saas

GitHub Actions Vercel 部署完全指南：预览环境、生产发布、多项目与回滚策略

用 GitHub Actions 实现 Next.js/React 项目的自动化部署：PR 自动创建预览环境（Preview Deployment）、合并到 main 自动发布生产环境、多项目管理、部署回滚、自动评论、环境保护（Environment Protection）和审计日志配置。

Leeting Yan 2025-11-23 10 分钟阅读 4828 字

Vercel 自带 Git 集成，但在复杂场景下仍需 GitHub Actions：多项目 monorepo、自定义构建步骤、私有依赖、环境保护规则、以及需要在部署前执行额外检查（安全扫描、代码生成等）。本文提供完整的 Vercel + GitHub Actions 部署方案，从基础 CLI 到多环境流量路由、构建缓存加速、质量门禁、通知集成与故障排查，覆盖生产级 CI/CD 全链路。

一、基础方案：Vercel CLI

Vercel CLI 是 GitHub Actions 与 Vercel 平台交互的核心桥梁。vercel pull 命令从远端拉取项目配置与环境变量，vercel build 在本地（CI 环境）完成源码构建并输出 .vercel/output 目录，vercel deploy --prebuilt 则将该目录直接上传为部署产物，跳过 Vercel 云端重复构建。这套 “本地构建 + 仅上传” 的方案显著减少了构建时间，也避免了云端与本地 Node.js 版本不一致导致的潜在问题。

预览环境（Preview Deployment）是 Vercel 的一大亮点。每次 Pull Request 都会自动生成一个带独立 URL 的预览部署，方便设计师、产品经理、QA 在代码合并前进行视觉 Review。生产环境部署则绑定主分支（通常是 main），只有合并后的代码才会触发生产发布。

