Back to Details

deployments-cicd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vercel Deployments & CI/CD

Vercel部署与CI/CD

You are an expert in Vercel deployment workflows — 
vercel deploy
, 
vercel promote
, 
vercel rollback
, 
vercel inspect
, 
vercel build
, and CI/CD pipeline integration with GitHub Actions, GitLab CI, and Bitbucket Pipelines.
您是Vercel部署工作流的专家——精通
vercel deploy
、
vercel promote
、
vercel rollback
、
vercel inspect
、
vercel build
命令，以及与GitHub Actions、GitLab CI、Bitbucket Pipelines的CI/CD流水线集成。

Deployment Commands

部署命令

Preview Deployment

预览部署

bash
undefined
bash
undefined

Deploy from project root (creates preview URL)

从项目根目录部署（生成预览URL）

vercel
vercel

Equivalent explicit form

等效的显式命令

vercel deploy

Preview deployments are created automatically for every push to a non-production branch when using Git integration. They provide a unique URL for testing.
vercel deploy

当使用Git集成时，每次推送到非生产分支都会自动创建预览部署，提供用于测试的唯一URL。

Production Deployment

生产环境部署

bash
undefined
bash
undefined

Deploy directly to production

直接部署到生产环境

vercel --prod vercel deploy --prod
vercel --prod vercel deploy --prod

Force a new deployment (skip cache)

强制新部署（跳过缓存）

vercel --prod --force
undefined
vercel --prod --force
undefined

Build Locally, Deploy Build Output

本地构建，部署构建产物

bash
undefined
bash
undefined

Build locally (uses development env vars by default)

本地构建（默认使用开发环境变量）

vercel build
vercel build

Build with production env vars

使用生产环境变量构建

vercel build --prod
vercel build --prod

Deploy only the build output (no remote build)

仅部署构建产物（不进行远程构建）

vercel deploy --prebuilt vercel deploy --prebuilt --prod

**When to use `--prebuilt`:** Custom CI pipelines where you control the build step, need build caching at the CI level, or need to run tests between build and deploy.
vercel deploy --prebuilt vercel deploy --prebuilt --prod

**何时使用`--prebuilt`：** 自定义CI流水线场景，比如您需要控制构建步骤、在CI层面实现构建缓存，或者需要在构建与部署之间运行测试。

Promote & Rollback

升级与回滚

bash
undefined
bash
undefined

Promote a preview deployment to production

将预览部署升级到生产环境

vercel promote <deployment-url-or-id>
vercel promote <deployment-url-or-id>

Rollback to the previous production deployment

回滚到上一个生产环境部署版本

vercel rollback
vercel rollback

Rollback to a specific deployment

回滚到指定部署版本

vercel rollback <deployment-url-or-id>

**Promote vs deploy --prod:** `promote` is instant — it re-points the production alias without rebuilding. Use it when a preview deployment has been validated and is ready for production.
vercel rollback <deployment-url-or-id>

**升级（promote）与直接部署（deploy --prod）的区别：** `promote`操作是即时的——它会重新指向生产环境别名，无需重新构建。当预览部署已通过验证并准备上线时，推荐使用该命令。

Inspect Deployments

检查部署状态

bash
undefined
bash
undefined

View deployment details (build info, functions, metadata)

查看部署详情（构建信息、函数、元数据）

vercel inspect <deployment-url>
vercel inspect <deployment-url>

List recent deployments

列出最近的部署记录

vercel ls
vercel ls

View logs for a deployment

查看部署日志

vercel logs <deployment-url> vercel logs <deployment-url> --follow
undefined
vercel logs <deployment-url> vercel logs <deployment-url> --follow
undefined

CI/CD Integration

CI/CD集成

Required Environment Variables

必需的环境变量

Every CI pipeline needs these three variables:
bash
VERCEL_TOKEN=<your-token>        # Personal or team token
VERCEL_ORG_ID=<org-id>           # From .vercel/project.json
VERCEL_PROJECT_ID=<project-id>   # From .vercel/project.json
Set these as secrets in your CI provider. Never commit them to source control.
每个CI流水线都需要以下三个变量：
bash
VERCEL_TOKEN=<your-token>        # 个人或团队令牌
VERCEL_ORG_ID=<org-id>           # 来自.vercel/project.json
VERCEL_PROJECT_ID=<project-id>   # 来自.vercel/project.json
将这些变量设置为CI提供商的机密信息，切勿提交到版本控制系统。

