Gemini CLI 报 0 occurrences found for old_string 怎么解决？改文件失败的确定性排错
让 Gemini CLI 改一个文件，它报：
0 occurrences found for old_string
这条报错在体验上很挫败——它明明刚读过那个文件，转头就说找不到要改的内容。issue #5629（已关闭）里提这个问题的人用的词是「令人沮丧」。
但它有一个别的报错没有的好处：它是确定性的。 这意味着排查它不用碰运气。
一、先记住一件事：重试没有意义
这是本文最重要的一句话。
Gemini CLI 里的报错大致分两类：
- 随机的：
Premature close、Model stream ended with empty response text、Cannot read properties of undefined之类。这些跟服务端状态、网络、时机有关，重试有可能就过了 - 确定的：
0 occurrences found for old_string。同样的输入，一百次都是同样的结果
分清这两类能省掉大量无效操作。看到这条，别重试、别换网络、别重新登录、别查额度——那些都不会改变结果。
二、成因：替换要求精确匹配
改文件这个动作的机制是：给出一段旧内容（old_string）和一段新内容，工具在文件里找到那段旧内容，替换掉。
找不到，就报这条。
关键在于「找到」是精确匹配——一个字符都不能差。而人眼看起来一模一样的两段文本，字节层面可能完全不同。
三、四类最常见的差异
3.1 空白：缩进和行尾
这是头号原因。
- Tab 和空格：显示宽度可能一样，字节完全不同
- 缩进层级：4 个空格和 2 个空格
- 行尾空格：肉眼完全看不见，但确实在那里
尤其是行尾空格——很多编辑器会显示成什么都没有，但文件里实实在在有一个空格。匹配时它就是不一样。
3.2 换行符：CRLF 和 LF
Windows 用 \r\n，Unix 系用 \n。
跨平台协作的仓库里，同一个文件在不同人机器上可能是不同的行尾。如果匹配的旧内容跨了多行，行尾的差异就会导致匹配失败。
判断方法：如果改单行能成、改多行就失败，很可能就是这个。
3.3 文件已经变了
这个最隐蔽：它读文件的时候是那样，改的时候已经不是了。
可能的原因：
- 你在编辑器里手动改了同一个文件
- 保存时自动格式化工具（Prettier、gofmt、black 之类）动了它
- 另一个进程在改
- 上一步操作已经改过这里了
自动格式化那条特别值得警惕：你只是按了保存，格式化工具把缩进、引号、换行全调了一遍——文件内容变了，而你以为自己什么都没做。
3.4 不可见字符
- 全角空格和半角空格
- 不间断空格（NBSP）
- 零宽字符
- BOM 头
这类从网页复制粘贴过来的代码里特别常见。
四、怎么让它一次改对
第一，让它重新读一遍再改。
最简单也最有效。文件可能已经变了，让它读当前状态，基于当前内容生成替换。
第二，缩短匹配范围。
匹配的内容越长，撞上差异的概率越大。让它只匹配一小段唯一的内容——比如一个函数签名、一个特有的变量名——而不是整段代码。
这条对跨行匹配失败尤其有效，因为短片段通常不跨行，就绕开了换行符问题。
第三，先关掉保存时自动格式化。
如果你在让它连续改一个文件，编辑器的保存时格式化会不断制造差异。改这一轮的时候先关掉，改完再统一格式化。
第四，统一行尾。
跨平台项目里，用 .gitattributes 统一行尾，能一次性解决 3.2 那一类。
第五，实在改不动就换个方式。
如果某处反复匹配失败，别耗着——让它重写整个函数或者整个文件，或者你手动改掉那一处。
卡在一个匹配上反复试，是这类问题里最不划算的做法，因为它是确定性的：这次不行，下次也不行。
五、怎么快速确认是哪一类
按这个顺序，一分钟内能定位：
- 改单行行不行？
- 单行能成、多行不成 → 换行符问题（3.2）
- 让它重读文件再改，行不行？
- 重读就成了 → 文件已经变了（3.3），去查是谁在改
- 把匹配内容缩到最短，行不行？
- 缩短就成了 → 空白或不可见字符（3.1 / 3.4）
- 都不行？
- 换个方式：重写整段，或者手动改
六、跟它容易混的几条
Gemini CLI 里报错的性质差别很大，分清能省时间：
| 报错 | 性质 | 重试有用吗 |
|---|---|---|
0 occurrences found for old_string | 文本匹配失败（工具层） | 没用——确定性的 |
Operation not permitted / Permission denied | 沙箱限制（写到了项目目录或系统临时目录之外） | 没用，要改沙箱配置 |
Premature close | 连接提前关闭 | 有用，偶发 |
Model stream ended with empty response text | 流结束但内容为空 | 有用，偶发 |
Cannot read properties of undefined (reading 'candidates') | 客户端解析崩溃 | 有用，偶发 |
got status: 429 Too Many Requests | 额度或频率上限 | 等一等再试 |
第二条值得单独提一句：如果它报的是权限相关（Operation not permitted、Permission denied），官方说明的成因是沙箱开启时，它试图做被沙箱配置限制的操作，比如写到项目目录或系统临时目录之外。这跟匹配失败完全是两回事——处理要去看官方的沙箱配置文档。对应的退出码是 44（FatalSandboxError）。
七、连续改同一个文件时的工作流
这条报错在「连续改同一个文件」的场景下出现得最密集，因为每改一次，文件就变一次，而它脑子里的版本可能还停在上一次。
几条能明显降低失败率的习惯：
一次只改一处，改完让它确认。 一口气提十个修改点，中间任何一处失败，后面的匹配基准可能全乱了。
中途别用编辑器手动改同一个文件。 你改一行，它那边的匹配基准就作废了。要手动改的话，改完告诉它「我手动改了这里」，让它重读。
关掉保存时自动格式化。 这条前面说过，这里再强调一次，因为它是最隐蔽的一个——你以为你只是保存了，实际上格式化工具重排了整个文件。
大改动直接让它重写整段。 如果一次要动的地方很多、很零碎，与其一处处替换，不如让它把整个函数或整个文件重写。替换的失败率随匹配次数累积，重写只有一次。
改完立刻跑一次 diff 看。 确认改的地方跟你想的一致。匹配成功不等于改对了——它可能匹配到了另一处一模一样的代码。
最后这条值得展开一句：如果文件里有多处相同的代码，精确匹配可能命中的不是你想要的那一处。这种情况下不会报错，你会得到一个「成功但改错地方」的结果，比报错难发现得多。所以匹配内容要选唯一的片段——带上足够的上下文让它唯一，而不是只给一行通用代码。
这跟前面「把匹配范围缩到最短」是一对需要平衡的建议：短到不跨行，但长到足够唯一。
八、总结
- 这条是确定性的，重试没有意义。 分清「随机故障」和「确定故障」是本文最值钱的一点。
- 成因是精确匹配失败，四类常见差异：空白（Tab/空格/行尾空格）、换行符（CRLF/LF）、文件已被改动、不可见字符。
- 最有效的两条做法：让它重读文件再改；把匹配范围缩到最短。
- 连续改一个文件时，先关掉保存时自动格式化——它会在你不知情的时候制造差异。
- 别在一处反复试。 换成重写整段或手动改，比试第五次划算。
- 别把它和沙箱权限报错（退出码 44）混了，那是另一套处理。
本文引用的 issue 编号来自 google-gemini/gemini-cli 仓库，沙箱与退出码说明来自该仓库自带的 troubleshooting 文档，核对日 2026-08-08。