安装指南

本指南将帮助你安装和配置 vibetake 开发环境。我们提供了多种安装方式，你可以选择最适合你的方式开始。

📋 系统要求

在开始之前，请确保你的系统满足以下要求：

必需环境

Node.js 18.0 或更高版本（推荐 20.x LTS）
npm 9.0 或更高版本（或 yarn 1.22+、pnpm 8.0+）
Git 2.0 或更高版本

检查系统环境

# 检查 Node.js 版本
node --version
# 应该显示 v18.0.0 或更高

# 检查 npm 版本
npm --version
# 应该显示 9.0.0 或更高

# 检查 Git 版本
git --version
# 应该显示 2.0.0 或更高

环境管理工具（推荐）

如果你需要管理多个 Node.js 版本，推荐使用：

macOS/Linux:

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重启终端后安装 Node.js
nvm install 20
nvm use 20
nvm alias default 20

Windows:

# 使用 Chocolatey 安装 nvm-windows
choco install nvm

# 或下载安装包
# https://github.com/coreybutler/nvm-windows/releases

🚀 安装方式

我们提供了多种安装方式，选择最适合你的：

方式一：使用 vibetake CLI（推荐）

这是最简单快捷的安装方式，CLI 工具会自动处理项目初始化：

# 全局安装 vibetake CLI
npm install -g vibetake

# 验证安装
vibe --version

# 创建新项目（交互式）
vibe template

# 或直接指定项目名
vibe template my-awesome-project

# 进入项目目录
cd my-awesome-project

# CLI 会自动安装依赖，如果没有，手动安装
npm install

CLI 功能特性：

🎯 交互式项目配置
📦 自动依赖安装
🔧 环境变量模板生成
🗄️ 数据库自动初始化
🎨 可选功能模块选择

方式二：使用 create-next-app

# 使用官方脚手架
npx create-next-app@latest my-project --example "https://github.com/wangenius/vibetake-template"

# 进入项目目录
cd my-project

# 安装依赖
npm install

方式三：克隆 GitHub 仓库

适合需要完整控制项目初始化过程的开发者：

# 克隆仓库
git clone https://github.com/wangenius/vibetake-template.git my-project

# 进入项目目录
cd my-project

# 安装依赖
npm install

# 删除原有的 git 历史（推荐）
rm -rf .git

# 初始化新的 git 仓库
git init
git add .
git commit -m "Initial commit"

方式四：使用 GitHub 模板

适合直接在 GitHub 上创建项目：

访问 vibetake GitHub 仓库
点击绿色的 "Use this template" 按钮
选择 "Create a new repository"
填写仓库信息：
- Repository name: my-awesome-project
- Description: 项目描述
- Public/Private: 选择可见性
点击 "Create repository from template"
克隆到本地：

git clone https://github.com/your-username/my-awesome-project.git
cd my-awesome-project
npm install

方式五：使用包管理器模板

使用 yarn:

yarn create next-app my-project --example "https://github.com/wangenius/vibetake-template"
cd my-project
yarn install

使用 pnpm:

pnpm create next-app my-project --example "https://github.com/wangenius/vibetake-template"
cd my-project
pnpm install

方式六：下载 ZIP 文件

如果你不想使用 Git：

访问 GitHub 仓库
点击绿色的 "Code" 按钮
选择 "Download ZIP"
解压文件到你的项目目录
在项目目录中运行：

npm install

⚙️ 环境配置

安装完成后，需要配置环境变量和初始化数据库。

1. 创建环境变量文件

# 复制环境变量模板
cp .env.example .env.local

# 或者手动创建
touch .env.local

2. 配置环境变量

打开 .env.local 文件，配置以下变量：

基础配置（必需）

# .env.local

# 应用基础配置
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NODE_ENV="development"

# 数据库配置
DATABASE_URL="file:./dev.db"
# 或使用 Turso（云端 libSQL）
# DATABASE_URL="libsql://your-database-url"
# DATABASE_AUTH_TOKEN="your-auth-token"