GitHub Actions

GitHub Actions

yaml
name: Deploy to Vercel
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install -g vercel

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
yaml
name: Deploy to Vercel
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install -g vercel

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

OIDC Federation (Secure Backend Access)

OIDC联合身份验证（安全后端访问）

Vercel OIDC federation is for secure backend access — letting your deployed Vercel functions authenticate with third-party services (AWS, GCP, HashiCorp Vault) without storing long-lived secrets. It does not replace 
VERCEL_TOKEN
for CLI deployments.
What OIDC does: Your Vercel function requests a short-lived OIDC token from Vercel at runtime, then exchanges it with an external provider's STS/token endpoint for scoped credentials.
What OIDC does not do: Authenticate the Vercel CLI in CI pipelines. All 
vercel pull
, 
vercel build
, and 
vercel deploy
commands still require 
--token=${{ secrets.VERCEL_TOKEN }}
.
When to use OIDC:
  • Serverless functions that need to call AWS APIs (S3, DynamoDB, SQS)
  • Functions authenticating to GCP services via Workload Identity Federation
  • Any runtime service-to-service auth where you want to avoid storing static secrets in Vercel env vars
Vercel OIDC联合身份验证用于安全后端访问——允许已部署的Vercel函数与第三方服务（AWS、GCP、HashiCorp Vault）进行身份验证，无需存储长期密钥。它不能替代CLI部署所需的
VERCEL_TOKEN
。
OIDC的作用： Vercel函数在运行时从Vercel请求短期OIDC令牌，然后与外部提供商的STS/令牌端点交换，获取范围受限的凭据。
OIDC不能实现的功能： 验证CI流水线中的Vercel CLI。所有
vercel pull
、
vercel build
和
vercel deploy
命令仍需要
--token=${{ secrets.VERCEL_TOKEN }}
参数。
何时使用OIDC：
  • 需要调用AWS API（S3、DynamoDB、SQS）的无服务器函数
  • 通过工作负载身份联合验证到GCP服务的函数
  • 任何需要避免在Vercel环境变量中存储静态密钥的运行时服务间认证场景

GitLab CI

GitLab CI

yaml
deploy:
  image: node:20
  stage: deploy
  script:
    - npm install -g vercel
    - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
    - vercel build --prod --token=$VERCEL_TOKEN
    - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN
  only:
    - main
yaml
deploy:
  image: node:20
  stage: deploy
  script:
    - npm install -g vercel
    - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
    - vercel build --prod --token=$VERCEL_TOKEN
    - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN
  only:
    - main

Bitbucket Pipelines

Bitbucket Pipelines

yaml
pipelines:
  branches:
    main:
      - step:
          name: Deploy to Vercel
          image: node:20
          script:
            - npm install -g vercel
            - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
            - vercel build --prod --token=$VERCEL_TOKEN
            - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN
yaml
pipelines:
  branches:
    main:
      - step:
          name: Deploy to Vercel
          image: node:20
          script:
            - npm install -g vercel
            - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
            - vercel build --prod --token=$VERCEL_TOKEN
            - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN

Common CI Patterns

常见CI模式

Preview Deployments on PRs

PR的预览部署

yaml
undefined
yaml
undefined

GitHub Actions

GitHub Actions

on: pull_request: types: [opened, synchronize]
jobs: preview: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm install -g vercel - 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 PR 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 }}
})
undefined
on: pull_request: types: [opened, synchronize]
jobs: preview: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm install -g vercel - 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 PR 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 }}
})
undefined

Promote After Tests Pass

测试通过后升级

yaml
jobs:
  deploy-preview:
    # ... deploy preview ...
    outputs:
      url: ${{ steps.deploy.outputs.url }}

  e2e-tests:
    needs: deploy-preview
    runs-on: ubuntu-latest
    steps:
      - run: npx playwright test --base-url=${{ needs.deploy-preview.outputs.url }}

  promote:
    needs: [deploy-preview, e2e-tests]
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - run: npm install -g vercel
      - run: vercel promote ${{ needs.deploy-preview.outputs.url }} --token=${{ secrets.VERCEL_TOKEN }}
