企业官网建设流程全解析

如果你维护的项目超过三个月，大概率遇到过这种场景：新功能上线后，用户反馈某个页面变卡，或者某个接口偶尔报错。你去翻提交记录，几十条 commit 摊在面前，git log 翻了好几页也看不出哪行代码有问题。这时候最该用的，就是 Git 的二分查找（git bisect）。它不会帮你直接指出 bug 在哪个文件，但能用最短的测试次数，告诉你哪个提交让事情变坏的。我这几年的习惯是：遇到能稳定复现的回退，先跑一遍 bisect，再谈看代码。这篇就把我从上手 bisect 到把它变成日常排查武器的经验，一次讲透。

1. 为什么先用二分法缩小怀疑范围？git bisect 的核心思路

1.1 从线性翻看提交历史，到每次测试砍掉一半

二分查找的原理不难理解：假设你已知一个坏提交和更早的一个好提交，它们之间所有提交形成一个区间。取区间中间的提交测试：如果它是好的，说明问题在它之后；如果它是坏的，说明问题在它之前。每测一次，搜索范围缩小一半。100 个提交只需要约 7 次测试，1000 个提交只需要 10 次。

git bisect 帮你自动完成这个流程。它不会让你自己挑中间点，而是直接切换工作区到某个候选提交，等你给出“好”或“坏”的结论，再自动缩小区间。你不需要把每个 commit 的 diff 都读完，只需要让问题在你的环境里“重现一次”或“不重现”。

这件事的关键是：很多人第一反应是拿 git log 从头翻，看到某个提交像嫌疑就停下来猜。猜一次两次还可以，一旦项目历史复杂、提交粒度又碎，线性翻看的时间成本会高到让你想放弃。二分法最大的价值不是“更快找到具体行”，而是把“读代码判断”的高成本全部转成“运行一次复现”的低成本。

1.2 什么情况适合用 bisect，什么情况不适合

git bisect 特别适合这几类问题：

• 回归 bug：昨天正常，今天异常，中间一堆提交。
• 性能下滑：接口变慢、页面卡顿、构建时间越来越长。
• 行为变更：某个返回值变了、输出格式变了、交互逻辑不对。
• 一些“明明之前可以”的玄学问题，只要你能稳定复现。

不适合的情况反而更需要注意：

• 问题只在线上出现，本地无论哪个提交都复现不了。
• 问题依赖外部环境，比如数据库数据不同、第三方接口返回差异。
• 问题是偶发的，同一次提交测试三次得到三种结果。

我见过不少人上来就git bisect start，结果测到一半发现最开始的 good 提交本身也是坏的，整个区间起点就是错的。所以正式开工前，建议先手动在两个边界上各跑一次复现。确认 bad 提交真的坏、good 提交真的正常，再启动 bisect。边界错了，后面全部白费。

1.3 和 git blame、git log -S 怎么配合

有人会问：git blame不是也能看某一行是谁改的吗？为什么不直接用？

git blame适合你已经知道问题可能集中在某个文件、某个函数的场景。但它只能看“当前这行”的修改来源，如果问题是因为一个对象在多个提交中被反复改型，或者一个函数被重构挪了位置，blame 结果会非常分散。

git log -S '某个字符串'可以反查一个字符串的增删历史，像 grep 一样找变更点。但前提是你要先猜到一个和问题强相关的关键字。很多真实 bug 不是靠关键字能描述出来的，或者说关键字相关性无法确认。

我现在的配合方式是：如果可疑点非常明确，先用git log -S或git blame快速试探，几秒钟能命中最好；如果试了半小时还一头雾水，立刻换 bisect。bisect 不依赖你预先知道任何代码细节，只依赖“能不能复现”，这也是它在定位回归问题时几乎无敌的原因。

2. 从零上手：git bisect 完整排查流程

2.1 开始二分前，先确认好这四件事

第一，明确当前哪个提交是坏的。通常就是主分支上的 HEAD，也可以是一个 tag 或一个明确的 commit。如果问题出现在某个 feature 分支上，最好把你怀疑的分支顶端的 commit 作为 bad。

第二，找到一个确定正常的较早提交。这个范围越靠近问题出现的时间点越好。你选择 good 提交越早，中间需要测试的提交就越多；但也不能为了省次数选得太晚，否则可能把“本来就坏”的提交当成正常。

