用 git bisect 二分定位 Bug：告别盲翻提交历史

如果说有一个命令让我在第一次用完之后，脑子里冒出来的第一句话是“这招也太好用了吧”，那一定是git bisect。这不是什么新插件，也不需要额外安装，Git 本身就自带，只是绝大多数人日常只把它当作提交代码的工具，很少意识到它还内置了一套足够聪明的“回归排查器”。

最常见的场景是这样：昨天还好好的功能，今天一跑就报错。你并不确定是谁动过哪里，只知道这个功能以前是正常的。打开git log --oneline，从最近的提交开始一屏一屏往回翻。运气好时，某个 diff 会突然提醒你“原来这里改错了”；运气不好时，连翻二十几个 commit 都看不出问题，最后只能怀疑环境、怀疑缓存、怀疑同事，甚至想直接回滚整条分支。

后来我真正上手用了git bisect，才意识到：它解决的不是“多看几个提交”的问题，而是把一套原来靠感觉和运气的定位过程，变成了一种有锚点、有循环、有退出条件、甚至能被脚本自动执行的工程方法。这个判断，是这篇文章最想讲清楚的事。

1. 别急着翻提交历史，先确认它是不是“能 bisect”的题目

1.1 回归 bug 和偶发问题，处理路径完全不同

git bisect最擅长处理的问题，有一个很典型的特征：代码以前是正常的，某个提交之后就开始不正常了。这个变化通常是单向的，从一个“好状态”翻到“坏状态”，之后没有变回去。

换句话说，它适合的是回归 bug，而不是随机闪现的杂症。

如果你遇到的现象是：同样的代码、同样的输入，今天跑失败，明天又通过；或者同一个提交上连续测三次，两次好、一次坏；那问题大概率不是某个 commit 单独引入的，而是环境、数据、并发、外部依赖等因素叠加出来的。这个时候去 bisect，很可能越 bisect 越糊涂，因为 Git 每次切到一个历史提交，外部状态却并不会跟着重置。

所以真正动手之前，我建议先问三句话：

1. 这个“坏”能不能在当前提交上稳定复现？
2. 我能不能找到一个特别早期的提交，确认它在那个时间点没有问题？
3. 现象是否足够单一？比如只判断“启动失败”“接口返回字段缺失”“页面白屏”，而不是把所有不满意的现象都混在一起。

如果这三句话都能给出明确回答，再往下走。

1.2 两个锚点决定整场排查的质量

git bisect的原理很像在一本历史记录里做二分查找。它需要两个原始锚点：

• 坏提交，通常是当前 HEAD，也就是问题正在发生的地方。
• 好提交，通常是某个 tag、某个发布版本，或者你记忆中“最后一切正常”的那个 commit。

好提交的选择很关键，甚至比坏提交更关键。如果你选了一个太旧的提交，比如三个月前的版本，那么中间可能已经经历了几十次重构，包括依赖升级、接口调整、目录迁移，这些都会让你的“好/坏”判断变得很杂。如果选了一个太新的提交，而这个提交其实也已经坏了，那么整个二分搜索会在错误的方向上收敛，最后可能给你一个完全不相关的结果。

一个稳妥的流程是：

git status # 事先确认工作区是干净的 git log --oneline -20 # 先看最近的历史，找一个可信的好版本 git bisect start git bisect bad # 默认把当前 HEAD 标记为坏 git bisect good <good-commit> # 把最近确认正常的提交标记为好

执行完最后两条命令之后，Git 会先切到一个介于好坏之间的中间提交，然后输出类似“还剩多少个候选提交”的信息。从这一刻开始，真正的问题就变成了：对一个具体的提交，你能不能给出“好”或“坏”的明确判断。

2. 手动二分：从几行命令把可疑范围缩到单个提交

2.1 为什么它每次都能切到“正中间”

表面上看，git bisect只是把候选区间每次切掉一半。但它的聪明之处在于，它不只是按时间顺序从头到尾一个个找，而是根据提交图计算一个“中间点”，让你每次只需要验证一次，就能排除掉大约一半的历史。

你可以把它理解成猜数字游戏：我在 1 到 100 之间想了一个数，你猜 50，我只告诉你“大了”还是“小了”，那么下一次你只需要猜 25 或 75。这种做法的好处是，无论目标藏在哪个位置，需要问的次数都只跟区间大小呈对数关系。

放到 Git 历史里也一样。如果有 32 个候选提交需要排查，理论上最多只需要判断 5 次；如果候选区间扩大到 1024 个提交，也只需要 10 次。真正耗时的不是二分过程本身，而是每一次对当前提交做出的判断。

当我第一次看到 Git 自动切到中间提交时，第一反应是：它居然真的会把我的工作区切到历史上去。这个动作平时可能会让人紧张，但在 bisect 场景里恰恰是最有价值的，因为它把“你怎么看某段历史”变成了“你直接站在这段历史里看问题”。

2.2 每一轮只回答“这次还坏不坏”

进入 bisect 后，Git 会保持在某个历史提交的工作区中。你需要做的，是只针对这一个状态做验证。

例如，问题表现为“登录接口超时”，那你就直接跑一下登录接口，或执行对应的测试用例。如果问题仍然出现，就执行：

git bisect bad

如果问题不出现，就执行：

git bisect good

Git 会立刻根据你的反馈，把候选范围缩小一半，然后自动切换到下一个中间提交。如此循环，直到收敛到某一次提交，并输出类似：

xxx123abc is the first bad commit

看到这句话时，真正的排查工作才刚刚完成一半。它只是告诉你：从这一个提交开始，你观察到的现象出现了。

