今天遇到一个很离谱的 bug。
需求本身非常简单: 在博客首页那段 You can't connect the dots 的引言下面，加一个 GitHub 贡献日历。
过程却异常曲折。最开始我怀疑是文件编码有问题，于是先检查了首页文件:
- 没有 BOM
- 没有非法控制字符
- 没有替换字符
U+FFFD - 没有 emoji
- 没有任何非 ASCII 字符
后来甚至把文件明确重写成了 UTF-8 with BOM，结果还是一样: 只要准备在那段引言后面插入最后一行组件，Codex 就会卡住或者直接挂掉。
更诡异的是，别的编辑操作都能成功:
- 新建组件文件可以
- 在首页顶部加
import可以 - 读取这个文件也完全正常
- 只有“把组件插到那段文案后面”这一步最容易失败
所以这件事最后看起来不像是文件内容脏了，也不像编码坏了，更像是补丁工具在某个特定上下文附近匹配失败，或者直接进入了一种很奇怪的状态。
最后的解决办法反而很朴素: 不再做“单点插入”，而是改成替换一小段上下文。
也就是把这几行:
</p>
{替换成:
</p>
<GitHubCalendar username="66CF" />
{结果这次一次成功。
这次 bug 说明了什么
有时候“看起来像编码问题”的 bug，未必真是编码问题。
如果一个文件:
- 能正常读取
- 能正常显示
- 能成功做别的局部修改
- 唯独某个补丁位置老是失败
那就应该怀疑是编辑工具本身的补丁匹配机制，而不是继续死磕字符集。
留个结论
以后再遇到类似情况，可以按这个顺序排查:
- 先查编码、控制字符、替换字符、emoji。
- 如果文件本身干净，就不要一直怀疑文本内容。
- 把“大块插入”改成“小范围替换上下文”。
- 实在不行，就拆成两个极小改动，逐步逼近失败点。
这类 bug 的逆天之处不在于它有多复杂，而在于它非常像一个很常见的问题，但根本不是那个问题。