第三，复现步骤要足够固定。环境、数据、操作顺序最好全部写下来。如果测试结果不稳定，二分就会乱。比如同一个提交第一次卡、第二次不卡，你没法给它打标。

第四，确保工作区干净。bisect 会不断切换提交，未提交的本地改动会跟着乱跑，甚至被 checkout 覆盖。启动前先执行git status --porcelain看一下，有改动就 commit 或 stash。

2.2 启动 bisect，标记坏提交和好提交

假设当前在问题分支上，已知最近的正常提交是abc1234：

git bisect start git bisect bad # 当前 HEAD 是坏的 git bisect good abc1234

三条命令之后，Git 会自动把工作区切换到一个中间提交，并输出类似这样的提示：

Bisecting: 8 revisions left to test after this (roughly 3 steps)

意思是还剩 8 个提交没有排除，大概再测 3 步就能定位。此时你直接在这个中间提交上跑复现流程即可。

如果你不想依赖当前 HEAD，也可以写成一行：

git bisect start HEAD abc1234

git bisect start <bad> <good>这种写法能让你把边界写得更清楚。启动之后尽量别手动切换分支，bisect 需要你停留在它选中的提交上，否则后续标记会变得不可信。

2.3 每轮测试、标记，直到锁定嫌疑提交

启动后的每一轮，你只需要做两件事：跑复现，然后告诉 bisect 结果是正常还是异常。

git bisect good # 当前提交正常 git bisect bad # 当前提交仍然有问题

Git 每次都会切换到新的候选提交，直到只剩下一个。这时会输出类似：

abc7890 is the first bad commit commit abc7890 Author: ... Date: ... fix: adjust list rendering logic

看到这句话并不意味着你马上知道该改哪一行，但你已经把问题范围压缩到了一个提交。接下来可以执行：

git show --stat abc7890 git show --name-only abc7890

看看这个提交改了什么文件，仔细读 diff。很多时候问题在此时就水落石出了。

排查结束后，记得恢复现场：

git bisect reset

这一步会退出 bisect 状态，并把你带回启动前的分支。如果忘了 reset，你的 HEAD 会一直停留在某个中间提交，后续你可能会在错误的分支状态下继续开发。

3. 让排查更省力：git bisect run 脚本实战

3.1 写一个能被 bisect 理解的判断脚本

手动测试适合复现步骤简单的场景。如果你的项目有自动化测试，或者你需要连续定位好几个 bug，完全可以让 bisect 自动跑。

git bisect run的规则很简单：它执行你给的命令，退出码为 0 时标记 good，退出码为 1 到 127 时标记 bad，退出码为 125 时表示当前提交无法判断，需要跳过。

举个例子，如果你有一个回归测试能稳定代表这个 bug：

git bisect run npm run test:regression

npm test 失败时退出码非 0，Git 就自动标记为 bad；测试通过退出码为 0，就标记为 good。整个过程不用人盯着。

建议不要直接写一条命令了事，而是准备一个脚本check-bug.sh：

#!/usr/bin/env bash set -uo pipefail npm install > /tmp/bisect-install.log 2>&1 || exit 125 npm run build > /tmp/bisect-build.log 2>&1 || exit 125 npm run test:regression

然后执行：

chmod +x check-bug.sh git bisect run ./check-bug.sh

这里把 install 和 build 失败都返回 125，是因为这些提交可能因为历史原因缺少依赖锁文件，或者处于一个无法构建的中间状态，不代表那个提交“引入 bug”。如果返回非 0，bisect 会把它当成坏提交，结果就会被污染。

3.2 处理构建失败、超时和不确定结果

自动化最容易被坑的地方是超时问题。某些提交构建时间特别长，或者测试本身会卡死。如果测试命令超时返回 124，而你没有特殊处理，Git 会把它当成 bad（因为 124 在 1 到 127 之间）。但超时可能是环境问题，不一定是这个提交引入的 bug。

建议统一处理：

#!/usr/bin/env bash set -uo pipefail timeout 120 npm run build > /tmp/build.log 2>&1 build_rc=$? if [ $build_rc -eq 124 ]; then # 超时，无法判断，跳过 exit 125 elif [ $build_rc -ne 0 ]; then # 构建失败，要么是中间态问题，要么是真坏了 # 如果你能确认这个提交确实因本次改动无法构建，可以视为 bad； # 无法确认时，更稳妥的是返回 125 exit 125 fi timeout 120 npm run test:regression