这里有一个容易忽略的动作：定位到 first bad commit 之后，记得执行git bisect reset，让 Git 退出 bisect 状态，把 HEAD 切回到你原来的分支。否则你会停留在某个历史提交上，后续继续开发时可能满脸困惑。

2.3 first bad commit 不等于根因

很多新人第一次跑通 bisect 后，会误以为这就是答案：找到那个 commit，然后回滚它就行了。但实际工程里，没那么简单。

first bad commit只是“好状态翻转为坏状态”的最近位置，它不一定是问题真正的源头。真正负责的 commit 可能是它，也有可能是它在更早时依赖了某个被重构掉的状态，或者它只是把两个原本没交集的模块最终拼到了一起。

所以定位之后，我建议的执行顺序是：

1. 先git bisect reset回到分支头部。
2. 用git show <first-bad-commit>查看这个提交到底改了什么。
3. 不急着回滚，而是回到现在的代码里，搜索这个提交改动的变量、函数、字段，看它们在最新代码里被谁使用。
4. 修复后，补一个能捕获这个回归的测试。

注意：开始 bisect 之前，先把工作区整理干净。Git 在切换中间提交时需要工作区是干净的，否则会拒绝执行。

3. 自动化的关键：让git bisect run代替人工反复点击

3.1 什么情况下值得把它脚本化

如果一次回归只涉及两三个提交，手动 bisect 已经很快。但真实项目里，候选区间经常长达几十个甚至几百个提交，而每次验证又必须经过安装依赖、编译、启动服务、跑用例等流程。这种时候，手动操作的问题就出来了：人很容易疲劳，而当你每轮都要重复相同动作时，任何一次误判断都可能让整场排查白费。

这时候用git bisect run，逻辑就顺畅多了：给它一段命令或脚本，Git 会自己完成“切提交—跑脚本—根据退出码标记 good/bad—继续切下一个提交”的循环。

Git 对脚本退出码有一个基础约定：

• 退出码 0：表示这个提交是好的。
• 非 0 退出码：表示这个提交是坏的。
• 特殊值 125：表示这个提交无法测试，需要跳过。

很多常见测试工具本身已经符合这个约定。比如npm test如果通过，进程会返回 0；如果用例失败，通常返回非 0。所以你甚至可以直接这样跑：

git bisect run pytest

但在真实项目里，我不建议直接只用一条裸命令，因为你还需要处理依赖安装、日志输出、进程清理等细节。

3.2 写一个“可被 bisect 信任”的脚本

假设项目是 Node.js 写的，回归点是npm test里的某个用例。一个更稳妥的脚本，应该放在仓库目录外，而不是塞进仓库里。

为什么？因为 bisect 在切换历史提交时，会不断改变工作区内容。如果脚本存在仓库内，而那个历史提交还没有这个文件，脚本路径可能失效；即使文件是未跟踪的，一旦你切换到的提交里出现了同名文件，也会产生覆盖和冲突。

一个常见的示例结构是：

#!/usr/bin/env bash # /tmp/check-regression.sh cd /path/to/your/project # 先尝试安装依赖 if ! npm ci > /tmp/bisect-npm.log 2>&1; then exit 125 fi # 运行目标测试，并把结果写入独立日志 if npm test > /tmp/bisect-test.log 2>&1; then exit 0 else exit 1 fi

然后启动：

git bisect start git bisect bad git bisect good <good-commit> git bisect run bash /tmp/check-regression.sh

这个脚本里最值得注意的不是 npm test，而是几处容易踩坑的细节：

• 脚本会先安装依赖；如果安装依赖失败，说明这个提交本身就处于无法测试状态，返回 125 让 Git 跳过它，而不是把它当成“坏提交”。
• 日志输出到/tmp下，避免把生成文件混进 Git 工作区。
• 脚本放在仓库外，避免被历史 checkout 影响。

另外，如果测试需要启动服务或依赖数据库，脚本还应该处理旧进程清理、临时端口、数据重置等问题。因为在 bisect 过程中，前一个提交可能已经启动过某个服务，如果不主动杀掉，后一个提交的测试很可能会连到上一个提交启动的旧进程上，造成严重误判。

3.3 用日志和 replay 让排查过程可恢复

git bisect还有一个很适合工程协作的能力：记录进度。你随时可以执行：

git bisect log > /tmp/bisect.log

这样即使中间被打断，或者你想要把当前排查的状态分享给同事，也可以用：

git bisect replay /tmp/bisect.log

恢复整套二分状态。

这个能力的重要意义在于，排查回归 bug 不只是一种个人操作，也可以变成一份可追溯的记录。当团队里有人接手时，看到的不是一个“我查到第三个提交卡住了”，而是一份明确的判断路径：哪些提交被判定为好，哪些被判定为坏，当前候选区间在哪里。

脚本返回 0 表示“好”，非 0 表示“坏”，125 表示“这个提交无法测试”。不要把构建失败和测试失败混为一谈。

4. 实操里最容易误判的几个边界

4.1 单调性假设并不总成立

git bisect本质上是在依赖一个假设：从“好提交”到“坏提交”之间，状态是单调翻转的。也就是好提交之后某个点变坏，然后一直坏到当前状态。

如果实际情况不是这样，事情就麻烦了。

例如同一个 bug 在三个月前被引入，一个月前被一个重构顺手修好了，前几天又有新提交把它带回来。你拿最新坏提交和三个月前的好提交做 bisect，它会找到一个状态翻转点，但那个翻转点可能不是今天这个 bug 的真正责任人。

又比如，bug 只有在两个提交同时存在时才会出现