VSCode离线文档索引损坏需先排除search.exclude/files.exclude误配，再删除工作区.vscode/.search目录并重启重建索引；WSL2需调高inotify.max_user_watches，企业环境需将rg.exe加入杀软白名单。
VSCode离线文档索引损坏怎么修复
VSCode 离线文档索引损坏，本质是 .search 缓存目录状态异常或底层索引构建失败，不是“文档丢了”，而是 VSCode 找不到已存在的文件内容——常见于 WSL2、NTFS 监听失效、杀毒软件拦截或大文件跳过之后的静默断链。
先确认是不是真“索引损坏”，而不是被排除了
很多所谓“搜不到文档”其实是 search.exclude 或 files.exclude 误配导致的。VSCode 不会告诉你“这个路径被跳过了”，它只会安静地不索引。
- 打开搜索面板（
Ctrl+Shift+F），右下角点!图标，临时关闭「使用排除规则」；如果立刻能搜到，说明就是排除配置在拦路 - 检查
settings.json中是否写了"**/docs/**": true这类通配符——漏掉前后**/会导致匹配错位（比如"docs"会误匹配mydocs） - 远程开发（WSL/SSH）下，
files.exclude有时会间接干扰索引构建，建议只用search.exclude控制搜索范围
删掉 .search 目录强制重建索引
.search 是 VSCode 在工作区根目录下自建的索引缓存目录（路径如 ~/project/.vscode/.search），它不加密、不压缩，纯结构化数据。损坏后不会报错，但搜索响应变慢或返回空结果。
- 必须先彻底退出 VSCode：Windows 杀光
Code.exe和Code Helper.exe；macOS 查Electron进程；Linux 执行pkill -f "code.*--no-sandbox" - 进项目根目录，删掉
.vscode/.search整个文件夹（注意不是.vscode/search，后者不存在） - 重启 VSCode，它会在状态栏显示 “Indexing…” —— 等进度条走完再试搜索
- 若项目含大量 Markdown 或 JSON 文档，可提前在设置里调高
search.maxFileSize（默认约 50MB），避免单文件被跳过
rg.exe 被拦截或 inotify 失效时的底层修复
VSCode 全局搜索底层依赖 rg.exe（ripgrep），它靠操作系统事件监听文件变化。一旦监听失败，索引就卡住不动——这在 WSL2 或企业环境最常见。
- WSL2 用户检查：
cat /proc/sys/fs/inotify/max_user_watches，若低于 524288，执行echo 524288 | sudo tee /proc/sys/fs/inotify/max_user_watches - 企业电脑（装绿盾/北信源等）：把 VSCode 安装目录下的
rg.exe路径（如resources/app/out/vs/workbench/contrib/search/browser/rg.exe）加进终端防护白名单 - Windows NTFS 下索引丢事件：临时改用
code --disable-gpu启动，可绕过部分图形驱动引发的监听中断 - 验证 rg 是否可用：终端进项目根目录，直接运行
rg -i "关键词"，如果返回空或报错，说明问题出在 rg 层，不是 VSCode 配置
真正难修的不是 .search 目录，而是那些没日志、不报错、只默默跳过的拦截点——尤其是 WSL2 的 inotify 限制和企业级终端防护，它们不会弹窗，也不会写 error，只会让搜索变成“薛定谔的索引”。
