版本发布后第二天,客服反馈「满减券叠加时订单金额算少了」。上一版 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 轮。

git bisect 的收敛过程
v1.4.0(good) ←──────── 400 commits ────────→ main(bad)
↓ 取中点
中点为 bad → 丢弃右半段,继续在左半段取中点
↓ 重复约 9 次
锁定 first bad commit,输出提交哈希与摘要

三步准备

1. 工作区必须是干净的

bisect 会不断 checkout 不同提交,未提交的改动会让它拒绝切换。先提交、stash 或丢弃:

bash 开始前检查
git status --short          # 输出为空才继续
git stash push -u -m "bisect 前暂存"
git fetch origin --tags     # 确认 v1.4.0 这个 tag 在本地

2. 有一个能自动判定的测试

最理想的是已有的单元测试:能稳定复现问题、失败时返回非 0、通过时返回 0。不要用「打开页面看一眼」这种需要人判断的方式——bisect run 的价值就在于无人值守。

3. 确认「好」的起点

起点必须真的没有这个问题,否则二分结果毫无意义。先手动验证一次:

bash 验证起点
git switch --detach v1.4.0
php vendor/bin/phpunit --filter testOrderTotalWithCoupon
# 预期 PASS;若这里就失败,说明「好」的起点选错了
git switch -

写一个 bisect 脚本

脚本要做三件事:清掉可能掩盖问题的缓存、装好当前提交的依赖、跑那一条能复现问题的测试,并把自己的判断用退出码告诉 Git。

bash bisect-test.sh
#!/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 时,先确认它们「断言失败」和「运行出错」分别返回什么,再照此映射,否则会把环境问题误判成代码问题。

跑起来

bash 执行二分
git bisect start
git bisect bad HEAD          # 当前版本有问题
git bisect good v1.4.0       # 这个版本正常

# 让 Git 自动执行脚本(Windows 下显式用 bash 调用,避免 shebang/换行问题)
git bisect run bash ./bisect-test.sh

输出会一段段滚动,类似:

text bisect 输出
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: 调整满减门槛判断

拿到哈希后先别急着改代码,看看它到底改了什么:

bash 查看嫌疑提交
git show 9d4e5f6a1b
git log -1 --stat 9d4e5f6a1b

结束后一定要复位

bisect 过程中 HEAD 处于游离状态,不 reset 会一直停在那个提交上,很容易让人以为代码丢了。

bash 收尾
# 保存过程记录,便于复盘或在另一个 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 很多,二分可能落在某个合并进来的分支提交上。可以只在主线二分:

bash 只沿第一父提交二分
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 看清那个提交到底改了什么,再动手修。

二分查找不需要灵感,只需要一个能自己回答对错的问题。