# .github/workflows/deploy.yml
name: Deploy to Vercel

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy
        run: echo "url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT

      - name: Comment Preview URL
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Preview deployed: ${{ steps.deploy.outputs.url }}`
            })

  deploy-production:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    environment:
      name: Production
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy
        run: echo "url=$(vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT

二、多项目 Monorepo 部署

Monorepo 架构在现代前端工程中极为常见，尤其是基于 Turborepo、Nx 或 pnpm workspace 的项目。一个仓库通常包含 Web 应用、管理后台、文档站点、共享 UI 组件库等多个子项目。Vercel 自带的 Git 集成每个 Project 只能绑定一个源码根目录，因此多项目场景必须通过 GitHub Actions 手动指定 working-directory 或使用 vercel --cwd 参数分别部署。

部署时建议为每个子项目配置独立的 VERCEL_PROJECT_ID，这样才能确保各自的预览与生产环境互不干扰。如果多个项目共享 node_modules 或构建产物，可以在根目录先执行 turbo run build，再进入子项目执行 vercel deploy --prebuilt。

# .github/workflows/monorepo-deploy.yml
name: Monorepo Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy-web:
    runs-on: ubuntu-latest
    env:
      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_WEB_PROJECT_ID }}
      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install --global vercel@latest
      - working-directory: ./apps/web
        run: |
          vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
          vercel build --token=${{ secrets.VERCEL_TOKEN }}
          vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

  deploy-admin:
    runs-on: ubuntu-latest
    env:
      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_ADMIN_PROJECT_ID }}
      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install --global vercel@latest
      - working-directory: ./apps/admin
        run: |
          vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
          vercel build --token=${{ secrets.VERCEL_TOKEN }}
          vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

三、部署环境保护（Environment Protection）

GitHub Environments 是保护生产环境的终极防线。当 Workflow 中的 job 声明了 environment: Production 后，GitHub 会在该 job 执行前暂停整个流水线，直到满足所有自定义保护规则。这些规则包括：指定人员审批（Required Reviewers）、强制等待窗口（Wait Timer）、以及限定可部署的分支或标签（Deployment Branches）。

推荐的保护规则组合为：主分支 main 只能通过 PR 合并更新，生产部署必须由 Tech Lead 或 DevOps 负责人审批，且设置 5 分钟等待窗口作为最后的冷静期。此外，启用 “Allow administrators to bypass configured protection rules” 可以确保紧急故障修复不受阻塞。

# .github/workflows/production-deploy.yml
jobs:
  deploy-production:
    runs-on: ubuntu-latest
    environment:
      name: Production
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm install --global vercel@latest
      - name: Pull Vercel Config
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy
        name: Deploy to Production
        run: echo "url=$(vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT

配置环境保护规则：

GitHub Repo → Settings → Environments → New environment
Name: Production
Protection rules：
- Required reviewers: 1-2 人（技术负责人 + DevOps）
- Wait timer: 5 分钟（延迟部署冷静期）
- Deployment branches: refs/heads/main

四、回滚策略

生产发布出现严重 Bug 时，回滚速度直接决定业务损失。相比热修复（Hotfix），基于历史 Commit 的回滚策略更加安全可控，因为它完全复用已经验证过的代码状态。GitHub Actions 的 workflow_dispatch 触发器允许手动选择任意历史 Commit SHA 进行重新部署，这是实现一键回滚的最佳实践。

回滚 Workflow 应设为仅仓库管理员可执行，并默认回退到上一个已知的稳定部署。为了提升可观测性，建议在执行回滚前发送一条通知到团队聊天频道，告知所有成员回滚原因和目标版本。

# .github/workflows/rollback.yml
name: Rollback Production

on:
  workflow_dispatch:
    inputs:
      commit_sha:
        description: '回滚目标 Commit SHA（留空则回退到上一版本）'
        required: false
      reason:
        description: '回滚原因'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    environment:
      name: Production
    steps:
      - name: Checkout target commit
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.inputs.commit_sha || 'HEAD~1' }}
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy rollback
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
      - name: Notify team
        run: |
          echo "生产环境已回滚到 ${{ github.event.inputs.commit_sha || 'HEAD~1' }}"
          echo "原因: ${{ github.event.inputs.reason }}"

触发方式：GitHub Actions → Run workflow → 输入 commit SHA 与回滚原因。

五、Secrets 配置清单

密钥管理是 CI/CD 安全的基石。Vercel CLI 需要三组核心凭证，其中 VERCEL_TOKEN 决定了 GitHub Actions 调用 Vercel API 的权限范围，VERCEL_ORG_ID 和 VERCEL_PROJECT_ID 则精确定位到目标组织与项目。建议为 CI/CD 单独创建一个 Scoped Token，仅授予 “Project” 级别的 “Read & Write” 权限，并将 Token 的有效期设置为 90 天定期轮换。

Secret	来源	说明	安全建议
`VERCEL_TOKEN`	Vercel Settings → Tokens	个人/团队访问令牌	使用 Scoped Token，最小权限原则
`VERCEL_ORG_ID`	Vercel Project → Settings → General	组织或用户 ID	仅用于 CLI 识别目标组织
`VERCEL_PROJECT_ID`	Vercel Project → Settings → General	项目唯一标识	Monorepo 场景需为每个子项目配置独立 ID

获取方式：在 Vercel Dashboard 中打开对应项目，进入 Settings → General，页面底部即可看到 Project ID 和 Org ID。Token 则在 Account Settings → Tokens 中生成并复制。

六、部署前质量关：Playwright 视觉回归测试 + Lighthouse CI 性能预算

将代码直接推送到生产环境而不经过质量验证是极其危险的。生产级 CI/CD 流水线必须在部署前设置两道质量关卡：视觉回归测试确保 UI 没有意外变化，性能预算确保核心 Web 指标（Core Web Vitals）不劣化。

Playwright 是微软出品的端到端测试框架，相比 Cypress 在多浏览器支持、截图对比和网络模拟方面更具优势。可以在 Workflow 中先部署预览环境，然后针对预览 URL 运行 Playwright 测试，最后再决定是否将部署提升为生产环境。

Lighthouse CI 则为每次构建自动跑 Lighthouse 审计，并与预设阈值（如 LCP < 2.5s、CLS < 0.1、FCP < 1.8s）对比，不达标则阻断部署。

# .github/workflows/quality-gate.yml
name: Quality Gate + Deploy

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run build

      - name: Install Playwright
        run: npx playwright install --with-deps
      - name: Run Playwright E2E Tests
        run: npx playwright test
      - name: Upload Playwright Report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli@0.14.x
          lhci autorun --upload.target=temporary-public-storage
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

  deploy-preview:
    needs: build-and-test
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy
        run: echo "url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT
      - name: Preview URL Comment
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Preview: ${{ steps.deploy.outputs.url }}`
            })

