速读#
两个故事讲的是同一个偏差：明明最直接的线索就在眼前，却绕去查更高级、更体面的可能。调试的第一优先级不是炫技，而是逐字读报错、比对环境差异；间歇性问题则先想办法稳定复现。
先摆两条规律#
当一份代码本地正常、换到线上或另一台机器才出错时，最省时间的起点通常是先列出两边的差异项：环境变量、依赖与运行时版本、配置文件、权限、路径、网络、数据、并发量和 CPU 架构。它不是“环境一定有错”的定律，因为同一段逻辑在不同数据、负载与时序下也会走到不同分支；它只是一个基于现象的排查顺序：先逐字读错误和上下文，再对比差异并验证请求链，最后才在没有证据时漫游代码。
间歇性 Bug 难在证据稀薄：盯着跑它不犯，一转身它就崩。第一目标是把触发条件收窄，让它更频繁、更可观测——提高并发、固定随机种子、记录请求 ID、输入摘要、版本与耗时，或在隔离环境重放生产请求。稳定复现会大幅提高修复信心，但不是唯一道路；暂时复现不了时仍可以靠崩溃转储、指标和调用链定位，只是不能把“改完暂时没再报”当成已经证明修好。
这两个规律底下是同一个朴素的认知：线索离你越近、越朴素，命中率越高；越高深、越体面的猜测，越容易是把人带偏的叙事。
情人节前夜#
第一个故事在情人节前夜。写 Spring Boot 接口时，一个 @PathVariable 参数怎么都绑定不到方法，请求一直失败。我对着屏幕干瞪了三个小时。
那三个小时里的排查路径是：反复确认路由写法、反复核对参数名、甚至怀疑是 Spring 版本的 bug——就是没去看一眼「变量名和路径占位符对上了没」。
咖啡馆下午#
第二个故事在一个本该轻松的周末下午。抱电脑去咖啡馆，被一个 bug 钉在那两个半小时——FastAPI 接口本地跑得好好的，部署到 VPS 上一访问就 502，uvicorn 日志只有一句 KeyError: 'NOTIFY_WEBHOOK'。
日志明明白白写着那行 KeyError。但因为本地跑没问题，我下意识认定「不可能是这么简单的事」，开始往别的方向钻：怀疑 Nginx 配置，反复对照 proxy_pass，改了又改，重启三四次——其实 502 是网关根本连不上后端，该问的是「后端进程为什么没起来」，不是转发规则写没写对；怀疑 Python 版本差异，本地 3.11 服务器 3.12，花二十分钟对比 changelog，完全无关；怀疑 Docker 网络，进容器 curl 一通证明网络是通的，又是无关。
转机都在离开屏幕之后#
第一个故事的转机发生在洗澡时——离开屏幕，脑子突然冒出“变量名和路径占位符对上了吗”。冲回电脑一看，路径是 {userId}，方法参数却叫 id，又没有显式写绑定名。改成 @PathVariable("userId") Long id 后请求立刻通过；显式写名字也避免了构建是否保留 Java 参数名带来的差异。
第二个故事的转机，是去柜台续了杯水、站着喝完回来的那两分钟。回到座位后我才第一次认真看那行 KeyError：本地 .env 有 NOTIFY_WEBHOOK，它被 .gitignore 正确排除了，服务器部署流程却从未创建对应配置。NOTIFY_WEBHOOK 是必填项，不应该随便给空默认值让应用带病启动；真正的修复是把它纳入部署契约，在 systemd 的 EnvironmentFile=、Compose secret 或平台变量中注入，并在启动时给出明确错误：
notify_webhook = os.getenv("NOTIFY_WEBHOOK")if not notify_webhook: raise RuntimeError("NOTIFY_WEBHOOK is required; configure it before startup")代码仍然快速失败，但下一次看到的是可行动的信息，不是一条需要回忆上下文的裸 KeyError。配置文件权限设为仅服务账号可读，部署后只验证变量存在和服务健康，不把 secret 值打印进日志。
栽过两次之后我刻的两条排查优先级#
栽过两次，我形成了两条很具体的排查纪律。
第一条：本地能跑、线上不行，先查两边有什么不同。 这个信号出现时，我不先给“环境”或“代码”定罪，而是沿着现有错误证据检查配置、版本、权限、数据、负载与网络。
| 顺序 | 检查什么 | 要回答的问题 |
|---|---|---|
| 1 | 错误、时间点与上下文 | 哪一层先失败，原始异常是什么？ |
| 2 | 本地和线上差异 | 配置、版本、权限、数据与负载哪里不同？ |
| 3 | 请求链与连通性 | DNS、端口、代理和后端分别通不通？ |
| 4 | 最小化代码路径 | 哪个输入或分支能稳定触发？ |
第二个故事里，我要是第一秒逐字读那行 KeyError，两个半小时变 30 秒。
第二条：能稳定复现，修复才容易被证伪。 前阵子 FastAPI 接口每隔二三十次请求返回一次 500，单线程一直正常，提高并发后才稳定出现 SQLite 的 database is locked。我最初在关键路径加了很多 print，后来换成带请求 ID、事务起止时间和异常堆栈的日志，才看清是多个写事务重叠且持锁过久。修复不是笼统一句“加锁”：先缩短事务、避免事务里做网络调用，再设置合理的 busy_timeout；WAL 能改善读写并发，但 SQLite 仍只有一个写者，高写入并发成为常态时就该迁到 PostgreSQL，而不是无限延长等待时间。
我犯的是同一个偏差：跳过最直接的线索#
两个故事表面毫无关联，一个 Spring 一个 FastAPI，一个深夜一个咖啡馆。但把排查路径摆一起，底子是同一个错：明摆着的线索就在眼前——一行 KeyError、一个路径占位符——我都没在最该看的时候看它，而是去查更「高级」的可能。Nginx、Python 版本、Spring bug、Docker 网络，这些方向体面、像那么回事，但都不是那一行报错指向的地方。
心理上有个很微妙的偏差在起作用：「这么简单的错不可能是我犯的」。于是下意识往复杂的方向钻，结果恰恰就是那个简单的错。真正让我浪费两个半小时的，不是 bug 难，是方向错了。
而两个转机机制完全一样：离开屏幕的几分钟，大脑从「在已有思路里反复打转」的死循环里跳出来了。我管这叫「热水器驱动开发」——卡超过 40 分钟强制起身，不是放弃，是给潜意识腾地方。它后来救了我不止一次。
别绕开朴素事实#
这两次还让我顺带想通一件更普遍的事：人有一种用更复杂的解释掩盖简单错误的倾向，它不只出在 debug 上。
代码里写 // TODO: 临时方案，记得改 的地方，往往会一直跑到项目下线。我有一段硬编码值，标着“等有空改成配置”，三个月过去仍在生产。后来我想通：如果这个值没有变化需求，就删掉 TODO，诚实保留最简单的实现；如果它确实会因环境变化，就现在纳入配置契约，或至少建一条带触发条件和负责人的任务。只有一句“以后改”既不能约束风险，也不能帮助后来的人判断为什么没改。
这和「跳过最直接线索去查高级可能」是同一种心理结构：用一个更体面、更省事的叙事，回避眼前那个朴素的事实。 这一层想通，是这两次 debug 给我超过 bug 本身的收获——它治了我对「复杂叙事」的本能偏好，提醒我遇到事先看眼前那行报错，再决定要不要往深里钻。
这些是经验，不是定律#
把它们说成「永远有效」就又犯了同一个毛病——用一个高级叙事盖住具体情境。所以边界写清楚：
- 离开屏幕救的是「思路打转」这类卡法；逻辑本身不理解，起身也没用，得去补理解。
- 优先级表是“本地能跑、线上不行”这个信号下的流程，不是所有 Bug 的万能顺序；生产事故仍应先止损并保留证据。
- 「临时即永久」是提醒自己对临时诚实，不是说所有临时方案都该立刻改成正式的——有些临时是真临时，诚实标注即可。
写代码这行，耐心比聪明重要。聪明让你写得快，耐心让你改得完。这两次我学到的其实是更朴素的一句：别绕开最直接那条路。