3. 源代码管理引起的构建失败（分支、合并冲突）

说实话，我见过最多CI翻车现场，就是分支合并这一关。代码写得挺好，一合并全崩。

为什么会这样？因为很多人只关注“代码能不能跑”，忽略了“分支管理是门手艺活”。我个人习惯是：每做一次合并，先问自己三个问题——基线在哪？冲突在哪？构建环境能否安全合并？

3.1 分支策略：你选对了吗？

Git flow、GitHub flow、Trunk-based……用哪种不是重点。重点是团队有没有统一执行。我见过一个项目，三个人三种分支模型，合并后依赖全乱，构建直接红一片。

下面这个表，是我在实际项目中整理的几种常见分支模型对比：

模型	适用团队	合并频率	CI失败风险
Git flow	大型发布周期项目	中	中（长周期分支容易积累冲突）
GitHub flow	持续部署团队	高	低（尽早合并，冲突小）
Trunk-based	DevOps成熟团队	极高	低但需要强测试覆盖

我个人习惯：小团队用GitHub flow，大团队用Trunk-based配合短命特性分支。不要搞3个月以上的分支，那是给自己埋雷。

3.2 合并冲突：不是暴力解决的

合并冲突本身不可怕，可怕的是随便选一个版本就提交了。

我曾经接手过一个线上事故：同事在解决package.json冲突时，直接选了本地分支的版本，结果把生产依赖版本降回去了。构建虽然过了，但上线后依赖不兼容，服务挂了20分钟。

所以我的建议是：

1. 不要用IDE的“自动合并”功能直接点确定，尤其对于构建配置文件、包管理文件、数据库迁移脚本。
2. 冲突文件先手动拉取两边差异，逐行比对。
3. 如果冲突涉及第三方库版本，跑一遍 npm ci 或 go mod verify 确保锁文件一致。

3.3 构建配置文件的“隐形杀手”

你知道吗？大多数分支合并导致的构建失败，根本不是代码逻辑冲突，而是配置文件冲突。

常见的“隐形杀手”包括：

• .gitignore：不同分支添加了不同忽略规则，合并后漏掉了本该忽略的文件，导致构建时污染环境。
• Dockerfile / .dockerignore：基础镜像版本不一致，合并后构建产物突然变了。
• Makefile 或构建脚本：变量定义冲突，导致构建参数传递错误。
• CI配置文件（如 .gitlab-ci.yml、.github/workflows/*.yml）：合并后语法错误直接让流水线失效。

针对这个问题，我团队的做法是：所有构建配置文件中禁止存在语义冲突。如果不同分支需要不同配置，用环境变量或条件判断来区分，而不是在同一个文件里反复改。

3.4 解决冲突的“三板斧”

当我遇到合并冲突导致CI失败时，我通常按这个流程排查：

1. 先看CI日志中失败的任务是哪个 —— 通常是编译、测试、打包中的某一步。
2. 定位冲突文件 —— 用 git status 看哪些文件处于unmerged状态。
3. 检查冲突内容 —— 是不是构建配置文件？是不是第三方依赖锁文件？如果是，手动合并时一定记得执行一次 npm install 或 go mod tidy 更新锁。
4. 跑一次本地构建 —— 确认本地能过再推送。
5. 如果可以，让两个人互相review合并结果 —— 我发现一个人经常会漏掉关键差异。

3.5 自动化的“安”

光靠人眼是不够的。我建议在CI流水线里加上前置检查：

• 合并前检查：在PR/MR阶段，使用 git diff --check 检查是否有空白符冲突或二进制冲突。
• 构建配置格式化检查：用yaml格式校验，防止合并后语法错误。
• 依赖完整性检查：比如npm ci先跑一遍，发现锁文件不对直接拒绝合并。
• 分支命名规范检查：防止用feature/xxx直接合并到main。