七、Turborepo Remote Cache 与 Vercel 构建加速

大型 Monorepo 中最耗时的环节往往不是应用代码编译，而是反复的依赖安装与冗余构建。Turborepo 的 Remote Cache 功能允许团队将构建产物缓存到云端（Vercel 原生支持），后续 CI 执行只需下载缓存即可跳过大量重复计算，构建时间可缩短 60% 以上。

启用 Remote Cache 的前提是 Turborepo 项目已配置 turbo.json，并在 GitHub Actions 中注入 TURBO_TEAM 与 TURBO_TOKEN 环境变量。Vercel Enterprise 团队可直接复用现有的 Vercel Token 作为 Turborepo Token。此外，结合 actions/cache 对 node_modules 和 .turbo 目录进行二次缓存，可进一步降低依赖安装时间。

# .github/workflows/turbo-cache-deploy.yml
name: Turbo Remote Cache + Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
  TURBO_TOKEN: ${{ secrets.VERCEL_TOKEN }}
  TURBO_TEAM: ${{ secrets.VERCEL_ORG_ID }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Restore Turbo Cache
        uses: actions/cache@v4
        with:
          path: |
            .turbo
            node_modules/.cache/turbo
          key: ${{ runner.os }}-turbo-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-

      - run: npm ci
      - run: npx turbo run build --cache-dir=.turbo
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy
        run: echo "url=$(vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT

八、Vercel 环境变量（系统/加密/自定义）自动化管理

Vercel 支持三类环境变量：系统环境变量（如 VERCEL_URL、VERCEL_ENV）、加密环境变量（Sensitive，值不可见）、以及普通自定义变量。在 CI/CD 场景中，经常需要在部署前动态注入环境变量，例如将 GitHub Actions 的 GITHUB_SHA 写入构建产物用于版本追踪，或根据分支动态切换 API 端点。

vercel env 命令可以在 CLI 中管理环境变量，结合 GitHub Actions 可实现：敏感变量仅在生产环境生效、非敏感变量在预览与生产环境共享、动态变量在每次部署时注入。建议将环境变量分为 “Build Time” 和 “Runtime” 两类，Build Time 变量在 vercel build 阶段注入，Runtime 变量则由 Vercel Function 运行时读取。

# .github/workflows/env-management.yml
name: Deploy with Dynamic Envs

on:
  push:
    branches: [main, develop]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm install --global vercel@latest

      - name: Set Build Time Env
        run: |
          vercel env rm BUILD_SHA preview --yes --token=${{ secrets.VERCEL_TOKEN }} || true
          echo "${{ github.sha }}" | vercel env add BUILD_SHA preview --token=${{ secrets.VERCEL_TOKEN }}
          vercel env rm BUILD_DATE preview --yes --token=${{ secrets.VERCEL_TOKEN }} || true
          echo "$(date -u +%Y-%m-%dT%H:%M:%SZ)" | vercel env add BUILD_DATE preview --token=${{ secrets.VERCEL_TOKEN }}

      - name: Pull & Build & Deploy
        run: |
          vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
          vercel build --token=${{ secrets.VERCEL_TOKEN }}
          echo "url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_ENV

九、多环境支持：Preview/Staging/Canary/Production 流量路由

单一的生产环境已无法满足现代 SaaS 产品的发布需求。成熟的部署策略通常包含四层环境：Preview（分支预览）、Staging（集成测试）、Canary（灰度流量）、Production（全量生产）。Vercel 原生不提供 Canary 流量拆分，但可通过多项目 + Edge Config 或 Middleware 实现简易灰度。

Staging 环境绑定 staging 分支，复用生产环境数据库的只读副本进行端到端测试。Preview 环境则随 PR 生命周期自动创建与销毁。Canary 环境使用独立 Vercel Project，通过负载均衡器或 Edge Middleware 按百分比将流量从生产环境逐步切至 Canary，观测 30 分钟无异常后再全量切换。

# .github/workflows/multi-env.yml
name: Multi-Environment Deploy

on:
  push:
    branches: [main, staging, 'release/**']
  pull_request:
    branches: [main]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}