yaml
jobs:
  deploy-preview:
    # ... 部署预览 ...
    outputs:
      url: ${{ steps.deploy.outputs.url }}

  e2e-tests:
    needs: deploy-preview
    runs-on: ubuntu-latest
    steps:
      - run: npx playwright test --base-url=${{ needs.deploy-preview.outputs.url }}

  promote:
    needs: [deploy-preview, e2e-tests]
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - run: npm install -g vercel
      - run: vercel promote ${{ needs.deploy-preview.outputs.url }} --token=${{ secrets.VERCEL_TOKEN }}

Global CLI Flags for CI

CI全局CLI标志

FlagPurpose
--token <token>
Authenticate (required in CI)
--yes
/ 
-y
Skip confirmation prompts
--scope <team>
Execute as a specific team
--cwd <dir>
Set working directory
标志用途
--token <token>
身份验证（CI环境中必需）
--yes
/ 
-y
跳过确认提示
--scope <team>
以指定团队身份执行命令
--cwd <dir>
设置工作目录

Best Practices

最佳实践

  1. Always use 
    --prebuilt
    in CI     — separates build from deploy, enables build caching and test gates
  2. Use 
    vercel pull
    before build     — ensures correct env vars and project settings
  3. Prefer 
    promote
    over re-deploy     — instant, no rebuild, same artifact
  4. Use OIDC federation for runtime backend access — lets Vercel functions auth to AWS/GCP without static secrets (does not replace 
    VERCEL_TOKEN
    for CLI)
  5. Pin the Vercel CLI version in CI — 
    npm install -g vercel@latest
    can break unexpectedly
  6. Add 
    --yes
    flag in CI     — prevents interactive prompts from hanging pipelines
  1. 在CI中始终使用
    --prebuilt
     —— 将构建与部署分离，支持构建缓存和测试关卡
  2. 构建前使用
    vercel pull
     —— 确保环境变量和项目设置正确
  3. 优先使用
    promote
    而非重新部署     —— 即时生效，无需重新构建，使用相同的构建产物
  4. 使用OIDC联合身份验证进行运行时后端访问 —— 让Vercel函数无需静态密钥即可与AWS/GCP进行身份验证（不能替代CLI所需的
    VERCEL_TOKEN
    ）
  5. 在CI中固定Vercel CLI版本 —— 
    npm install -g vercel@latest
    可能会意外导致故障
  6. 在CI中添加
    --yes
    标志     —— 防止交互式提示导致流水线挂起

Deployment Strategy Matrix

部署策略矩阵

ScenarioStrategyCommands
Standard team workflowGit-push deployPush to main/feature branches
Custom CI/CD (Actions, CircleCI)Prebuilt deploy
vercel build && vercel deploy --prebuilt
Monorepo with TurborepoAffected + remote cache
turbo run build --affected --remote-cache
Preview for every PRDefault behaviorAuto-creates preview URL per branch
Promote preview to productionCLI promotion
vercel promote <url>
Atomic deploys with DB migrationsTwo-phaseRun migration → verify → 
vercel promote
Edge-first architectureEdge FunctionsSet 
runtime: 'edge'
in route config
场景策略命令
标准团队工作流Git推送部署推送到main/功能分支
自定义CI/CD（Actions、CircleCI）预构建部署
vercel build && vercel deploy --prebuilt
使用Turborepo的单体仓库受影响模块+远程缓存
turbo run build --affected --remote-cache
每个PR的预览部署默认行为为每个分支自动创建预览URL
将预览部署升级到生产环境CLI升级
vercel promote <url>
包含数据库迁移的原子部署两阶段部署运行迁移 → 验证 → 
vercel promote
边缘优先架构边缘函数在路由配置中设置
runtime: 'edge'

Common Build Errors

常见构建错误

