部署到 Vercel

Vercel 是将 ProductReady 部署到生产环境最快、最简单的方式。本指南将引导您完成整个过程。

为什么选择 Vercel？

无需配置
自动 HTTPS 和 CDN
免费套餐包含业余项目
每次 git push 自动部署
由 Next.js 的创建者构建

前置条件

部署前，您需要：

✅ GitHub 账户（用于连接您的仓库）
✅ Vercel 账户（免费注册）
✅ 数据库（Neon、Supabase 或其他 PostgreSQL）
✅ 准备好环境变量（见下文）

快速部署（5 分钟）

将代码推送到 GitHub

# 初始化 git（如果还没有）
git init
git add .
git commit -m "Initial commit"

# 在 GitHub 上创建仓库，然后：
git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPO.git
git push -u origin main

连接到 Vercel

访问 vercel.com/new
点击 "Import Git Repository"（导入 Git 仓库）
选择您的 ProductReady 仓库
点击 "Import"（导入）

首次使用？Vercel 会要求安装 GitHub App - 点击 "Install"（安装）

配置项目

Vercel 会自动检测 Next.js。验证这些设置：

Framework Preset（框架预设）：Next.js
Root Directory（根目录）：apps/productready（如果在 monorepo 中）或 ./（如果是独立项目）
Build Command（构建命令）：pnpm build（或 npm run build）
Output Directory（输出目录）：.next（自动检测）

点击 "Deploy"（部署）- 不用担心，第一次会失败（我们需要环境变量！）

添加环境变量

第一次部署失败后，前往： Project Settings → Environment Variables（项目设置 → 环境变量）

添加这些必需的变量：

# 数据库
PG_DATABASE_URL=postgresql://user:pass@host:5432/db

# 认证
BETTER_AUTH_SECRET=your-secret-32-chars-minimum
BETTER_AUTH_URL=https://your-app.vercel.app

# 应用 URL
NEXT_PUBLIC_APP_URL=https://your-app.vercel.app

重要：BETTER_AUTH_URL 必须是您的实际 Vercel URL（例如 https://productready.vercel.app）

可选变量（如果需要）：

# OAuth（可选）
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

# Stripe（如果使用支付）
STRIPE_SECRET_KEY=sk_live_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# 其他
API_SECRET_KEY=your-api-secret-key

重新部署

添加环境变量后：

前往 Deployments（部署）标签
点击最新部署旁的 "..."
选择 "Redeploy"（重新部署）

等待 2-3 分钟...

✅ 成功！ 您的应用现已上线！

数据库设置

选项 1：Neon（推荐）

Neon 提供免费的 PostgreSQL，非常适合 Vercel。

步骤：

在 neon.tech 创建账户
创建新项目
复制连接字符串
重要：使用池化连接（端口 6543）：
```
******host:6543/db?sslmode=require
```

选项 2：Supabase

Supabase 提供免费的 PostgreSQL + 更多功能。

步骤：

在 supabase.com 创建项目
前往 Settings → Database（设置 → 数据库）
复制 "Connection pooling"（连接池）字符串（不是直接连接）
添加到 Vercel 作为 PG_DATABASE_URL

选项 3：Railway

Railway - 简单部署。

步骤：

在 Railway 创建 PostgreSQL 数据库
复制 DATABASE_URL
粘贴到 Vercel

运行迁移

部署后，您需要运行数据库迁移。

方法 1：使用 Vercel CLI（推荐）

# 安装 Vercel CLI
npm i -g vercel

# 登录
vercel login

# 链接项目
vercel link

# 运行迁移
vercel env pull .env.local
pnpm db:migrate

方法 2：从本地运行

# 使用生产数据库 URL
PG_DATABASE_URL="your-production-db-url" pnpm db:migrate

方法 3：使用 GitHub Actions

创建 .github/workflows/migrate.yml：

name: Run Migrations
on:
  workflow_dispatch: # 手动触发

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 24.18.0
          cache: 'pnpm'
      
      - run: pnpm install
      - run: pnpm db:migrate
        env:
          PG_DATABASE_URL: ${{ secrets.PG_DATABASE_URL }}

自定义域名

添加域名

在 Vercel 项目中，前往 Settings → Domains（设置 → 域名）

输入您的域名（例如 myapp.com）并点击 Add（添加）

按照 Vercel 的说明更新您的 DNS 记录

选项 A：使用 Vercel 名称服务器（推荐）

将域名的名称服务器更新为 Vercel 的

选项 B：使用 CNAME/A 记录