再强调一次：125 是你的安全牌。遇到无法判断的情况，宁可 skip 让 bisect 自动选别的提交，也不要乱标记。

还有一个常见坑：在脚本开头写set -e。一旦第一行命令失败，脚本立刻退出，最终退出码可能就是 127 或某个非预期值，Git 会把它当成 bad。所以我习惯用set -uo pipefail，不用set -e，让每个命令的返回码自己决定结果。

3.3 性能问题的特殊自动化写法

性能回归不像普通 bug 那样非黑即白，你需要给脚本设一个阈值。比如我定位过一次接口首屏渲染变慢的问题，当时的脚本大概长这样：

#!/usr/bin/env bash set -uo pipefail npm install > /tmp/p.log 2>&1 || exit 125 npm run build > /tmp/p.log 2>&1 || exit 125 start=$(date +%s%N) node scripts/bench.js > /tmp/bench.out 2>&1 || exit 125 end=$(date +%s%N) duration_ms=$(( (end - start) / 1000000 )) # 阈值 500ms，超过就视为坏提交 if [ "$duration_ms" -gt 500 ]; then exit 1 else exit 0 fi

性能测试的问题在于波动。同一个提交可能第一次 480ms，第二次 520ms。我的经验是至少要跑三遍取中位数，或者把阈值留出足够余量。如果输出本身带耗时数据，你也可以从/tmp/bench.out里解析平均值，不要只看单次结果。

这类自动化脚本跑完，一般十几分钟就能定位到引入性能问题的那个提交。

4. 真实复盘：一次“更新后页面秒开变卡顿”的定位过程

4.1 问题现场与初始信息

有一段时间，我在维护一个内部前端项目（这里叫模拟项目 X）。订单列表页原本从接口返回数据到渲染完成大约是 0.8 秒，一次例行合并后，突然变成了 3 秒多。页面本身能正常打开，接口也没有变慢，明显是渲染层出了性能回退。

第一步，我先在主分支上重新拉代码、复现，确认 HEAD 是坏的。然后又确定一个月前的发布 tagv2.6.0是正常的。这个时间窗口里大概有 60 多个提交，如果一个个翻 git log 肯定翻到崩溃，正好适合 bisect。

4.2 从零开始 bisect 的完整命令记录

启动前先看工作区：

$ git status --porcelain

确认干净后：

$ git bisect start $ git bisect bad $ git bisect good v2.6.0 Bisecting: 34 revisions left to test after this (roughly 6 steps)

然后每一轮我都执行同样的复现：启动前端服务，打开订单列表页，计时观察。下面是当时的标记记录（提交哈希为虚构代称）：

第 5 轮结束后，Git 输出了第一坏提交：

f1a2b3d is the first bad commit

git show --stat f1a2b3d显示这个提交把列表数据格式化的逻辑从原来的“在数据接入时统一转换”改成了“渲染阶段对每条数据做一次深拷贝”，而且深拷贝的目标是整份列表对象。列表有几百行，每条渲染都被重复拷贝一次，复杂度直接变成 O(n^2)，卡顿就是这么来的。

4.3 定位到问题提交后，我们做了什么

先执行git bisect reset回到主分支，然后把那个提交git revert掉。验证一次，页面恢复到 0.8 秒左右。

但真正值得记录的不是这次 revert，而是后续的两件事：

第一，我们把“渲染过程中不做大数据深拷贝”这一条写进了代码评审清单。深拷贝本身没问题，问题是它被放在了渲染热路径上，这是典型的性能陷阱。

第二，给列表页加了一个性能回归测试断言，用它挡在 CI 里。如果渲染耗时超过阈值，直接让测试失败。这样一来，以后再有类似的改动，bisect 甚至不需要被启动，CI 先帮我们拦住了。

这次复盘给我的体会是：bisect 能帮你快速定位到提交，但真正的价值是要把“为什么会慢”想清楚，并沉淀成可执行的防护手段。否则下次换个团队、换个功能，同样的问题还会再来一遍。

5. 常见问题与避坑指南：让 bisect 不再翻车

5.1 边界标错了怎么补救