# 认证配置
BETTER_AUTH_SECRET="your-super-secret-key-at-least-32-characters"
BETTER_AUTH_URL="http://localhost:3000"

可选服务配置

# AI 服务配置（可选）
OPENAI_API_KEY="sk-..."
# 或使用其他 AI 提供商
ANTHROPIC_API_KEY="sk-ant-..."
GOOGLE_AI_API_KEY="..."

# 支付配置（可选）
STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# 第三方认证（可选）
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# 邮件服务（可选）
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"

# 文件存储（可选）
UPLOADTHING_SECRET="sk_live_..."
UPLOADTHING_APP_ID="your-app-id"

3. 生成安全密钥

# 生成 32 字符的随机密钥
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# 或使用 openssl
openssl rand -hex 32

4. 初始化数据库

# 生成数据库迁移文件
npm run generate

# 执行数据库迁移
npm run migrate

# 或者直接推送模式到数据库（开发环境推荐）
npm run db:push

数据库选项

本地开发（SQLite）:

DATABASE_URL="file:./dev.db"

云端部署（Turso）:

# 1. 安装 Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash

# 2. 登录 Turso
turso auth login

# 3. 创建数据库
turso db create my-app-db

# 4. 获取连接信息
turso db show my-app-db

# 5. 创建访问令牌
turso db tokens create my-app-db

# 6. 更新环境变量
DATABASE_URL="libsql://[your-database-url]"
DATABASE_AUTH_TOKEN="[your-auth-token]"

5. 验证配置

# 检查环境变量是否正确加载
npm run dev

# 在另一个终端检查数据库连接
npm run db:studio

🎯 启动开发服务器

配置完成后，启动开发服务器：

# 启动开发服务器（使用 Turbopack）
npm run dev

# 或使用其他包管理器
yarn dev
pnpm dev

# 不使用 Turbopack（如果遇到兼容性问题）
next dev

开发服务器特性：

🔥 热重载 - 代码更改实时生效
⚡ Turbopack - 极速构建和更新
🔍 错误提示 - 详细的错误信息和堆栈跟踪
📱 响应式 - 自动适配不同设备

打开浏览器访问 http://localhost:3000 查看你的应用。

可用的开发命令

# 开发相关
npm run dev          # 启动开发服务器
npm run build        # 构建生产版本
npm run start        # 启动生产服务器
npm run lint         # 代码检查
npm run format       # 代码格式化

# 数据库相关
npm run generate     # 生成数据库迁移
npm run migrate      # 执行数据库迁移
npm run db:push      # 推送模式到数据库
npm run db:studio    # 打开数据库管理界面

✅ 验证安装

按照以下步骤验证安装是否成功：

1. 检查页面加载

访问以下页面确保正常显示：

首页: http://localhost:3000
- ✅ 页面正常加载
- ✅ 样式正确显示
- ✅ 无控制台错误
文档页面: http://localhost:3000/docs
- ✅ 文档导航正常
- ✅ 搜索功能可用
- ✅ 代码高亮正常
认证页面: http://localhost:3000/login
- ✅ 登录表单显示
- ✅ 表单验证正常

2. 检查数据库连接

# 查看数据库文件是否创建（SQLite）
ls -la *.db

# 检查数据库表结构
npm run db:studio
# 应该在浏览器中打开 Drizzle Studio

验证数据库：

✅ 数据库文件存在
✅ 表结构正确创建
✅ 可以在 Studio 中查看数据

3. 测试构建

# 构建生产版本
npm run build

# 检查构建输出
# 应该看到类似输出：
# ✓ Compiled successfully
# ✓ Linting and checking validity of types
# ✓ Collecting page data
# ✓ Generating static pages

# 启动生产服务器
npm start

4. 功能测试清单

页面路由 - 所有页面可以正常访问
样式加载 - Tailwind CSS 样式正常
组件渲染 - shadcn/ui 组件正常显示
数据库连接 - 可以连接和查询数据库
环境变量 - 配置正确加载
热重载 - 代码更改实时生效
构建成功 - 生产构建无错误
TypeScript - 类型检查通过