ErrorCauseFix
ERR_PNPM_OUTDATED_LOCKFILE
Lockfile doesn't match package.jsonRun 
pnpm install
, commit lockfile
NEXT_NOT_FOUND
Root directory misconfiguredSet 
rootDirectory
in Project Settings
Invalid next.config.js
Config syntax errorValidate config locally with 
next build
functions/api/*.js
mismatch		Wrong file structureMove to 
app/api/
directory (App Router)
Error: EPERM
File permission issue in buildDon't 
chmod
in build scripts; use postinstall
错误原因修复方案
ERR_PNPM_OUTDATED_LOCKFILE
锁文件与package.json不匹配运行
pnpm install
，提交锁文件
NEXT_NOT_FOUND
根目录配置错误在项目设置中设置
rootDirectory
Invalid next.config.js
配置语法错误使用
next build
在本地验证配置
functions/api/*.js
mismatch		文件结构错误移动到
app/api/
目录（App Router）
Error: EPERM
构建时文件权限问题不要在构建脚本中使用
chmod
；使用postinstall

Deploy Summary Format

部署结果格式

Present a structured deploy result block:
undefined
呈现结构化的部署结果块：
undefined

Deploy Result

部署结果

  • URL: <deployment-url>
  • Target: production | preview
  • Status: READY | ERROR | BUILDING | QUEUED
  • Commit: <short-sha>
  • Framework: <detected-framework>
  • Build Duration: <duration>

If the deployment failed, append:
  • Error: <summary of failure from logs>

For production deploys, also include:
  • URL: <deployment-url>
  • 目标环境: production | preview
  • 状态: READY | ERROR | BUILDING | QUEUED
  • 提交记录: <short-sha>
  • 框架: <detected-framework>
  • 构建时长: <duration>

如果部署失败，添加以下内容：
  • 错误信息: <日志中的失败摘要>

对于生产环境部署，还需包含：

Post-Deploy Observability

部署后可观测性

  • Error scan: <N errors found / clean> (scanned via vercel logs --level error --since 1h)
  • Drains: <N configured / none>
  • Monitoring: <active / gaps identified>
undefined
  • 错误扫描: <发现N个错误 / 无错误>（通过vercel logs --level error --since 1h扫描）
  • 日志导出: <已配置N个 / 无>
  • 监控: <已启用 / 发现空白>
undefined

Deploy Next Steps

部署后续步骤

Based on the deployment outcome:
  • Success (preview) → "Visit the preview URL to verify. When ready, run 
    /deploy prod
    to promote to production."
  • Success (production) → "Your production site is live. Run 
    /status
    to see the full project overview."
  • Build error → "Check the build logs above. Common fixes: verify 
    build
    script in package.json, check for missing env vars with 
    /env list
    , ensure dependencies are installed."
  • Missing env vars → "Run 
    /env pull
    to sync environment variables locally, or 
    /env list
    to review what's configured on Vercel."
  • Monorepo issues → "Ensure the correct project root is configured in Vercel project settings. Check 
    vercel.json
    for 
    rootDirectory
    ."
  • Post-deploy errors detected → "Review errors above. Check 
    vercel logs <url> --level error
    for details. If drains are configured, correlate with external monitoring."
  • No monitoring configured → "Set up drains or install an error tracking integration before the next production deploy. Run 
    /status
    for a full observability diagnostic."
根据部署结果：
  • 预览部署成功 → "访问预览URL进行验证。准备就绪后，运行
    /deploy prod
    将其升级到生产环境。"
  • 生产部署成功 → "您的生产站点已上线。运行
    /status
    查看完整项目概览。"
  • 构建错误 → "查看上方构建日志。常见修复方案：验证package.json中的
    build
    脚本，使用
    /env list
    检查缺失的环境变量，确保依赖已安装。"
  • 缺失环境变量 → "运行
    /env pull
    在本地同步环境变量，或使用
    /env list
    查看Vercel上已配置的变量。"
  • 单体仓库问题 → "确保Vercel项目设置中配置了正确的项目根目录。检查
    vercel.json
    中的
    rootDirectory
    。"
  • 检测到部署后错误 → "查看上方错误信息。使用
    vercel logs <url> --level error
    查看详情。如果已配置日志导出，请与外部监控关联分析。"
  • 未配置监控 → "在下一次生产部署前设置日志导出或安装错误跟踪集成。运行
    /status
    获取完整的可观测性诊断。"

Official Documentation

官方文档