版本发布后第二天,客服反馈「满减券叠加时订单金额算少了」。上一版 v1.4.0 是正常的,main 上已经多了 400 多个提交,谁都说不出是哪次改动引入的。靠肉眼翻 git log,一小时也未必有结论;而 git bisect run 可以把这个过程交给一个几行的脚本,让 Git 自己做二分查找,通常 9 轮左右就能定位到「第一个坏提交」。
这篇是完整实战:从准备可判定的测试、写 bisect 脚本、读懂退出码,到收尾复位与避免缓存误判。所有命令在 Git 2.5+ 可用,脚本以 PHP + PHPUnit 为例,换成任何能返回退出码的测试命令都一样。
先搞清楚 bisect 在做什么
二分查找的前提只有两个:一个已知正常的起点,一个已知异常的终点。Git 会在两者之间取中点检出,你告诉它这个点是「好」还是「坏」,它据此把范围砍半,直到锁定第一个坏提交。400 个提交需要多少次?2 的 9 次方是 512,所以最多 9 轮。
三步准备
1. 工作区必须是干净的
bisect 会不断 checkout 不同提交,未提交的改动会让它拒绝切换。先提交、stash 或丢弃:
git status --short # 输出为空才继续
git stash push -u -m "bisect 前暂存"
git fetch origin --tags # 确认 v1.4.0 这个 tag 在本地
2. 有一个能自动判定的测试
最理想的是已有的单元测试:能稳定复现问题、失败时返回非 0、通过时返回 0。不要用「打开页面看一眼」这种需要人判断的方式——bisect run 的价值就在于无人值守。
3. 确认「好」的起点
起点必须真的没有这个问题,否则二分结果毫无意义。先手动验证一次:
git switch --detach v1.4.0
php vendor/bin/phpunit --filter testOrderTotalWithCoupon
# 预期 PASS;若这里就失败,说明「好」的起点选错了
git switch -
写一个 bisect 脚本
脚本要做三件事:清掉可能掩盖问题的缓存、装好当前提交的依赖、跑那一条能复现问题的测试,并把自己的判断用退出码告诉 Git。
#!/usr/bin/env bash
# 退出码约定:
# 0 = 正常(good)
# 1 = 复现问题(bad)
# 125 = 这个提交没法测,跳过(skip)
set -u
# 1) 清缓存:编译产物、框架缓存、OPcache 文件缓存都可能让旧结果残留
rm -rf var/cache/* 2>/dev/null
rm -rf bootstrap/cache/*.php 2>/dev/null
# 2) 按当前提交的 composer.lock 安装依赖
composer install --no-interaction --prefer-dist --quiet >/dev/null 2>&1
if [ $? -ne 0 ]; then
echo "[skip] 依赖安装失败,跳过该提交"
exit 125
fi
# 3) 跑能复现问题的那一条测试
php vendor/bin/phpunit --filter testOrderTotalWithCoupon >/tmp/bisect-phpunit.log 2>&1
code=$?
case $code in
0) exit 0 ;; # 通过
1) exit 1 ;; # 断言失败,按 PHPUnit 约定视为复现
*) exit 125 ;; # 配置错误、致命错误等,跳过,别污染判定
esac
1 当「复现」、其它非 0 当「跳过」,是以 PHPUnit 的约定为例。换成 Jest、pytest 时,先确认它们「断言失败」和「运行出错」分别返回什么,再照此映射,否则会把环境问题误判成代码问题。跑起来
git bisect start
git bisect bad HEAD # 当前版本有问题
git bisect good v1.4.0 # 这个版本正常
# 让 Git 自动执行脚本(Windows 下显式用 bash 调用,避免 shebang/换行问题)
git bisect run bash ./bisect-test.sh
输出会一段段滚动,类似:
Bisecting: 200 revisions left to test after this (roughly 8 steps)
[3f2a1bc9d0] refactor: 提取优惠券计算服务
...
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[9d4e5f6a1b] fix: 调整满减门槛判断
9d4e5f6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e is the first bad commit
commit 9d4e5f6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e
Author: ...
Date: ...
fix: 调整满减门槛判断
拿到哈希后先别急着改代码,看看它到底改了什么:
git show 9d4e5f6a1b
git log -1 --stat 9d4e5f6a1b
结束后一定要复位
bisect 过程中 HEAD 处于游离状态,不 reset 会一直停在那个提交上,很容易让人以为代码丢了。
# 保存过程记录,便于复盘或在另一个 clone 里重放
git bisect log > /tmp/bisect-2026-11-17.log
# 回到 bisect 开始前的分支
git bisect reset
# 需要复现同一过程时
git bisect replay /tmp/bisect-2026-11-17.log
五个让结果失真的坑
1. 缓存和编译产物没清
框架缓存、var/cache、OPcache 的文件缓存、前端构建产物,都可能让「新代码 + 旧缓存」跑出错误结论。bisect 脚本里必须显式清理,且清理要在切到该提交之后执行。
2. 测试本身不稳定
偶发失败的用例会把好提交判成坏提交。做法:先在几个已知提交上连续跑 3 次,确认结果稳定;或者在脚本里失败后重跑一次,两次都失败才返回 1。
3. 依赖装不上却返回了「坏」
某个中间提交的 composer.lock 指向已删除的包版本,composer install 失败。如果脚本直接 exit $?,Git 会把这个提交当成 bad,结论直接跑偏。这类情况必须 exit 125 跳过。
4. 跳过太多,精度下降
大量 125 之后,bisect 可能提示只剩被跳过的提交,无法给出确定结论。能修则修(补一个最小构建脚本),不要盲目跳过。
5. 合并历史干扰判断
如果 main 上 merge 很多,二分可能落在某个合并进来的分支提交上。可以只在主线二分:
git bisect start --first-parent
git bisect bad HEAD
git bisect good v1.4.0
git bisect run bash ./bisect-test.sh
什么时候值得上 bisect run
| 适合 | 不适合 |
|---|---|
| 回归范围大(几十到上千提交),且能自动判定成败 | 问题只能靠肉眼判断(样式错位、文案不对) |
| 有稳定的单元测试或可脚本化的接口测试 | 每次构建要几十分钟,二分成本高于人工排查 |
| 依赖可以用锁文件复现,环境相对固定 | 依赖外部服务、数据状态无法复现 |
总结
git bisect run 不要求你聪明,只要求你能把「这个版本有没有问题」写成一个返回 0 或 1 的脚本。准备工作其实只有三件:干净的工作区、稳定的测试、确认过的 good 起点。剩下的交给 Git,400 个提交 9 轮收敛,比翻日志可靠得多。最后别忘了 git bisect reset,以及先用 git show 看清那个提交到底改了什么,再动手修。
二分查找不需要灵感,只需要一个能自己回答对错的问题。