Next.js 全栈项目 Vercel 上线部署全流程：从仓库到生产的可复用方案一套可复用的 Vercel 部署方案：环

Next.js 全栈项目 Vercel 上线部署全流程：从仓库到生产的可复用方案

本文基于真实生产实践抽象整理，已去除企业名称、域名、密钥与业务细节。下文以 NovaKit 为项目代号（Next.js App Router + API Routes + 定时任务 + 对象存储），适合作为中小团队「第一次上 Vercel」或「从自建机迁到 Serverless」的参考手册。

写在前面

很多团队本地 pnpm dev 跑得飞起，一到上线就卡在：

环境变量漏配，Preview 能跑、Production 500；
构建脚本依赖本地文件，CI 里直接挂；
大静态资源 / Serverless 超时，首屏慢或接口断流；
域名、HTTPS、Cron 各搞各的，没有一张「全流程清单」。

这篇文章给一套 可照抄的 Vercel 上线流程：不绑定某一家云厂商控制台，只讲「Git → Vercel → 环境 → 构建 → 域名 → 验收 → 回滚」。

一、方案总览

1.1 目标

目标	说明
自动化部署	`git push` 触发 Preview；合并主分支触发 Production
环境隔离	Development / Preview / Production 三套变量
可观测	每次部署有独立 URL、构建日志、Runtime 日志
可回滚	一键 Promote 历史版本或 Instant Rollback
低成本起步	个人/小团队 Hobby 即可验证，流量上来再升级 Pro

1.2 推荐架构（NovaKit 示例）

开发者本地
    │
    │ git push
    ▼
GitHub / GitLab 仓库
    │
    │ Webhook
    ▼
