3.6 部署与发布（Deployment & Publishing）

3.6 部署与发布（Deployment & Publishing）

本节摘要：开发完成 ≠ 上线成功。本节讲清 Next.js 的两种主流部署方式：Vercel（平台托管，零配置）与自托管（Node 服务器/Docker），以及环境管理、CI/CD、监控与回滚——把"能跑的应用"变成"可靠的服务"。

本节导读

阅读完本节，你应当能够：

1. 用 Vercel 部署 Next.js 应用
2. 用 Docker 自托管部署
3. 管理多环境（开发/预发布/生产）
4. 配置 CI/CD 自动部署
5. 理解监控与回滚的基本实践

问题与直觉：部署的两种哲学

Next.js 应用有两种部署形态：

• Vercel 平台：连接 Git 仓库，push 即部署，自动处理边缘网络、预览环境、回滚——零运维；
• 自托管：自己装 Node/Docker，控制服务器、数据库、域名——完全掌控。

直觉类比：Vercel 像"托管公寓"（交钥匙入住，物业全包）；自托管像"自建房"（一切自己来，但房子完全属于你）。小团队/创业期用 Vercel 最快；有合规、成本、定制需求时自托管。

💡 关键直觉：Next.js 的构建产物是"纯静态 + 可选服务器"的混合——纯静态页面可以托管在任何静态托管（CDN）；有动态能力时需要一个 Node 服务器（或平台）。理解"什么内容需要服务器"，就理解了部署形态的选择。

核心原理：两种部署

2.1 Vercel 部署

# 1. 推送代码到 Git 仓库（GitHub/GitLab）
git init && git add -A && git commit -m "init"
git push origin main

# 2. 在 vercel.com 导入仓库，框架自动识别（Next.js）
# 3. 配置环境变量（数据库地址、密钥）
# 4. 部署完成，获得 https://xxx.vercel.app
​

Vercel 自动能力：

• 预览部署：每个 PR 自动生成预览环境，联调/评审用；
• 边缘网络：静态资源全球 CDN；
• 一键回滚：随时切回任意历史版本；
• 环境变量：按环境（production/preview）隔离。

2.2 自托管：Node 服务器

# 1. 构建
npm run build

# 2. 启动（生产模式）
npm run start -- -p 3000

# 3. 用进程管理器守护
npm install -g pm2
pm2 start "npm run start -- -p 3000" --name next-app
pm2 save && pm2 startup
​

可选独立产物（Docker 优化）：

// next.config.ts
const nextConfig = {
  output: "standalone",   // 生成最小独立产物（不含 node_modules 冗余）
};
​

2.3 Docker 部署

# Dockerfile
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]
​

docker build -t next-app .
docker run -d -p 3000:3000 -e DATABASE_URL=xxx next-app
​

注意：standalone 模式需配合 output: "standalone" 配置。

工程实践要点：环境与 CI/CD

3.1 多环境管理

隔离纪律：环境变量按环境注入（Vercel 的环境配置 / 自托管的 .env.production）。

3.2 CI/CD 流水线

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint
      - run: npm run test:unit

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      # 部署到自托管服务器（示例：rsync/ssh）
      - run: scp -r .next user@server:/app
​

CI 流程：提交 → lint+测试（闸门）→ 构建 → 部署 → 健康检查。

3.3 上线检查清单

• 生产环境变量已配置（密钥、数据库）
• npm run build 通过，无类型错误
• 环境变量中没有 NEXT_PUBLIC_ 前缀的敏感值
• 数据库迁移已执行
• 健康检查接口可访问
• 日志与监控已配置
• 回滚方案就绪（平台回滚/镜像 tag）

常见误区与排查

动手演练：从零部署到 Vercel

# 1. 准备 .env.example（提交）与 .env.production（平台配置）
# 2. 推送 GitHub
git remote add origin https://github.com/user/next-app.git
git push -u origin main

# 3. Vercel 导入（vercel.com → Add New Project → 选仓库）
# 4. 配置环境变量：DATABASE_URL、AUTH_SECRET
# 5. 点击 Deploy

# 6. 绑定域名（Settings → Domains）
# 7. 验证：访问线上域名，跑一遍核心流程
# 8. 配置 Vercel Analytics 监控 Web Vitals
​

从提交代码到线上可访问，全程在 Vercel 面板完成——这就是平台托管的效率。之后每次 push 到 main 自动部署，PR 自动出预览环境。

核心回顾

• 两种形态：Vercel（零运维托管）vs 自托管（Node/Docker 全掌控）。
• Vercel 能力：预览部署、边缘网络、一键回滚、环境变量隔离。
• 自托管：build + start + pm2 守护；standalone 产物优化 Docker。
• 多环境：开发/预览/生产，环境变量按环境隔离。
• CI/CD：lint+测试闸门 → 构建 → 部署 → 健康检查。
• 上线清单：环境变量、迁移、健康检查、日志监控、回滚方案。

深入理解：部署的完整生命周期

从代码到线上

部署平台对比

上线前的部署检查清单

1. 环境变量：生产密钥、数据库地址已配置；
2. 数据库迁移：执行 prisma migrate deploy；
3. 构建验证：npm run build 通过（无类型错误）；
4. 健康检查：/api/health 返回正常；
5. 监控：日志、错误追踪（Sentry）、性能指标已接；
6. 回滚方案：Vercel 一键回滚 / Docker 镜像 tag。

常见部署事故与预防

一句话：部署不是"最后一步"，而是"持续的过程"——环境、迁移、监控、回滚都在部署流程里，做全了才叫"可靠上线"。

常见问题速答

问：Vercel 和自托管怎么选？
小团队/快速上线/不想管服务器 → Vercel；合规要求/成本控制/完全掌控 → 自托管（Docker + 云服务器）。从 Vercel 起步，需要时再迁自托管。

问：自托管需要什么配置？
Node 20+、构建产物（build + start 或 standalone）、进程守护（pm2/systemd）、反向代理（Nginx，可选）、环境变量、HTTPS 证书。数据库单独部署（托管服务或云数据库）。

问：数据库迁移在生产怎么执行？
部署流程中加入迁移步骤：npx prisma migrate deploy（生产环境专用，只应用已有迁移）。迁移失败要先回滚代码再排查。

问：如何监控线上应用？
三件套：日志（控制台/日志服务）、错误追踪（Sentry）、性能指标（Vercel Analytics / 自建 RUM）。告警规则：错误率突增、可用性下降。

问：回滚怎么做？
Vercel 一键回滚到历史部署；自托管保留旧镜像/产物，出问题切换。"能快速回滚"比"部署得完美"更重要。