在 Vercel 上部署 Next.js 并使用预览环境

目标#

把 Next.js 仓库连接到 Vercel，让每个分支或 Pull Request 获得独立 Preview URL，并在合并主分支后更新 Production。

前置条件#

• Next.js 项目在本地能完成安装、检查和生产构建。
• 代码已推送到 Vercel 支持的 Git 提供商。
• 已区分预览与生产所需的外部服务和环境变量。

导入项目#

1. 在 Vercel Dashboard 选择 Add New > Project。
2. 连接 Git 提供商并导入目标仓库。
3. 确认 Framework Preset 识别为 Next.js。
4. 如果项目位于 monorepo，设置正确的 Root Directory。
5. 检查 Build Command、Install Command 和 Output Directory；没有特殊需求时保留框架默认值。

配置环境变量#

在 Project Settings 中分别为 Development、Preview 和 Production 设置变量。服务端密钥不要使用 NEXT_PUBLIC_ 前缀；该前缀的值会进入浏览器可见的客户端代码。

本地开发可以拉取项目环境配置，但不要提交生成的 .env.local：

vercel env pull .env.local

Preview 应尽量连接隔离的测试数据库和第三方沙箱，避免预览分支修改生产数据。

触发预览部署#

创建分支并推送：

git switch -c feature/example
git push -u origin feature/example

Vercel 会为提交生成 Preview Deployment。创建 Pull Request 后，把 Preview URL 用于产品确认、视觉检查和端到端测试。

发布到 Production#

默认情况下，Production Branch 通常是仓库主分支。合并通过检查的 Pull Request 后，Vercel 构建并切换生产部署。是否静态生成、服务端渲染或运行 Edge/Node 函数由 Next.js 路由实现决定，不能一概视为静态页面。

验证#

1. 构建日志中没有类型、lint 或依赖错误。
2. Preview 使用测试环境变量，Production 使用生产变量。
3. 检查主要页面、API、图片优化、重定向和缓存行为。
4. 在 Vercel Functions 与 Runtime Logs 中确认没有新增异常。

回滚#

Vercel 保留历史 Deployment。生产异常时可在 Dashboard 中把已验证的旧 Deployment 重新提升为 Production，同时修复主分支，避免下一次自动部署重新引入问题。

参考#

• Vercel：Deploying Git repositories
• Vercel environments
• Next.js deployment