pjt222 部署到 Vercel
将 Next.js 应用程序以生产配置部署到 Vercel。
适用场景
- 首次部署 Next.js 应用
- 为 Pull Request 设置预览部署
- 配置自定义域名
- 管理生产环境变量
输入
- 必需：本地构建成功的 Next.js 应用
- 必需：GitHub 仓库（推荐）或本地项目
- 可选：自定义域名
- 可选：生产环境变量
步骤
第 1 步：验证本地构建
npm run build
预期结果： 构建成功，无任何错误。
失败处理： 部署前修复构建错误。常见问题：TypeScript 错误、缺少依赖项、无效导入。
第 2 步：安装 Vercel CLI
npm install -g vercel
预期结果： vercel 命令全局可用，vercel --version 打印已安装版本。
失败处理： 如果出现权限错误，使用 sudo npm install -g vercel 或配置 npm 使用用户本地前缀。使用 node --version 验证 Node.js 已安装。
第 3 步：关联并部署
# Login to Vercel
vercel login
# Deploy (first time: creates project)
vercel
# Follow prompts:
# - Set up and deploy? Y
# - Which scope? (select your account)
# - Link to existing project? N (for new projects)
# - Project name: my-app
# - Directory: ./
# - Override settings? N
预期结果： 提供预览 URL（如 https://my-app-xxx.vercel.app）。
失败处理： 如果 vercel login 失败，检查网络连接并尝试基于浏览器的认证。如果部署失败，查看构建输出中的错误——Vercel 使用干净环境，所有依赖项必须在 package.json 中声明。
第 4 步：配置环境变量
# Add environment variables
vercel env add DATABASE_URL production
vercel env add API_KEY production preview
# List environment variables
vercel env ls
或通过 Vercel 控制台配置：项目设置 > 环境变量。
预期结果： vercel env ls 显示所有必需的环境变量，已针对正确的环境（生产、预览、开发）配置。
失败处理： 如果变量在运行时未出现，验证目标环境是否匹配（生产 vs 预览）。添加变量后重新部署——现有部署不会自动获取新变量。
第 5 步：部署到生产环境
vercel --prod
预期结果： 生产 URL 可用（如 https://my-app.vercel.app）。
失败处理： 使用 vercel logs 或在 Vercel 控制台中检查部署日志。常见问题包括生产环境缺少环境变量，以及构建命令与本地设置不同。
第 6 步：连接 GitHub 实现自动部署（推荐）
- 访问 https://vercel.com/new
- 导入您的 GitHub 仓库
- Vercel 将自动在以下时机部署：
- 推送到 main → 生产部署
- Pull Request → 预览部署
预期结果： Vercel 控制台显示已连接 GitHub 仓库，后续推送到 main 自动触发生产部署。
失败处理： 如果仓库未出现在导入列表中，检查 Vercel GitHub 应用是否有权访问该仓库。访问 GitHub 设置 > 应用程序 > Vercel 并授予访问权限。
第 7 步：配置自定义域名
vercel domains add my-domain.com
或通过控制台：项目设置 > 域名。
按照 Vercel 的指示更新 DNS 记录（通常是 CNAME 或 A 记录）。
预期结果： vercel domains ls 显示自定义域名已配置，DNS 传播后（最长 48 小时），域名解析到 Vercel 部署。
失败处理： 如果域名显示"配置无效"，验证 DNS 记录与 Vercel 的指示完全匹配。使用 dig my-domain.com 或在线 DNS 检查工具确认传播。
第 8 步：优化配置
在项目根目录创建 vercel.json 进行高级设置：
{
"framework": "nextjs",
"regions": ["iad1"],
"headers": [
{
"source": "/api/(.*)",
"headers": [
{ "key": "Cache-Control", "value": "no-store" }
]
}
]
}
预期结果： vercel.json 保存在项目根目录，下次部署时采用该配置（在 Vercel 控制台构建日志中可见）。
失败处理： 如果配置被忽略，使用 jq . vercel.json 验证 JSON 是否合法。检查 Vercel 文档中您的框架版本，某些设置可能已移至 next.config.ts。
验证清单
-
npm run build在本地成功 - 预览部署可正常访问
- 生产部署正确提供应用服务
- 环境变量在生产中可用
- 自定义域名解析正常（如已配置）
- GitHub 集成在推送时触发部署
常见问题
- Vercel 构建失败但本地成功：Vercel 使用干净环境。确保所有依赖项在
package.json中，而非全局安装。 - 环境变量缺失：变量必须添加到 Vercel，而非仅在
.env.local中。不同环境（生产、预览、开发）有独立的变量集。 - Node.js 版本不匹配：在项目设置或
package.json的engines字段中设置 Node.js 版本。 - 部署体积过大：Vercel 有大小限制。使用
.vercelignore排除不必要的文件。 - API 路由超时：Vercel 免费套餐的无服务器函数超时为 10 秒。优化代码或升级套餐。
相关技能
scaffold-nextjs-app— 创建待部署的应用setup-tailwind-typescript— 部署前配置样式configure-git-repository— 自动部署集成的 Git 设置