二分查找最怕边界错。如果你发现最早标记的 good 提交其实也坏，或者 bad 提交不够坏，最好的办法是停止当前过程，重新开始。

git bisect reset git bisect start git bisect bad # 确认真正坏的当前提交 git bisect good 修正后的正常提交

千万不要抱着“先继续测，错了再说”的心态。二分是依赖前后一致性的，一旦某个标记错了，后面所有结果都会跑偏。重新标记一次一般也就损失十几分钟，比起在错误结果上排查一天，已经很便宜了。

如果你跑了一半，有很多 skip 信息不想丢，可以用git bisect log导出状态到文件，稍作修改后git bisect replay恢复。不过我个人更倾向于 reset 重来，因为二分测试次数本来就不多，重跑更干净。

5.2 merge commit 要不要跳过

仓库如果用 merge 开发模式，bisect 会进入 merge commit 的两个父分支来回测。某个 merge commit 被标记为 bad 时，有可能是合并时冲突解决错了，这个提交本身是有意义的。不要看到 “Merge branch” 就觉得它不可能是元凶。

如果合并提交涉及大量代码，手动判断它到底是好是坏很痛苦，可以直接用git bisect skip让它跳过。Git 会选择一个附近且仍能覆盖范围的提交继续。

有一点需要注意：某些 merge 问题只在两个分支的代码“合在一起”时才暴露，单独测任何一个父分支都正常。这时 bisect 就算定位到 merge commit，也不能靠 revert 一个提交解决，而是要看合并时做的冲突处理，用git show --cc审查实际差异。

5.3 中途退出、状态查看与恢复现场

bisect 过程中如果你急着改别的，可以先git bisect reset退出。这个命令会把工作区恢复到启动前的分支，并清掉 bisect 状态。

有一个常见误操作是：bisect 过程中直接git checkout main去改代码。这虽然能切走，但 bisect 的状态还留在仓库里，后续再次 checkout 到别的提交，状态会变得混乱。正确做法永远是先 reset。

如果 bisect 被中断了几天，回到仓库后可以用git bisect log看当前进度，用git bisect visualize可视化剩余候选提交。确认状态后再决定继续还是放弃。长时间不用的 bisect 状态很容易让人忘记 HEAD 其实不在任何分支上，这一点需要格外小心。

5.4 历史被改写、cherry-pick 后还能不能用

如果你的历史被 rebase 过，或者功能是通过 cherry-pick 挑到发布分支的，bisect 依然能用，但定位到的“第一个坏提交”可能需要二次翻译。

rebase 会把多个提交压成一个，bisect 找到的可能是一个包含大量改动的 squash 提交，而不是原始问题提交。你在这个大提交里看到很多文件变化，不一定所有都是问题源头，要结合 reflog 和原始分支对比。

cherry-pick 也一样。问题可能是在某个原始分支上引入的，但发布分支上是另一个 commit hash。bisect 定位到发布分支上的那次 pick 后，还要回到源分支找到对应的原始提交，才能做真正的 revert 或修复。

我的做法是：bisect 定位到提交后，先git show看内容是否确实符合“导致问题”的条件，再通过git log --all --grep或 ref log 反查它在完整历史里的位置。二分只负责告诉你“从哪个时间点开始变坏”，真正“为什么坏”还是要由人来判断。

5.5 关于自动化的最后一个提醒

用git bisect run的时候，脚本一定要在当前提交的干净上下文中运行。如果脚本会写缓存文件，或者依赖某些全局状态，最好在脚本开头清理一遍，避免上次提交的产物污染本次结果。

另外，git bisect run过程中 Git 会频繁 checkout，如果你的项目没有package-lock.json或yarn.lock，每次 install 依赖都可能因为版本漂移让你误判。尽量在启动 bisect 前确认依赖锁定文件是完整的，这能省掉很多 125 和不稳定结果。

最后说一个个人体会：我踩过几次坑之后，现在遇到任何能稳定复现的问题，第一反应都是问自己“这个 bug 是不是最近某个提交引入的”。只要答案是，我就直接git bisect start。比起打开编辑器一行行猜，让 Git 替我走一遍二分，通常更省心。这套方法不只在 Web 项目里有效，后端、客户端、脚本工具，只要代码在 Git 里，都能用同样的节奏快速缩小嫌疑范围。