5. 性能检查

# 检查包大小
npm run build
# 查看 .next/static 目录大小

# 使用 Lighthouse 检查性能（可选）
# 在 Chrome DevTools 中运行 Lighthouse 审计

性能指标目标：

🎯 First Contentful Paint < 1.5s
🎯 Largest Contentful Paint < 2.5s
🎯 Cumulative Layout Shift < 0.1
🎯 First Input Delay < 100ms

🔧 故障排除

Node.js 版本问题

问题: Node.js 版本过低或不兼容

# 错误信息示例
Error: This package requires Node.js version 18 or higher

解决方案:

# 使用 nvm 管理版本
nvm install 20
nvm use 20
nvm alias default 20

# 验证版本
node --version  # 应该显示 v20.x.x

依赖安装问题

问题: 依赖安装失败或版本冲突

# 常见错误
npm ERR! peer dep missing
npm ERR! ERESOLVE unable to resolve dependency tree

解决方案:

# 方案 1: 清除缓存重新安装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

# 方案 2: 使用 --legacy-peer-deps
npm install --legacy-peer-deps

# 方案 3: 使用 yarn 或 pnpm
yarn install
# 或
pnpm install

端口冲突

问题: 3000 端口被占用

Error: listen EADDRINUSE: address already in use :::3000

解决方案:

# 方案 1: 使用其他端口
npm run dev -- --port 3001

# 方案 2: 查找并终止占用进程
lsof -ti:3000 | xargs kill -9

# 方案 3: 设置环境变量
PORT=3001 npm run dev

数据库连接问题

问题: 数据库连接失败

Error: Database connection failed

解决方案:

# 检查环境变量
cat .env.local

# 重新初始化数据库
rm -f *.db
npm run db:push

# 检查数据库权限（Linux/macOS）
chmod 664 dev.db

TypeScript 错误

问题: TypeScript 类型错误

Type error: Cannot find module or its corresponding type declarations

解决方案:

# 重新安装类型定义
npm install --save-dev @types/node @types/react @types/react-dom

# 重启 TypeScript 服务器（VS Code）
# Ctrl+Shift+P -> "TypeScript: Restart TS Server"

# 检查 tsconfig.json 配置
npx tsc --noEmit

构建失败

问题: 生产构建失败

Error: Build failed with errors

解决方案:

# 检查 TypeScript 错误
npm run lint

# 清除 Next.js 缓存
rm -rf .next

# 重新构建
npm run build

# 检查环境变量
echo $NODE_ENV

样式问题

问题: Tailwind CSS 样式不生效

# 样式没有应用或显示异常

解决方案:

# 检查 Tailwind 配置
cat tailwind.config.js

# 重启开发服务器
npm run dev

# 检查 CSS 导入
# 确保在 globals.css 中导入了 Tailwind

权限问题（Linux/macOS）

问题: 文件权限错误

Error: EACCES: permission denied

解决方案:

# 修复 npm 权限
sudo chown -R $(whoami) ~/.npm

# 或使用 nvm 避免权限问题
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

🚀 下一步

安装完成后，建议按以下顺序学习：

1. 基础使用

快速开始 - 5 分钟了解基本功能
项目结构 - 熟悉代码组织方式

2. 核心功能

认证系统 - 用户登录注册
数据库操作 - 数据存储和查询
UI 组件 - 界面组件使用

3. 高级功能

AI 集成 - 添加 AI 功能
支付系统 - 集成支付功能
部署指南 - 发布到生产环境

4. 开发工具推荐

VS Code 扩展:

ES7+ React/Redux/React-Native snippets
Tailwind CSS IntelliSense
TypeScript Importer
Auto Rename Tag
Prettier - Code formatter
GitLens

浏览器工具:

React Developer Tools
Redux DevTools (如果使用 Redux)
Lighthouse (性能检测)

命令行工具:

# 安装有用的全局工具
npm install -g @biomejs/biome
npm install -g typescript
npm install -g vercel

现在你已经成功安装了 vibetake，开始构建你的应用吧！ 🎉

安装指南

On this page