ZhenYu's 知识库

外观

在 Vercel 中使用

约 970 字大约 3 分钟

nextjsverceldeploy

2026-04-08

官网：https://vercel.com/docs

Vercel 是 Next.js 官方团队推出的部署平台。对于 Next.js 项目，它通常是最省配置、支持最完整的部署方案。

1. 为什么 Next.js 常配合 Vercel

优点：

  • 零配置识别 Next.js 项目
  • 自动支持 Preview Deployment
  • Git 推送即可触发部署
  • 对 Serverless / Edge / 静态资源支持完整
  • 自带域名、HTTPS、日志和环境变量管理

2. 最常见的使用方式

2.1 通过 Git 仓库部署

这是最推荐的方式。

步骤：

  1. 将 Next.js 项目推送到 GitHub、GitLab 或 Bitbucket
  2. 登录 Vercel
  3. 点击 New Project
  4. 导入你的 Git 仓库
  5. 确认框架识别为 Next.js
  6. 设置 Root Directory、环境变量等配置
  7. 点击 Deploy

部署完成后：

  • 推送到生产分支，触发 Production Deployment
  • 推送到其他分支，触发 Preview Deployment

这非常适合多人协作和 PR 预览。

2.2 使用 Vercel CLI

适合本地快速部署或未接入 Git 平台的场景。

安装：

pnpm add -g vercel

首次登录：

vercel login

在项目根目录执行：

vercel

发布到生产环境：

vercel --prod

常见用途：

  • 临时预览
  • 手动发布
  • 本地验证部署配置

3. 与 Next.js 项目配合的基本流程

3.1 本地开发

pnpm dev

3.2 构建检查

pnpm build

在推送到 Vercel 前，建议本地先保证 build 成功。

3.3 推送触发部署

git push origin main

默认情况下：

  • main 常被用作生产分支
  • 其他分支会生成预览环境

4. 环境变量配置

Next.js 项目常常需要配置数据库、鉴权、第三方 API Key 等环境变量。

在 Vercel 中可以为不同环境分别配置：

  • Production
  • Preview
  • Development

典型变量：

DATABASE_URL=xxxx
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
JWT_SECRET=xxxx

注意：

  • NEXT_PUBLIC_* 会暴露给浏览器端
  • 敏感信息不要加 NEXT_PUBLIC_
  • 修改环境变量后，通常需要重新部署，新值才会进入新的 Deployment

如果要把开发环境变量拉到本地：

vercel env pull

5. 域名与生产环境

部署完成后，Vercel 会给你一个默认域名，例如：

your-project.vercel.app

如果需要正式上线：

  1. 在项目设置中添加自定义域名
  2. 按提示配置 DNS
  3. 等待域名生效
  4. 验证 Production Deployment 是否绑定到该域名

Vercel 默认提供 HTTPS。

6. 常见部署模式

6.1 Preview Deployment

适用于：

  • PR 预览
  • 测试新功能
  • 给产品或测试同学确认页面效果

特点：

  • 每个分支或提交都可以有独立访问地址
  • 不影响正式环境

6.2 Production Deployment

适用于：

  • 正式上线
  • 对外访问流量入口

一般由生产分支触发，例如 main。

7. 常见问题

7.1 本地正常，Vercel 构建失败

优先检查：

  • Node.js 版本是否匹配
  • 环境变量是否缺失
  • 是否依赖本地文件路径或本地服务
  • pnpm build 在本地是否能通过

7.2 接口能本地访问，线上失败

常见原因：

  • 服务端环境变量未配置
  • 浏览器端误用了服务端密钥
  • 跨域或外部服务白名单未放行
  • 线上数据库或第三方服务不可达

7.3 页面更新了但线上还是旧内容

常见原因：

  • 命中了缓存
  • 使用了静态生成
  • revalidate 周期未到
  • 实际访问的不是最新的 Deployment

8. 实践建议

  • 新项目优先用 Git 集成部署
  • 所有分支都走 Preview Deployment
  • 合并到 main 前先检查预览环境
  • 把本地和线上 Node 版本保持一致
  • 环境变量按 Production / Preview / Development 分开管理
  • 先确认 pnpm build 成功，再提交代码

9. 参考资料