Claude Code 搜不到文件、@file 不好使怎么解决？多半是 ripgrep 跑不起来
有一类问题不报错，但特别耽误事：你让它找一个明明存在的文件，它说找不到。
或者 @ 提及文件的时候补全列表是空的，或者自定义的 agent、skill 死活加载不出来。
这几件事看起来毫不相干，实际上共用一个底层组件。官方排查页把它们列在同一条里：Search 工具、@file 提及、自定义 agent、自定义 skill 找不到文件时，很可能是自带的 ripgrep 二进制在你的系统上跑不起来。
一、为什么这几件事会一起坏
ripgrep 是个搜索工具，Claude Code 自带了一份编译好的二进制。上面那几个功能都靠它去文件系统里找东西。
所以它跑不起来的表现不是「搜索报错」，而是所有依赖搜索的功能一起变哑——不报错，就是找不到。
这也是这个问题难排查的原因：没有报错文本可搜。 你只会觉得「它今天有点笨」。
自带二进制跑不起来的常见原因是运行环境不匹配——比如某些 Linux 发行版用的是 musl 而不是 glibc，或者系统缺少某些依赖库。官方给的解法不是去修那个二进制，而是换用你系统自己的 ripgrep。
二、官方给的完整步骤
第一步：装系统的 ripgrep
按你的平台选：
macOS
brew install ripgrep
Ubuntu / Debian
sudo apt install ripgrep
Alpine
apk add ripgrep
官方补了一句：ripgrep 在 Alpine 的 community 仓库里。如果 apk 说找不到这个包，要去看官方文档里 Alpine Linux 与 musl 系发行版的设置说明。
Arch
pacman -S ripgrep
Windows
winget install BurntSushi.ripgrep.MSVC
第二步：告诉 Claude Code 用系统的那个
把 USE_BUILTIN_RIPGREP 设为 0。两种方式：
shell 环境变量：
export USE_BUILTIN_RIPGREP=0
或者写进 settings.json 的 env 块：
{
"env": {
"USE_BUILTIN_RIPGREP": "0"
}
}
第二种更持久，推荐用这个——shell 变量的问题是换个终端就没了，而这个设置你显然希望它一直生效。
第三步：验证真的切过去了
这一步别省。官方给的验证方法很具体：
claude doctor
看输出里的 Search 那一行：
- 显示的是你系统 ripgrep 的路径 → 切换成功
- 显示
OK (bundled)→ 还在用自带的那份，说明环境变量没生效
第二种情况通常是因为：变量设在了别的 shell 里、写进了配置文件但没重开终端、或者 settings.json 的位置/格式不对。
三、WSL 上那个例外：显示正常，但结果偏少
这是最容易误判的一种情况，官方单独列了一条。
现象：在 WSL 上用 Claude Code，搜索能用，但命中的结果比预期少。
成因：官方说明是跨文件系统读盘的性能损失——WSL 访问 Windows 那边的文件（/mnt/c/）时磁盘读性能有惩罚，导致搜索返回的结果少于预期。
最坑的地方：官方明确写了，这种情况下 claude doctor 显示 Search 是 OK 的。
也就是说，你的验证手段在这里会给出误导性的结论。诊断说没问题，实际结果是残缺的。
官方给的三条对策：
- 搜索写得更具体——限定目录或文件类型，减少要搜的文件数量。官方给的例子是「在 auth-service 包里搜 JWT 校验逻辑」「在 JS 文件里找 md5 哈希的用法」，而不是笼统地全库搜
- 把项目挪到 Linux 文件系统（
/home/下），而不是放在/mnt/c/ - 考虑直接在 Windows 原生跑，跳过 WSL
第二条是根治，第一条是当下能立刻用的缓解。
判断自己是不是撞上这个：项目在 /mnt/c/ 下、跑在 WSL 里、搜索能用但总觉得漏东西——三条都占，基本就是它。
四、排查顺序
把上面串起来：
- 先确认症状范围——是只有搜索不好使，还是
@file、自定义 agent、skill 也一起不好使？一起坏 = 高度指向 ripgrep claude doctor看 Search 那一行- 显示
OK (bundled)且功能确实不好使 → 自带二进制跑不起来，走第 3 步 - 显示系统 ripgrep 路径 → 已经切过了，问题在别处
- 显示 OK 但你在 WSL 且项目在
/mnt/c/→ 走第 5 步，别被这个 OK 骗了
- 显示
- 装系统 ripgrep（按平台用上面的命令）
- 设
USE_BUILTIN_RIPGREP=0，推荐写进settings.json的env块 - WSL 跨文件系统的情况 → 搜索写具体些；根治是把项目挪到
/home/下 - 再跑
claude doctor确认 Search 那一行变成了系统路径
五、还有几种「看起来丢了东西，其实没丢」
WSL 那条给了一个重要提醒：有些「结果不全」是显示层面的，不是真的丢了。 Claude Code 里还有几种类似的情况，认出来能省掉一轮白排查。
大表格只显示前 200 行。 官方排查页写明：Markdown 表格超过 200 行时，只渲染前 200 行，后面跟一句 … N more rows not shown。完整表格仍然在对话里，/copy 会复制全部行。
判断很简单：看有没有那句 … N more rows not shown。 有就是显示上限，数据没丢。确实要看完整的大表格，官方建议让它写到文件里，别在终端里渲染。
（官方还提到 v2.1.208 之前是渲染全部行的，所以恢复一个包含超大表格的会话时，可能会卡在重新渲染上——那是在忙，不是挂了。）
终端里文字花屏。 如果在 VS Code、Cursor 或 Devin Desktop 的集成终端里，字符渲染成方块、糊成一片或者显示成错误的字形，官方说明成因是终端的 GPU 渲染。处理是在会话里跑 /terminal-setup，它会把 terminal.integrated.gpuAcceleration 设成 "off"；也可以在编辑器设置里手动改，然后重载窗口。
这三种情况的共同点是：内容都在，问题在呈现。 排查时先分清「没找到」和「没显示出来」——前者要查 ripgrep 和文件系统，后者要查渲染和显示上限，方向完全不同。
六、顺带说一下 /doctor 和 claude doctor
这两个都在本文出现了，区别值得记住：
/doctor：在 Claude Code 会话里面跑。官方描述它会自动检查安装、设置、扩展和上下文用量，并在你确认后应用它能修的修复claude doctor：在 shell 里跑。claude起不来的时候用这个
本文的验证步骤两个都能用，但如果你只是想看 Search 那一行，在 shell 里跑 claude doctor 更直接。
官方还提到另一个自检入口 /mcp，用来查 MCP 服务状态——跟本文主题无关，但一起记住能省事。
七、搜索变慢或者整机卡顿的话
如果不是「找不到」而是「找得很慢」，或者伴随整机卡顿，那多半不是 ripgrep 的问题，而是资源占用。官方对高 CPU / 内存给的处理是四条：
- 经常
/compact减小上下文 - 两个大任务之间重启 Claude Code
- 把大的构建目录加进
.gitignore - 用
claude --safe-mode起一次，判断是不是插件、MCP 服务或者 hook 引起的
第三条跟搜索直接相关：构建产物目录（node_modules、dist、target 之类）如果没被忽略，每次搜索都要趟一遍。 文件数量可能比源码多一两个数量级，慢是必然的，而且还会把无关结果混进来——这既是性能问题，也是准确性问题。
第四条是通用的分界手段：safe mode 禁用所有自定义，如果在它下面资源占用降下来了，范围就锁定在你装的那些东西里。
八、总结
- 搜索、
@file、自定义 agent 和 skill 一起失灵，是自带 ripgrep 跑不起来的典型信号。这个问题不报错，所以靠症状范围来认。 - 解法是装系统 ripgrep + 设
USE_BUILTIN_RIPGREP=0，推荐写进settings.json的env块。 - 验证看
claude doctor的 Search 行：显示系统路径才算切成功，显示OK (bundled)就是没生效。 - WSL 上有个例外：项目在
/mnt/c/时搜索结果会偏少，而claude doctor此时仍显示 OK——别信那个 OK。根治办法是把项目挪到/home/下。 - Alpine 等 musl 系发行版如果
apk找不到包，要去看官方的 musl 设置说明。
本文所引官方内容来自 Claude Code 官方排查文档，核对日 2026-08-08。各平台的包管理命令与产品行为会变化，以官方文档为准。