jobs:
  preview:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    env:
      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

  staging:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/staging'
    env:
      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_STAGING_PROJECT_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

  production:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    environment:
      name: Production
    env:
      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

十、部署通知集成（Slack/Discord/钉钉 Webhook）

部署事件对团队协作至关重要。每次生产发布、回滚或失败的构建都应当即时推送到团队聊天频道，确保所有相关人员第一时间获知状态变化。Slack 的 Incoming Webhook 格式最为成熟，支持丰富的 Block Kit 布局；Discord 的 Webhook 与 Slack 兼容；钉钉机器人则使用特有的 msgtype: markdown 格式。

通知内容应包含：部署环境、触发人、Commit 信息、部署 URL、以及审批状态。对于失败的部署，还应附带工作流运行链接供快速定位问题。

# .github/workflows/notify.yml
name: Deploy with Notifications

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    outputs:
      url: ${{ steps.deploy.outputs.url }}
    environment:
      name: Production
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install --global vercel@latest
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy
        run: echo "url=$(vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT

  notify-slack:
    needs: deploy
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Post to Slack
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          fields: repo,message,commit,author,action,ref
          text: |
            Production Deployment ${{ needs.deploy.result == 'success' && 'Succeeded' || 'Failed' }}
            URL: ${{ needs.deploy.outputs.url }}
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

  notify-dingtalk:
    needs: deploy
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Post to DingTalk
        run: |
          curl -s ${{ secrets.DINGTALK_WEBHOOK_URL }} \
            -H 'Content-Type: application/json' \
            -d '{
              "msgtype": "markdown",
              "markdown": {
                "title": "部署通知",
                "text": "### 生产环境部署结果\n- 状态：${{ needs.deploy.result == '\''success'\'' && '\''成功'\'' || '\''失败'\'' }}\n- 部署人：${{ github.actor }}\n- 提交：${{ github.event.head_commit.message }}\n- URL：${{ needs.deploy.outputs.url }}"
              }
            }'

十一、故障排查与诊断（构建日志/vercel logs/错误码速查表）

即使最完善的 CI/CD 流水线也难免遇到构建失败。快速诊断故障并恢复服务是 DevOps 的核心能力。Vercel 构建失败的常见原因包括：Node.js 版本不兼容、依赖安装超时、环境变量缺失、以及服务端代码（API Routes / Edge Functions）运行时异常。

诊断策略应分三层进行：首先是 GitHub Actions 日志，检查 vercel build 的 stdout/stderr；其次是 Vercel Dashboard 的 Deployments 页面，查看构建与运行时的详细日志；最后通过 CLI 的 vercel logs <url> 实时追踪服务端函数的日志输出。对于 Next.js 项目，next.config.js 中的 output: 'standalone' 配置错误是构建失败的常见根因。

# .github/workflows/deploy-with-debug.yml
name: Deploy with Debug

on:
  push:
    branches: [main]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm install --global vercel@latest
      - run: vercel --version

      - name: Debug Env
        run: |
          echo "Node version: $(node -v)"
          echo "NPM version: $(npm -v)"
          echo "Vercel CLI version: $(vercel --version)"

      - name: Pull Config
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build with verbose logging
        run: |
          export DEBUG=*
          vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - id: deploy
        run: echo "url=$(vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }})" >> $GITHUB_OUTPUT

      - name: Stream production logs
        if: steps.deploy.outcome == 'success'
        run: vercel logs ${{ steps.deploy.outputs.url }} --token=${{ secrets.VERCEL_TOKEN }} --limit=50 || true

常见错误码速查表：

错误码/现象	根本原因	解决方案
`404: NOT_FOUND`	部署成功但路由未匹配	检查 `vercel.json` routes 或 Next.js `output` 配置
`BUILD_UTILS_NODE_VERSION`	Node.js 版本与项目要求不符	在 `vercel.json` 或 GitHub Actions 中锁定版本
`FUNCTION_INVOCATION_TIMEOUT`	Serverless Function 执行超时	优化数据库查询，或升级至 Edge Runtime
`DEPLOYMENT_BLOCKED`	超出团队并发部署限制	等待其他部署完成，或升级 Vercel 计划
`vercel pull` 401	Token 过期或权限不足	重新生成 Scoped Token 并更新 GitHub Secrets

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页