┌─────────────────────────────────────┐
│           Vercel Platform            │
│  ┌─────────┐  ┌──────────────────┐ │
│  │  Build   │→ │ Edge + Node Fn   │ │
│  │ next build│  │ /api/*  Route    │ │
│  └─────────┘  └──────────────────┘ │
│         │              │            │
│         ▼              ▼            │
│   静态资源 CDN    Serverless 执行    │
└─────────────────────────────────────┘
    │
    ├── Preview URL（每个 PR / 分支）
    └── Production（自定义域名 + 默认 *.vercel.app）

技术栈假设（可替换）：

框架：Next.js 15+ / 16，App Router
包管理：pnpm
运行时：Node.js Serverless Functions（默认）或 Edge（按路由配置）
存储：Vercel Blob / 外部 S3 兼容（经环境变量接入）
定时任务：vercel.json 声明 Cron

二、上线前检查清单（Preflight）

在点「Deploy」之前，建议团队过一遍：

2.1 仓库与构建

package.json 中 build 命令可在 干净环境 执行（无本地绝对路径）
构建不依赖「仅本机存在」的文件；生成物走 scripts/ 或 CI 步骤
engines.node 与 Vercel 默认 Node 版本一致（或在项目设置中锁定）
大文件（模型、字体、样本数据）放 public/ 或对象存储，避免打进 Serverless bundle

2.2 环境变量

列出全部 process.env.* 引用，区分 构建时 / 运行时
敏感项（API Key、数据库 URL）只进 Vercel Environment Variables，不进 Git
客户端可见变量使用 NEXT_PUBLIC_ 前缀，其余默认仅服务端

2.3 Next.js 特有问题

Server Component / Client Component 边界清晰，避免在 RSC 里引浏览器 API
长耗时 API（转码、大文件）评估 maxDuration 与 Fluid Compute（Pro）
流式接口（SSE）确认 Runtime 与超时配置

2.4 合规与安全

.env*、密钥文件在 .gitignore 中
Preview 环境若连真实库，需防误写（独立库或只读账号）

三、全流程分步（推荐顺序）

阶段 0：安装 CLI 并登录（可选但强烈建议）

pnpm add -g vercel
vercel login

CLI 适合：本地拉环境变量、手动触发部署、查日志。日常仍可以只用 Dashboard。

阶段 1：导入 Git 仓库

打开 Vercel Dashboard → Add New Project
选择 Git 提供方，授权组织/个人仓库
选中 NovaKit 对应仓库（示例名：org/novakit-web）
确认 Framework Preset 为 Next.js（通常自动识别）

团队习惯：

主分支：main 或 master → Production
功能分支 / PR → Preview Deployment（独立 URL）

阶段 2：配置构建命令与输出

Dashboard → Project → Settings → General → Build & Development Settings

项	典型值
Framework Preset	Next.js
Build Command	`pnpm build` 或 `npm run build`
Install Command	`pnpm install`（留空则自动推断）
Output Directory	留空（Next.js 由框架插件处理）
Root Directory	monorepo 子目录时填写，如 `apps/web`

NovaKit 示例 package.json：

{
  "scripts": {
    "dev": "next dev",
    "build": "node scripts/prebuild.mjs && next build",
    "start": "next start"
  }
}

要点：prebuild 里做索引生成、字体拉取等，必须在 CI 可重复执行。

阶段 3：环境变量（核心）

路径：Settings → Environment Variables

建议三张表维护（团队内部 Wiki）：

变量名	Development	Preview	Production	说明
`DATABASE_URL`	本地 Docker	预览库	生产库	服务端
`LLM_API_KEY`	测试 Key	测试 Key	生产 Key	服务端
`NEXT_PUBLIC_APP_URL`	localhost	自动 Preview URL	正式域名	客户端

操作方式：

# 从 Vercel 拉取到本地（勿提交 .env.local）
vercel env pull .env.local

# 添加变量（示例）
vercel env add LLM_API_KEY production

常见翻车：

Production 漏配 → 线上 500，Preview 正常
改了变量但没 Redeploy → 旧实例仍用旧值
把 Secret 写进 NEXT_PUBLIC_ → 泄露到浏览器

阶段 4：首次部署与验证 Preview

# 方式 A：推分支自动部署
git push origin feat/initial-deploy

# 方式 B：CLI 手动（当前目录）
vercel        # Preview
vercel --prod # Production（确认后再用）

部署完成后得到：

Preview:  https://novakit-web-xxx-team.vercel.app
Production: https://novakit-web.vercel.app（或自定义域）

验收项：

首页与核心路由 200
带鉴权的 API 在 Preview 环境行为符合预期
构建日志无 Error，Warnings 中关注 bundle 体积
Lighthouse / Web Vitals 抽样（可选）

阶段 5：自定义域名与 HTTPS

路径：Settings → Domains

添加根域或子域，如 app.example.com
按提示在 DNS 添加 CNAME 或 A 记录
Vercel 自动签发与续期 HTTPS 证书

建议：

Production 固定一个主域；Preview 继续用 *.vercel.app
需要「仅内网访问」时，配合 Vercel Authentication 或上游 WAF，而不是裸奔 Preview URL

阶段 6：`vercel.json` 平台能力（按需）

根目录 vercel.json 声明与框架无关的平台行为：

{
  "crons": [
    {
      "path": "/api/cron/cleanup",
      "schedule": "0 3 * * *"
    }
  ],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "no-store" }
      ]
    }
  ]
}

Cron 注意：

Hobby 有次数与精度限制，生产清理类任务要评估配额
Cron 路由需自行校验 Authorization: Bearer ${CRON_SECRET}，防被扫

API 超时（Next.js Route）：

// app/api/heavy-job/route.ts
export const maxDuration = 60; // 秒，受套餐上限约束
export const runtime = 'nodejs'; // 或 'edge'，按依赖选择

阶段 7：Production 晋升与 Git 流

阶段 8：上线后监控与回滚

手段	用途
Deployments 列表	对比构建时间、Commit、环境
Runtime Logs	查 500、超时、第三方 API 失败
Analytics / Speed Insights	LCP、CLS、慢路由（可选开通）
Instant Rollback	秒级切回上一 Production

回滚不等于「修数据」：若新版本写了脏数据，仍需 DB 侧处理。

四、NovaKit 场景化配置示例

4.1 仅前端 + 轻 API

默认 Next.js 构建即可
静态页可走 CDN 缓存；fetch 配合 revalidate 或 Cache Components（Next 16+）

4.2 AI 对话 + SSE 流式

Route Handler 返回 ReadableStream
确认未在 Edge 使用仅 Node 支持的 SDK
客户端断开时服务端 Abort，避免 Function 空转

4.3 大文件上传 / 转码

不要经 Serverless 代理整文件；浏览器直传对象存储（STS / 预签名 URL）
API 只负责签发凭证与写元数据
长任务拆为异步 Job + 轮询或 Webhook

4.4 定时清理（Blob / 临时文件）

vercel.json Cron 调 /api/cron/cleanup
清理逻辑幂等，日志打删除数量便于审计

五、常见问题与排障

Q1：Preview 正常，Production 500

优先查： Production 环境变量是否齐全；是否 redeploy；是否连了生产库/schema 不一致。

Q2：构建成功，运行时 `MODULE_NOT_FOUND`

原因： 依赖放在 devDependencies 但被生产代码引用；或 monorepo 未正确设置 Root Directory。

Q3：Serverless 超时

手段： 缩短链路、异步化、maxDuration、升级套餐、Fluid Compute；勿在单请求内同步处理百 MB 文件。

Q4：静态资源 404

检查： 是否放在 public/；构建是否生成到 .next；是否误配 assetPrefix。

Q5：Cron 没触发

检查： vercel.json 是否合并到部署分支；路径是否 POST/GET 与实现一致；Hobby 配额。

Q6：域名已配，仍跳旧站

检查： DNS 传播；是否混用根域 CNAME；CDN 缓存层是否另有配置。

六、成本与套餐选型（简表）

场景	建议
个人 Demo / 内测	Hobby
正式产品、团队协作、Cron/日志保留	Pro
强合规、SSO、SLA	Enterprise

计费关注点：带宽、Function 执行时间、构建分钟数、团队成员数。大模型 API 费用通常在 Vercel 之外另算。

七、一套可打印的「上线日」Runbook

T-1  Preflight 清单评审（构建、env、密钥、大文件）
T0   合并 main，等待 Production 构建 Ready
T0+5 冒烟：首页、登录、核心 API、Cron 手动触发一次
T0+10 域名抽检 HTTPS、移动端、弱网
T+1h  看 Error Rate、慢查询、外部 API 配额
若失败 → Promote 上一版本 + 复盘 env/迁移

八、与自建机 / 容器部署对比（为何选 Vercel）

维度	Vercel	自建 K8s/VM
上手速度	快，Git 即用	慢，需运维体系
HTTPS/CDN	内置	需自建或再接 CDN
弹性伸缩	按请求自动	需 HPA 等配置
定制 OS/长驻进程	弱	强
供应商锁定	有	低

适合：Web 前端 + Next 全栈 API、希望少运维的团队。不适合：强 GPU 训练、超低延迟 UDP、复杂有状态中间件集群。

九、总结

Vercel 上线不是「点一下 Deploy」，而是一条 工程化流水线：

Preflight：构建可复现、env 清单、Next 边界
Link：Git 导入 + 构建命令 + Node 版本
Env：三环境变量 + 禁止泄露 NEXT_PUBLIC_
Deploy：先 Preview 验收，再 Production
Domain：DNS + 自动 HTTPS
Platform：vercel.json Cron / headers / maxDuration
Operate：日志、回滚、Cron 与成本复盘

把这份 Runbook 放进团队 Wiki，新人也能在半天内独立完成 NovaKit 级项目的首次 Production 发布。

Next.js 全栈项目 Vercel 上线部署全流程：从仓库到生产的可复用方案