Vercel 部署指南

本文档介绍如何将项目部署到 Vercel 平台。

前置条件

Vercel 账户: 在 vercel.com 注册账户
Vercel CLI: 安装 Vercel 命令行工具
环境变量: 准备好生产环境所需的环境变量

安装 Vercel CLI

# 全局安装 Vercel CLI
pnpm add -g vercel

# 或使用 npm
npm install -g vercel

快速部署

方式一：使用部署脚本（推荐）

# 1. 首次部署前，关联 Vercel 项目
pnpm vercel:link

# 2. 检查环境变量配置
pnpm deploy:check-env

# 3. 部署到预览环境
pnpm deploy

# 4. 部署到生产环境
pnpm deploy:prod

方式二：直接使用 Vercel CLI

# 部署到预览环境
vercel

# 部署到生产环境
vercel --prod

方式三：通过 Vercel Dashboard

访问 vercel.com/new
导入 GitHub/GitLab/Bitbucket 仓库
配置环境变量
点击 Deploy

配置说明

vercel.json 配置

项目根目录的 vercel.json 文件包含以下配置：

{
  "framework": "nextjs",
  "buildCommand": "pnpm build",
  "installCommand": "pnpm install",
  "regions": ["hkg1"],
  "functions": {
    "src/app/api/**/*.ts": {
      "maxDuration": 30
    }
  },
  "crons": [
    {
      "path": "/api/crontab/yearly-credits",
      "schedule": "0 0 1 * *"
    }
  ]
}

配置项说明

配置项	说明
`framework`	框架类型，Next.js
`buildCommand`	构建命令
`installCommand`	依赖安装命令
`regions`	部署区域，`hkg1` 为香港
`functions`	Serverless 函数配置
`crons`	定时任务配置

可用区域

区域代码	位置
`hkg1`	香港
`sin1`	新加坡
`nrt1`	东京
`sfo1`	旧金山
`iad1`	华盛顿
`fra1`	法兰克福

环境变量配置

必需的环境变量

在 Vercel Dashboard 的 Settings > Environment Variables 中配置：

数据库（至少配置一种）

# Turso/LibSQL（推荐用于 Serverless）
TURSO_DATABASE_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-auth-token

# PostgreSQL (Neon/Supabase/etc.)
POSTGRE_DATABASE_URL=postgresql://...

认证

BETTER_AUTH_SECRET=your-random-secret-key
BETTER_AUTH_URL=https://yourdomain.com/

邮件服务

RESEND_API_KEY=re_xxxxxxxxxx
RESEND_FROM_EMAIL=noreply@yourdomain.com

支付网关（可选）

# Stripe
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_PUBLISHABLE_KEY=pk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# 或 Creem
CREEM_API_KEY=ck_prod_xxx
CREEM_WEBHOOK_SECRET=whsec_xxx

使用 CLI 配置环境变量

# 添加环境变量
vercel env add BETTER_AUTH_SECRET

# 拉取环境变量到本地
vercel env pull .env.local

# 或使用 npm script
pnpm vercel:env:pull

定时任务 (Cron Jobs)

项目配置了以下定时任务：

任务	路径	执行时间	说明
年订阅积分发放	`/api/crontab/yearly-credits`	每月1日 00:00 UTC	为年订阅用户发放月度积分

配置定时任务 API 密钥

在环境变量中配置：

YEARLY_CREDITS_API_KEY=your-secure-api-key

部署脚本参数

vercel-deploy.ts

# 部署到预览环境（默认）
pnpm deploy

# 部署到生产环境
pnpm deploy:prod

# 仅构建，不部署
npx tsx scripts/deploy/vercel-deploy.ts --build-only

# 跳过构建，直接部署
npx tsx scripts/deploy/vercel-deploy.ts --skip-build

# 指定环境变量文件
npx tsx scripts/deploy/vercel-deploy.ts --env=.env.staging

check-env.ts

# 检查默认环境变量文件
pnpm deploy:check-env

# 检查指定文件
npx tsx scripts/deploy/check-env.ts --env=.env.production

# 严格模式（缺少必需变量时退出）
npx tsx scripts/deploy/check-env.ts --strict

自定义域名

在 Vercel Dashboard 进入项目设置
点击 Domains
添加自定义域名
按照提示配置 DNS 记录

DNS 配置示例

# A 记录
@ -> 76.76.21.21

# CNAME 记录
www -> cname.vercel-dns.com

部署检查清单

部署前请确认：

环境变量已在 Vercel 配置
数据库已创建并可访问
邮件服务已配置
支付网关 Webhook 已配置（如使用）
自定义域名已配置（如需要）
SSL 证书已生效

常见问题

Q: 部署失败，提示 "Build failed"

A: 检查以下几点：

确认 pnpm build 在本地能正常运行
检查环境变量是否完整
查看 Vercel 构建日志定位具体错误

Q: API 路由返回 500 错误

检查数据库连接配置
确认环境变量已正确设置
查看 Vercel Functions 日志

Q: 定时任务没有执行

确认 vercel.json 中的 cron 配置正确
检查 YEARLY_CREDITS_API_KEY 是否配置
注意 Vercel Hobby 计划不支持 Cron Jobs

Q: 如何回滚到之前的版本

A: 在 Vercel Dashboard 的 Deployments 页面，找到之前的部署，点击 "..." > "Promote to Production"