添加 Vercel 提供的 DNS 记录

等待 DNS 传播（最多 24 小时，通常是几分钟）

更新环境变量

添加域名后，更新这些变量：

BETTER_AUTH_URL=https://myapp.com
NEXT_PUBLIC_APP_URL=https://myapp.com

然后重新部署。

Monorepo 部署

如果 ProductReady 在 monorepo 中（例如 apps/productready）：

Vercel 配置

在项目根目录创建 vercel.json：

{
  "buildCommand": "cd apps/productready && pnpm build",
  "devCommand": "cd apps/productready && pnpm dev",
  "installCommand": "pnpm install",
  "framework": "nextjs",
  "outputDirectory": "apps/productready/.next"
}

Root Directory

在 Vercel 项目设置中：

Root Directory: apps/productready

环境变量最佳实践

开发 vs 生产

在 Vercel 中为每个环境设置不同的值：

Production（生产）：用于 main 分支
Preview（预览）：用于 PR 和其他分支
Development（开发）：用于本地（不常用）

提示：使用不同的数据库用于预览/生产以避免数据污染

敏感值

永远不要提交 .env 文件到 Git！

# .gitignore
.env
.env.local
.env.production.local

持续部署

Vercel 在每次推送时自动部署：

分支

main → 生产部署
其他分支 → 预览部署

预览部署

每个 PR 都会获得唯一的 URL：

https://productready-git-feature-branch-yourname.vercel.app

非常适合：

✅ 测试功能
✅ 在合并前审查
✅ 与团队分享

性能优化

图片优化

Vercel 自动优化图片。确保使用 next/image：

import Image from 'next/image';

// ✅ 优化
<Image src="/logo.png" width={200} height={100} alt="Logo" />

// ❌ 未优化
<img src="/logo.png" />

边缘函数

对于全局低延迟，使用边缘运行时：

// app/api/hello/route.ts
export const runtime = 'edge';

export async function GET() {
  return Response.json({ hello: 'world' });
}

ISR（增量静态再生）

缓存页面，同时保持新鲜：

// app/blog/[slug]/page.tsx
export const revalidate = 3600; // 每小时重新验证

export default function BlogPost() {
  // ...
}

监控和日志

查看日志

Vercel 仪表板 → Deployments → 点击部署 → Function Logs（函数日志）

实时日志

# 使用 Vercel CLI
vercel logs
vercel logs --follow # 实时流式传输

分析

启用 Vercel Analytics：

项目设置 → Analytics（分析）
启用 Web Analytics（网络分析）
查看流量、性能、Web Vitals

故障排除

部署失败

检查构建日志：

Deployments → 点击失败的部署
查看 Build Logs（构建日志）

常见问题：

"Module not found"（未找到模块）

# 确保所有依赖在 package.json 中
pnpm install
git add package.json pnpm-lock.yaml
git commit -m "Update dependencies"

"Environment variable not set"（环境变量未设置）

检查 Project Settings → Environment Variables
确保所有必需变量都已设置
重新部署

"Database connection failed"（数据库连接失败）

验证 PG_DATABASE_URL 格式
使用池化连接（Neon 端口 6543）
检查数据库是否可从外部访问

慢速构建

优化依赖：

# 使用 pnpm（比 npm 快）
pnpm install

# 清理未使用的依赖
pnpm prune

缓存 node_modules： Vercel 自动缓存 - 但如果有问题：

Deployments → ... → Redeploy（重新部署）
选中 "Clear cache"（清除缓存）

404 错误

动态路由：确保使用正确的 [[...slug]] 语法

API 路由：检查文件位置 app/api/*/route.ts

安全性

环境变量

永远不要在客户端代码中暴露秘密：

// ❌ 危险 - 暴露秘密
const apiKey = process.env.API_SECRET_KEY;

// ✅ 安全 - 仅服务器端
// app/api/route.ts
export async function POST() {
  const apiKey = process.env.API_SECRET_KEY; // OK - 服务器端
  // ...
}

CORS

如果需要 CORS（用于外部 API）：

// app/api/route.ts
export async function OPTIONS() {
  return new Response(null, {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    },
  });
}

速率限制

保护您的 API：

import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '10 s'),
});

export async function POST(req: Request) {
  const ip = req.headers.get('x-forwarded-for') ?? 'unknown';
  const { success } = await ratelimit.limit(ip);
  
  if (!success) {
    return Response.json({ error: 'Too many requests' }, { status: 429 });
  }
  
  // 处理请求...
}