Vercel 修改部署分支与关闭分支构建

修改方法如下

项目部署时其余分支的提交也会触发构建

点击 Preview 将 Branch Tracking 设置为 Disabled

完整的设置路径

上面两处配置都在同一个页面下，找的时候按这个路径走：

项目 → Settings → Git（老版本叫 Git Integration）

这个页面从上到下有三块内容，对应三件不同的事：

Connected Git Repository — 关联的仓库，以及断开重连的入口。
Production Branch — 生产分支。这个分支上的每次 push 都会触发一次生产部署，并自动切换你的自定义域名指向。这就是正文第一张图要改的地方。
Ignored Build Step / Deployment Protection 等 — 更细的构建控制，下面会说。

Preview 部署的分支追踪开关在 Settings → Git 页面里的 Preview Deployment Suffix 附近，或者在项目的 Deployments 页签里按分支管理。不同时期的 Vercel 后台布局有调整，找不到就在 Settings 页面顶部的搜索框里输 branch。

改了 Production Branch 之后会发生什么

这一点值得说清楚，因为它不是一个纯粹的「标记」，会连带影响几件事：

改完不会立刻重新部署。Vercel 只是记下了新的生产分支名，等到下一次这个分支有 push 才触发生产部署。所以如果你希望立刻让新分支的代码上线，要么手动 push 一个空提交：

git commit --allow-empty -m "chore: trigger vercel deploy"
git push

要么在 Deployments 列表里找到该分支上已有的一次 Preview 部署，点右侧的三点菜单选 Promote to Production。后者更快，因为它复用已经构建好的产物，不用重新 build。

自定义域名会跟着变。你的域名（比如 wflynn.cn）绑定的是「生产部署」这个概念，不是某个具体的 URL。生产分支一改，域名指向的内容下次部署后就跟着换了。这是最容易出意外的地方——如果你只是想让某个分支能被访问来做测试，不要改 Production Branch，用它自动生成的 Preview URL 就行。

环境变量的作用域会变。Vercel 的环境变量分 Production、Preview、Development 三个环境。原来在 main 上跑的时候读的是 Production 那组变量，切成别的分支做生产分支后，该分支的部署仍然读 Production 组——因为决定读哪组的是「部署类型」而不是「分支名」。这一点符合直觉，但反过来要注意：原来的 main 分支现在变成了 Preview 部署，它读的是 Preview 组的变量，如果那组没配全，main 的部署会构建失败或者运行时报错。

关闭分支构建的几种粒度

「其余分支的提交也触发构建」这个问题，Vercel 提供了从粗到细好几个开关，按需要选：

1. 全局关掉 Preview 部署 — 就是正文说的把 Branch Tracking 设成 Disabled。最彻底，之后只有生产分支的 push 会构建。适合个人项目，我自己的博客就是这么设的，因为分支只是本地临时用的，不需要每个都生成一个线上预览。

2. 只追踪指定分支 — Branch Tracking 除了 Disabled 还可以填一个模式，只有匹配的分支才构建。比如只让 feature/* 或 release/* 构建，其它分支忽略。适合分支多但只有部分需要预览的团队。

3. 用 vercel.json 精确控制 — 在项目根目录写配置，这是唯一能提交进版本控制、跟着代码走的方式：

{
  "git": {
    "deploymentEnabled": {
      "main": true,
      "dev": true,
      "experimental/*": false
    }
  }
}

值为 false 的分支 push 时 Vercel 直接跳过，不消耗构建额度。也可以整体关掉再单独放行：

{
  "git": {
    "deploymentEnabled": false
  }
}

注意 vercel.json 的这个配置是「读取被 push 的那个 commit 里的 vercel.json」，所以你得先把配置合进相关分支才生效。

4. Ignored Build Step — 最灵活的一层，在 Settings → Git → Ignored Build Step 里写一段 shell，退出码为 0 表示跳过构建，非 0 表示继续构建（注意这个约定是反直觉的，很多人写反）。

最常用的场景是 monorepo 里只有某个子目录变了才构建。Vercel 提供了内置命令：

npx turbo-ignore

或者自己判断变更文件：

git diff HEAD^ HEAD --quiet -- ./apps/blog

这条命令的含义是：比较当前提交和上一个提交，如果 apps/blog 目录没变化，--quiet 会让 git 返回 0（跳过构建）；有变化返回 1（继续构建）。刚好和 Vercel 的约定对上。

另一个常见用法是按提交信息跳过：

if [[ "$VERCEL_GIT_COMMIT_MESSAGE" == *"[skip ci]"* ]]; then exit 0; else exit 1; fi

之后在提交信息里带上 [skip ci] 就不会触发构建，改文档、改 README 的时候很省事。

Vercel 在构建环境里注入的这几个变量都可以用：VERCEL_GIT_COMMIT_REF（分支名）、VERCEL_GIT_COMMIT_SHA、VERCEL_GIT_COMMIT_MESSAGE、VERCEL_ENV（production / preview / development）。

为什么要关掉分支构建

三个实际原因：

省构建额度。Hobby 免费版每月有构建时长限制（历史上是 6000 分钟/月，具体看当前的定价页）。一个分支频繁 push 十几次，每次都构建，额度消耗很快。超了之后所有部署都会被阻塞，包括生产的。

减少通知噪音。Vercel 默认会在 PR 里评论部署结果、发邮件通知。分支多的时候这些通知会把真正重要的信息淹掉。

避免误访问。每个 Preview 部署都有一个公开可访问的 URL（Hobby 版默认不加密码保护）。半成品的分支被搜索引擎抓到、或者 URL 被分享出去，是个实实在在的风险。如果确实需要 Preview 但不想公开，在 Settings → Deployment Protection 里开 Vercel Authentication（只有团队成员能访问）或者 Password Protection（后者需要付费版）。

常见问题

改了分支但部署的还是旧代码。先确认 push 到的分支名和 Production Branch 设置完全一致，包括大小写。另外看 Deployments 列表里最新那条的 Source 列显示的是哪个分支和哪个 commit hash，和本地 git log -1 --format=%H 对一下就知道是不是 Vercel 没收到 webhook。

Webhook 没触发。GitHub 那边可以在仓库 Settings → Webhooks 里看 Vercel 的 webhook 有没有发送成功、返回了什么状态码。如果一直失败，最简单的修法是在 Vercel 项目里断开仓库再重新连一次，会重建 webhook。

分支名带斜杠的部署 URL 很奇怪。像 feature/login 这样的分支，Vercel 生成的 Preview URL 会把斜杠转成连字符，变成 项目名-git-feature-login-用户名.vercel.app。分支名太长时 URL 会被截断并加哈希，这是正常行为，不影响访问。

想彻底不让某个分支存在于 Vercel。关掉构建只是不生成新部署，历史的 Preview 部署仍然可访问。要清掉得在 Deployments 列表里手动删除，或者用 CLI：

vercel ls           # 列出部署
vercel rm <部署名>   # 删除指定部署

删除是不可逆的，删生产部署之前想清楚——虽然域名会自动回退到上一个成功的生产部署，但那个部署的产物也可能已经被清理了。