自建 CI/CD 部署 Vercel：GitHub Actions 预构建（Prebuilt）部署实战指南
【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples
本篇技术指南聚焦于"自带 CI/CD"（Bring Your Own CI/CD）方案：使用 GitHub Actions 作为自定义流水线，通过 Vercel CLI 的vercel build与vercel deploy --prebuilt，在不向 Vercel 开放源码的前提下完成 Preview 与 Production 双环境部署。读完本文，你将掌握完整的两套 GitHub Actions workflow 配置、Vercel 令牌与项目密钥的接入方法，以及"本地构建、远端发布"这一预构建部署模型的底层原理。本文以仓库 ci-cd/github-actions/README.md 为骨架展开，并结合仓库内 ci-cd 目录下的同系列 CI/CD 示例与 turborepo-github-actions 多包仓库示例进行纵深补充。
为什么需要"自带 CI/CD"：GitHub Actions + Vercel 的适用场景
通常，将 Vercel 接入 GitHub 仓库后，Vercel 会通过零配置的 Git 集成自动识别前端框架，为每次git push生成 Preview Deployment，并在代码合并进main分支时触发 Production 部署。但在以下两类场景中，这种"开箱即用"的集成无法满足需求：
- 希望对 CI/CD 流水线拥有完全控制权的开发者：例如需要在构建前运行自定义测试、代码扫描、类型检查、镜像构建等步骤，或者希望把"构建"和"部署"两个环节彻底解耦、由自己的流水线编排；
- GitHub Enterprise Server 用户：自托管的 GitHub 企业版目前无法使用 Vercel 的零配置 Git 集成，只能通过自有 Actions Runner 与 Vercel CLI 打通部署链路。
此时，GitHub Actions 作为 CI/CD 提供方接入 Vercel，就能为每次git push生成 Preview Deployment，并在代码合并到main分支时自动部署到生产环境——这正是本仓库 ci-cd/github-actions 示例所要演示的核心工作流。仓库中同一目录下的 ci-cd/bitbucket-pipelines/README.md 与 ci-cd/gitlab-cicd/README.md 提供了 Bitbucket Pipelines 与 GitLab CI/CD 的等价实现，读者可以横向对比不同平台的流水线写法。
构建应用：vercel build与 Build Output API
在把 GitHub Actions 接入 Vercel 之前，先理解"预构建部署"的基石——vercel build命令。
你可以在本地（或任意 CI Action 中）直接执行vercel build，无需把源码交给 Vercel。Vercel CLI 会自动检测你的前端框架（Next.js、Nuxt、Vite 等），并生成一个符合Build Output API 规范的.vercel/output文件夹。Build Output API 是 Vercel 定义的构建产物标准格式，它把"框架如何构建"与"平台如何运行"解耦：只要产物目录符合规范，部署平台就不需要关心源码与框架细节。
vercel build的价值在于：它允许你在自己的 CI 环境中完成构建（无论是 GitHub Actions、自建 CI，还是本仓库演示的 Bitbucket Pipelines、GitLab CI/CD），然后**只上传构建产物（而非源码）**到 Vercel 创建部署。这样既保留了自定义流水线的灵活性，又避免了把私有源码暴露给部署平台。
配置 GitHub Actions：Preview 环境工作流
vercel deploy --prebuilt会跳过 Vercel 侧的构建步骤，直接上传 GitHub Action 中已经生成好的.vercel/output文件夹，实现"在 CI 里构建、在 Vercel 上发布"。
在仓库根目录新建.github/workflows/preview.yaml，内容如下（完整继承自 ci-cd/github-actions/README.md）：
name: GitHub Actions Vercel Preview Deployment env: VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} on: push: branches-ignore: - main jobs: Deploy-Preview: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install Vercel CLI run: npm install --global vercel@latest - name: Pull Vercel Environment Information run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }} - name: Build Project Artifacts run: vercel build --token=${{ secrets.VERCEL_TOKEN }} - name: Deploy Project Artifacts to Vercel run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}逐段拆解这份工作流的关键点：
env层注入组织与项目标识：VERCEL_ORG_ID与VERCEL_PROJECT_ID通过 GitHub Secrets 注入到整个工作流环境变量中，供后续vercel命令读取，用于定位"部署到哪个 Vercel 组织下的哪个项目"。on.push.branches-ignore: main触发条件：只要代码被推送到非main的任意分支（包括功能分支与 Pull Request 源分支），就触发本工作流，用于生成 Preview Deployment。actions/checkout@v3：检出仓库代码，使后续步骤能在工作区中执行vercel命令。npm install --global vercel@latest：在 runner 上全局安装最新版 Vercel CLI。仓库内 ci-cd/turborepo-github-actions 示例还展示了将 Vercel CLI 作为项目依赖纳入 pnpm workspace 的用法，适合对版本有强约束的 monorepo 场景。vercel pull --yes --environment=preview --token=...：从 Vercel 拉取该项目的环境信息（环境变量、框架预设等），--yes跳过交互确认，--environment=preview指定拉取 Preview 环境配置。vercel build --token=...：在 runner 上执行构建，产出.vercel/output目录。此步不传--prod，产物对应 Preview 构建。vercel deploy --prebuilt --token=...：跳过 Vercel 侧构建，直接上传上一步生成的构建产物，创建 Preview Deployment。--prebuilt是整条链路中承上启下的关键开关。
配置 GitHub Actions：Production 环境工作流
针对main分支的生产部署，用一份独立的 Action 文件（例如.github/workflows/production.yaml）实现，完整配置如下：
name: GitHub Actions Vercel Production Deployment env: VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} on: push: branches: - main jobs: Deploy-Production: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install Vercel CLI run: npm install --global vercel@latest - name: Pull Vercel Environment Information run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }} - name: Build Project Artifacts run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }} - name: Deploy Project Artifacts to Vercel run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}与 Preview 工作流相比，Production 工作流仅有三处差异，务必区分清楚：
| 环节 | Preview 工作流 | Production 工作流 | 说明 |
|---|---|---|---|
| 触发条件 | branches-ignore: [main] | branches: [main] | Preview 排除主分支，Production 仅响应主分支 |
| 拉取环境 | --environment=preview | --environment=production | 拉取对应环境的变量与配置 |
| 构建与部署 | vercel build/vercel deploy --prebuilt | vercel build --prod/vercel deploy --prebuilt --prod | 增加--prod标记为生产构建/部署 |
--prod的作用是让构建与部署都按 Production 环境处理：vercel build --prod生成的产物带有生产环境配置，vercel deploy --prebuilt --prod则将其发布为生产 Deployment（对应正式域名）。
需要留意的是，两份工作流属于两个独立文件，main分支的 push 只会命中 Production 工作流，功能分支的 push 只会命中 Preview 工作流，两者互不干扰。同样的"双触发"设计也出现在仓库的兄弟示例中，例如 ci-cd/bitbucket-pipelines/bitbucket-pipelines.yml 中按feature/*与main分支划分两个 step，以及 ci-cd/gitlab-cicd/README.md 中deploy_preview与deploy_production两个 job。
在 GitHub 中配置 Vercel 密钥
工作流中的secrets.*需要在 GitHub 仓库中预先配置。按以下步骤获取并注册三个必要值：
- 获取 Vercel Access Token：在 Vercel 账户设置中生成一个访问令牌（Access Token），用于 CI 环境中以 API 身份调用 Vercel。
- 登录 Vercel CLI 并关联项目：本地安装 Vercel CLI 后执行
vercel login完成登录；然后在项目文件夹内执行vercel link，创建一个新的（或关联已有的）Vercel 项目。 - 读取项目标识：
vercel link会在本地生成.vercel文件夹，其中的project.json文件内保存了projectId与orgId两个字段，分别对应VERCEL_PROJECT_ID与VERCEL_ORG_ID。 - 写入 GitHub Secrets：在 GitHub 仓库的 Settings → Secrets 中添加三个加密密钥：
VERCEL_TOKEN、VERCEL_ORG_ID、VERCEL_PROJECT_ID，值与上一步获取的令牌和标识一一对应。
GitHub 的 Encrypted Secrets 会在工作流运行时以${{ secrets.XXX }}语法解密注入，且不会出现在日志中，保证了令牌安全。作为对比，GitLab 场景有一个易踩的坑：GitLab 不允许在 UI 定义的变量与.gitlab-ci.yml中同名复用，因此 ci-cd/gitlab-cicd/README.md 特意将变量命名为VERCEL_ORG_ID_X、VERCEL_PROJECT_ID_X并在流水线内重新映射——GitHub Actions 没有这一限制，但理解各平台差异有助于迁移经验。
端到端验证：从 Pull Request 到生产回滚
配置完成后，即可验证完整的部署链路，流程如下：
- 向 GitHub 仓库发起一个新的 Pull Request（或向功能分支 push 代码）；
- GitHub Actions 识别到变更，在 runner 上通过 Vercel CLI 完成安装 CLI → 拉取环境信息 → 构建产物 → 上传部署的完整链路；
- Action 将构建产物上传到 Vercel，生成一个 Preview Deployment，并自动附着在该 Pull Request 上（可在 PR 页直接预览）；
- Pull Request 合并进
main后，Production 工作流被触发，创建并发布生产构建。
此后每个 Pull Request 都会自动带有一个 Preview Deployment，方便团队在合并前预览、评审实际运行效果。如果某次生产发布需要回滚，只需 revert 该 PR 并重新合并，Vercel 便会基于旧 git 状态启动一次新的 Production 构建——回滚动作本身也走同一套流水线，无需手工干预。
进阶：在 monorepo 中用 turbo 编排构建再预构建部署
如果项目是 Turborepo 多包仓库，直接对所有包执行 Vercel 构建可能产生冗余。仓库中的 ci-cd/turborepo-github-actions/README.md 提供了一个可参考的混合方案：
web应用：直接用vc deploy将源码交给 Vercel 构建部署（走零配置集成）；docs应用：改用vc build+vc deploy --prebuilt，在 GitHub Action 中完成构建后再上传产物——演示了"完全掌控构建过程"的预构建模式；- 额外引入一个
foo内部包：在构建docs之前，先用turboCLI 构建其内部依赖，说明 turbo 的任务编排能力（如缓存、依赖拓扑）可以与 Vercel CLI 的预构建流程无缝衔接。
该示例的根 package.json 中build: turbo build、dev: turbo dev等脚本，以及pnpm-workspace.yaml、turbo.json的 workspace 与管道配置，构成了"turbo 构建内部依赖 → vercel build 生成产物 → vercel deploy --prebuilt 发布"的完整依赖链。对于 monorepo 团队，这套组合是"自带 CI/CD"方案在生产规模下的自然延伸。
小结
通过 ci-cd/github-actions 示例所展示的四步命令（vercel pull→vercel build→vercel deploy --prebuilt），你可以在 GitHub Actions 中自主掌控构建过程，同时享受 Vercel 的 Preview/Production 双环境部署能力。其核心收益有三：其一，流水线完全透明、可自由插入测试与安全检查；其二，GitHub Enterprise Server 等无法使用零配置集成的场景得以打通；其三，构建产物与源码解耦，部署环节更安全可控。若需在 Bitbucket 或 GitLab 上复刻同一套流程，可直接参考仓库中的 ci-cd/bitbucket-pipelines/README.md 与 ci-cd/gitlab-cicd/README.md；若项目为 Turborepo 多包结构，则可对照 ci-cd/turborepo-github-actions 示例落地。
【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
