解决 VSCode 插件 Todo Tree 中文乱码：ripgrep 编码配置与 TaoToken 统一通道实践

1. 中文 TODO 在 Todo Tree 里变成问号问题到底出在哪VSCode 里装 Todo Tree 的人多半是冲着「把散落在项目里的 TODO、FIXME、NOTE 集中到一个侧边栏」去的。这个插件本身不扫描文件它调用的是 VSCode 内置的 ripgrep 来跑正则匹配。ripgrep 默认按 UTF-8 解码遇到 GBK/GB18030 编码的中文注释字节序列解不出来就会在结果里显示成?????或者一串乱码方块。你打开源文件看是正常中文但 Todo Tree 面板里就是花的原因就在这里——文件编码和 ripgrep 的解码假设不一致。这个场景在国内老项目里特别常见早期 Windows 项目、从 SVN 迁过来的代码库、某些 IDE 默认存成 GBK 的.c/.h/.java文件注释里写着「// 待处理接口超时重试」。Todo Tree 一扫中文全废你根本分不清哪条 TODO 是哪个模块的。更麻烦的是有些文件是 UTF-8有些是 GBK混在一起单一编码参数还会顾此失彼。我试过的排查路径是这样的先确认文件真实编码再确认 ripgrep 拿到的参数最后才是改配置。很多人一上来就改settings.json但没搞清 ripgrep 的-E参数到底作用在哪一层改完没生效就放弃了。下面把这条链路拆开讲顺带说清楚怎么用 TaoToken 把 AI 辅助相关的 Key 和 API 通道统一管起来避免每个插件各配一套、互相打架。2. 先搞懂 ripgrep 的编码参数与 Todo Tree 的调用关系Todo Tree 的扫描逻辑是读取你配置的todoTree.ripgrepArgs拼到它内部调用的 ripgrep 命令后面。ripgrep 有一个-E/--encoding选项用来指定「当文件没有 BOM 时按什么编码解码」。注意关键词没有 BOM。如果文件带 UTF-8 BOMripgrep 会优先认 BOM不带 BOM 的 GBK 文件才会走-E指定的编码。所以-E gbk能解决大部分无 BOM 的 GBK 中文注释乱码。但如果你项目里 UTF-8 和 GBK 混用-E gbk会把原本正常的 UTF-8 文件也按 GBK 解反而把 UTF-8 中文搞乱。这时候有两个思路一是统一项目编码治本但老项目动不得二是用--encoding的自动探测能力或者干脆分工作区配置。ripgrep 支持的编码名包括utf-8、gbk、gb18030、utf-16le、utf-16be、latin1等。gb18030是 GBK 的超集兼容性更好遇到生僻字也不容易崩。实测下来老项目直接上gb18030比gbk更稳。这里要提醒一句Todo Tree 的ripgrepArgs是数组形式不是字符串。写错格式插件会静默忽略你以为是编码没生效其实是参数根本没传进去。下面给可复制的配置。3. 可复制的 settings.json 配置与 ripgrep 编码选项打开 VSCode 的settings.jsonCtrlShiftP→Preferences: Open User Settings (JSON)加入或修改这一段{ todoTree.ripgrepArgs: [ -E, gb18030 ], todoTree.ripgrepCaseSensitive: false, todoTree.ripgrepWholeWord: false, todoTree.tags: [ TODO, FIXME, NOTE, 待处理, 待办 ] }如果你只想在某个工作区生效把同样的内容写进项目根目录的.vscode/settings.json不要动全局配置。这样不同项目可以用不同编码互不干扰。对于 UTF-8 和 GBK 混用的仓库可以退一步不强制单一编码而是让 ripgrep 按 BOM 和启发式判断{ todoTree.ripgrepArgs: [ --encoding, auto ] }auto在 ripgrep 里会尝试根据 BOM 和内容猜测但对纯 GBK 无 BOM 文件识别率一般。所以更稳的做法是主工作区用gb18030如果发现 UTF-8 文件被误伤再针对该子目录单独配。VSCode 支持多根工作区每个根目录可以有自己的.vscode/settings.json。另外Todo Tree 默认只扫它认为的「代码文件」如果你发现某些.txt或自定义后缀没被扫到需要配todoTree.includeGlobs{ todoTree.includeGlobs: [ **/*.{js,ts,java,c,h,cpp,py,go,md,txt} ] }改完配置后Todo Tree 不会自动重扫需要手动触发点侧边栏 Todo Tree 面板右上角的刷新图标或者CtrlShiftP执行Todo Tree: Refresh。4. 验证请求与成功结果确认中文 TODO 正常显示配置改完怎么确认真的生效了分三步。第一步确认 ripgrep 参数被正确传入。在 VSCode 里打开命令面板执行Todo Tree: Show Output看输出通道里打印的 ripgrep 命令行。你应该能看到类似ripgrep --encoding gb18030 --json -e TODO -e FIXME ...如果没看到--encoding说明ripgrepArgs格式写错了回去检查是不是写成了字符串-E gb18030而不是数组。第二步造一个测试文件。在项目里新建test_encoding.c用 GBK 编码保存VSCode 右下角编码 →Reopen with Encoding→GBK→Save with Encoding→GBK内容写// 待处理这里的中文注释应该被 Todo Tree 正确识别 // TODO: 补充超时重试逻辑第三步刷新 Todo Tree看面板里是否出现「待处理这里的中文注释应该被 Todo Tree 正确识别」。如果显示正常说明编码链路通了。如果还是乱码看下一节的排查。对于用 TaoToken 统一管理 AI 辅助配置的团队这一步还可以顺带验证在 VSCode 里通过 TaoToken 的模型对话通道让 AI 帮你检查settings.json是否有语法错误。TaoToken 的 API 地址是https://taotoken.net/apiKey 在控制台生成模型对话入口在 deep link 里可以直接打开。这样编码配置和 AI 辅助走同一套 Key不用每个插件单独填。5. 本篇常见错排查改完还是乱码怎么办错误一ripgrepArgs写成了字符串。这是最高频的坑。必须是数组每个参数一个元素。写成todoTree.ripgrepArgs: -E gb18030插件不认。错误二文件带 BOM-E不生效。如果 GBK 文件被某个编辑器加上了 UTF-8 BOMripgrep 会优先按 BOM 解-E gb18030被忽略。用十六进制工具看文件头是不是EF BB BF是的话去掉 BOM 再存成纯 GBK。错误三UTF-8 文件被gb18030误伤。表现是原本正常的中文变成乱码。解决办法是给 UTF-8 子目录单独配utf-8或者把项目编码统一。VSCode 的files.encoding和files.autoGuessEncoding也会影响保存时的编码建议开启files.autoGuessEncoding: true减少新文件编码混乱。错误四Todo Tree 缓存没刷新。改完配置必须手动 Refresh插件不会监听settings.json变化自动重扫。错误五ripgrep 版本太老不支持gb18030。VSCode 内置的 ripgrep 一般较新但如果你手动指定了外部 ripgrep 路径可能版本落后。检查todoTree.ripgrepPath是否指向了旧版本。错误六多根工作区配置覆盖。全局配了gb18030某个根目录的.vscode/settings.json又配了utf-8后者优先。排查时先看当前文件属于哪个工作区根。如果排查过程中需要 AI 帮你读报错日志可以用 TaoToken 的模型对话通道把Todo Tree: Show Output的内容贴进去问。TaoToken 的接入文档里有各语言 SDK 的调用示例API Key 在控制台统一生成coding-plan 适合长期做编码辅助的团队把 Key 和额度集中管理避免每个成员各自申请、配置散落。6. 用 TaoToken 统一 Key/API 通道让 AI 辅助配置不再散落编码问题解决后还有一个隐性成本项目里往往不止 Todo Tree 一个插件需要 AI 能力。代码补全、注释生成、报错解释、commit message 生成每个插件可能都要填一次 API Key、选一次模型、配一次地址。时间一长Key 散落在各个插件的配置里换人、换机器、轮换 Key 都是灾难。TaoToken 的做法是提供一个统一的 API 通道地址https://taotoken.net/api所有支持自定义 OpenAI 兼容接口的插件都指向这里Key 只在控制台生成一次。模型对话、coding-plan、API Keys 管理、接入文档都有独立的 deep link 入口团队里谁需要什么权限发对应的链接就行。具体到 VSCode 场景你可以把 Todo Tree 的编码配置和 AI 辅助配置放在同一个.vscode/settings.json里管理前者管 ripgrep 参数后者管 API 地址和 Key 引用。Key 本身不建议硬编码进 settings用环境变量或者 TaoToken 控制台生成的受限 Key配合.gitignore排除本地配置。这样一套下来中文 TODO 乱码是一次性解决的AI 辅助通道也是统一收口的。下次再遇到类似「某个插件扫描中文出问题」的情况排查思路是一样的先看它底层调的是什么工具再看那个工具的编码参数最后才是插件层的配置格式。ripgrep 这条链路在 VSCode 生态里被大量插件复用掌握一次后面省很多事。