1. 为什么我要花时间折腾Todo Tree的配置刚接手一个跑了三年多的老项目时我做的第一件事不是看架构图也不是翻接口文档而是全局搜索代码里的TODO、FIXME、HACK这些标记。原因很简单——前任开发者留下的注释标记往往比任何文档都诚实。哪个模块是临时拼凑的、哪段逻辑埋了雷、哪个接口等着替换全藏在这些标记里。但问题来了一个中型项目里这类标记少说几百个散落在几十个目录、上千个文件里。靠CtrlShiftF一个个翻效率低到让人想砸键盘。我试过用命令行grep -rn TODO结果输出一大坨没有分类、没有跳转、没有优先级看完就忘。直到我开始认真配置Todo Tree这个插件才真正把“代码里的待办事项”变成了一套可管理、可追踪、可协作的轻量系统。Todo Tree是VS Code生态里一个专门用来收集、归类、展示代码注释标记的插件。它做的事情听起来很简单扫描工作区把匹配到的标记汇总到侧边栏的一棵树里点一下就能跳到对应代码行。但真正把它用好配置才是关键。默认配置只能算“能用”离“好用”差得远。这篇文章就是把我这几年在不同项目里反复调整Todo Tree配置的经验整理出来从匹配规则、标签体系、颜色区分到多根工作区适配、性能优化、团队协作规范全部拆开讲清楚。适合谁看如果你每天在VS Code里写代码项目里有一堆待办标记需要管理或者你正在带团队想统一代码注释规范那这篇内容可以直接抄作业。哪怕你只是想让侧边栏那棵树看起来清爽一点下面的配置思路也能帮到你。2. Todo Tree的核心机制与配置逻辑拆解2.1 它到底是怎么找到那些标记的Todo Tree的工作流程分三步扫描、匹配、渲染。扫描阶段它遍历工作区里的文件默认会跳过.gitignore里忽略的内容以及一些二进制文件。匹配阶段它用正则表达式去每一行里找符合规则的标记。渲染阶段把匹配结果按标签分组以树形结构展示在侧边栏。这里有个容易被忽略的点Todo Tree默认使用的是逐行匹配而不是全文匹配。也就是说一个标记必须完整地出现在某一行里才能被识别。如果你写的是跨行的注释块比如/* * TODO: 这里需要重构 */默认配置下它是匹配不到的因为TODO和后面的描述不在同一行。解决办法要么是把标记写成单行要么在正则里用多行模式但后者会带来性能开销。我的建议是统一写成单行简单直接。另一个关键机制是标签提取。Todo Tree不只是找TODO这个词它还能把标记后面的内容作为“标签”提取出来用于分组和过滤。比如// TODO: 优化查询性能它会识别出TODO是标记类型优化查询性能是描述。如果你写成// TODO(zhangsan): 优化查询性能它还能把zhangsan识别为负责人。这个能力靠的是正则里的捕获组后面配置部分会详细讲。2.2 默认配置为什么不够用装完插件不配置你会遇到几个典型问题。第一它默认只匹配TODO、FIXME、XXX这几个词但实际项目里可能还有HACK、NOTE、OPTIMIZE、REVIEW、DEPRECATED等等。第二所有标记混在一起没有颜色区分TODO和FIXME看起来一样紧急程度分不出来。第三侧边栏的树默认按文件路径分组但有时候你更想按标签类型分组比如把所有FIXME集中看。第四大项目里扫描全量文件会卡需要配置排除规则。这些问题不解决Todo Tree就只是个“稍微方便一点的搜索”。而配置的核心思路就是围绕匹配规则、展示方式、性能控制这三个维度去调整。2.3 配置项的三大分类Todo Tree的配置项在VS Code的settings.json里全部以todo-tree.开头。我习惯把它们分成三类匹配类todo-tree.general.tags、todo-tree.regex.regex、todo-tree.general.tagGroups决定“找什么”。展示类todo-tree.highlights.*、todo-tree.tree.*、todo-tree.general.showActivityBarBadge决定“怎么显示”。性能类todo-tree.filtering.excludeGlobs、todo-tree.filtering.includeGlobs、todo-tree.general.maxFileSize决定“扫多快、扫哪些”。这三类配置互相配合。比如你加了一个新标签就得同时改匹配规则和颜色配置否则新标签会以默认样式出现看起来格格不入。下面我按实际配置顺序一步步拆解。3. 从零开始搭建一套顺手的Todo Tree配置3.1 标签体系设计先想清楚你要追踪什么配置之前先定标签。不要一上来就堆十几个标签那样侧边栏会乱成一锅粥。我的经验是控制在5到8个每个有明确语义。下面是我在多数项目里用的标签集标签含义紧急度典型场景TODO待完成的功能或改进中新功能占位、已知可优化点FIXME已知缺陷需修复高边界条件未处理、临时绕过HACK非常规实现需关注高性能妥协、兼容性绕行NOTE重要说明非待办低设计决策记录、使用提醒OPTIMIZE性能优化点中循环内重复计算、大对象拷贝REVIEW需要复查的代码中逻辑复杂、易出错处DEPRECATED已废弃待移除低旧接口、旧实现残留标签命名建议全大写和普通注释区分开。有人喜欢用中文标签比如待办、修复技术上可行但我不推荐——中文标记在跨团队、跨工具时容易出问题而且输入法切换麻烦。英文大写是行业惯例兼容性最好。标签确定后写进配置todo-tree.general.tags: [ TODO, FIXME, HACK, NOTE, OPTIMIZE, REVIEW, DEPRECATED ]注意这个配置项是数组顺序会影响侧边栏里标签的排列顺序。把最常用的放前面。3.2 正则匹配规则让标记识别更精准Todo Tree默认的正则比较宽松可能会误匹配。比如代码里有个变量叫TODO_LIST它也会被当成标记。要避免这种情况需要自定义正则。默认正则大致是这样的(?:\/\/|#|\/\*|!--|;|--|\*)\s*(TODO|FIXME|...)它要求标记前面有注释符号。但如果你在字符串里写了TODO: something也可能被匹配到。更严格的做法是加上单词边界和冒号要求todo-tree.regex.regex: (//|#|!--|;|/\\*|^|^\\s*(-|\\d.))\\s*($TAGS)(\\([^)]*\\))?:?\\s*(.*)这个正则做了几件事匹配常见注释符号开头$TAGS是Todo Tree的内置变量会自动替换成你配置的标签列表(\\([^)]*\\))?用来捕获括号里的负责人或分类最后的(.*)捕获描述内容。如果你想让标记必须带冒号才算可以把:?改成:这样TODO something就不会被匹配只有TODO: something才行。我倾向于要求冒号因为这样能减少误报。还有一个实用技巧支持TODO[优先级]这种写法。比如// TODO[P0]: 紧急修复可以在正则里加一个捕获组todo-tree.regex.regex: (//|#|!--|;|/\\*|^|^\\s*(-|\\d.))\\s*($TAGS)(\\[[^\\]]*\\])?(\\([^)]*\\))?:?\\s*(.*)这样[P0]会被单独捕获后面可以在展示时用来过滤或排序。3.3 颜色与高亮让紧急程度一眼可见Todo Tree支持为每个标签配置不同的高亮样式。配置项是todo-tree.highlights.customHighlight它是一个对象键是标签名值是样式配置。todo-tree.highlights.customHighlight: { TODO: { background: #FFCC00, foreground: #000000, icon: check, iconColour: #FFCC00 }, FIXME: { background: #FF0000, foreground: #FFFFFF, icon: bug, iconColour: #FF0000 }, HACK: { background: #FF6600, foreground: #FFFFFF, icon: alert, iconColour: #FF6600 }, NOTE: { background: #0099FF, foreground: #FFFFFF, icon: info, iconColour: #0099FF }, OPTIMIZE: { background: #00CC66, foreground: #FFFFFF, icon: zap, iconColour: #00CC66 }, REVIEW: { background: #9933FF, foreground: #FFFFFF, icon: eye, iconColour: #9933FF }, DEPRECATED: { background: #999999, foreground: #FFFFFF, icon: circle-slash, iconColour: #999999 } }颜色选择有讲究。红色系留给FIXME和HACK因为这两个最需要立刻关注。黄色给TODO醒目但不刺眼。蓝色给NOTE冷静、信息性。绿色给OPTIMIZE暗示“改进”而非“问题”。紫色给REVIEW中性偏提醒。灰色给DEPRECATED表示“不重要但别忘”。图标方面Todo Tree内置了一批Octicon图标常用的有check、bug、alert、info、zap、eye、circle-slash。图标颜色建议和高亮背景色一致视觉上更统一。还有一个全局高亮配置todo-tree.highlights.defaultHighlight用来设置没有单独配置的标签的默认样式。我一般设成浅灰背景避免漏配的标签太突兀。3.4 树形展示配置按什么分组、怎么排序侧边栏那棵树的展示方式由todo-tree.tree.*系列配置控制。几个关键项todo-tree.tree.showCountsInTree: true, todo-tree.tree.groupedByTag: false, todo-tree.tree.sortTagsOnlyViewAlphabetically: true, todo-tree.tree.showScanModeButton: false, todo-tree.tree.expanded: false, todo-tree.tree.flat: falseshowCountsInTree打开后每个标签后面会显示数量比如TODO (23)一眼知道有多少待办。groupedByTag决定是按标签分组还是按文件路径分组。我通常设为false按文件路径分组更符合“定位代码”的需求但如果你更关心“所有FIXME集中处理”就设为true。sortTagsOnlyViewAlphabetically在按标签分组时让标签按字母排序。expanded控制树默认是否展开大项目建议设为false否则一打开侧边栏就刷屏。flat设为true会取消层级所有标记平铺适合标记数量少的项目。还有一个很实用的配置是todo-tree.tree.filterCaseSensitive控制过滤时是否区分大小写。默认false搜索todo也能匹配TODO方便。3.5 性能优化大项目里不卡顿的关键项目一大Todo Tree扫描全量文件会明显拖慢VS Code启动和响应。几个优化手段第一排除不需要扫描的目录todo-tree.filtering.excludeGlobs: [ **/node_modules/**, **/dist/**, **/build/**, **/.git/**, **/coverage/**, **/*.min.js, **/*.map ]第二限制单文件大小todo-tree.general.maxFileSize: 1048576这里单位是字节1048576就是1MB。超过这个大小的文件会被跳过避免扫描压缩后的代码或数据文件。第三如果只想扫描特定目录用includeGlobstodo-tree.filtering.includeGlobs: [ **/src/**, **/lib/** ]第四关闭实时扫描改为手动触发。配置todo-tree.general.tags旁边的todo-tree.tree.autoRefresh设为false然后需要时点侧边栏的刷新按钮。这个取舍看个人习惯我一般保持自动刷新但把排除规则配好实际影响不大。实操心得如果你的项目用了monorepo多个包各自有独立的node_modules一定要把**/node_modules/**加进排除列表否则扫描量会翻好几倍。4. 多根工作区与团队协作下的进阶配置4.1 多根工作区里怎么让配置生效VS Code的多根工作区Multi-root Workspace是个好东西但Todo Tree的配置默认是“工作区级别”的也就是每个根文件夹可以有自己的.vscode/settings.json。如果你在顶层工作区文件里配了Todo Tree子文件夹的配置可能会覆盖它。我的做法是在顶层.code-workspace文件里写一份通用配置然后在每个子项目的.vscode/settings.json里只写差异部分。比如顶层配好标签和颜色子项目里只调整includeGlobs。{ folders: [ { path: frontend }, { path: backend }, { path: shared } ], settings: { todo-tree.general.tags: [TODO, FIXME, HACK, NOTE], todo-tree.highlights.customHighlight: { TODO: { background: #FFCC00, foreground: #000000 }, FIXME: { background: #FF0000, foreground: #FFFFFF } } } }然后在frontend/.vscode/settings.json里{ todo-tree.filtering.includeGlobs: [src/**, components/**] }这样顶层配置提供基础子项目做微调不会互相干扰。4.2 团队统一配置的落地方式带团队时最怕每个人Todo Tree配置不一样导致代码注释标记五花八门。统一配置有两个层面一是插件配置统一二是注释规范统一。插件配置统一靠的是把.vscode/settings.json提交到代码仓库。但要注意这个文件里可能包含个人偏好比如主题色、字体大小。解决办法是把Todo Tree相关配置单独抽出来放在一个todo-tree.code-snippets或者用VS Code的“配置文件”功能。更简单的做法是在.vscode/settings.json里只放Todo Tree配置其他个人设置放用户级别。注释规范统一靠的是文档和代码审查。我一般会在项目README里加一节“代码标记规范”明确所有待办标记必须用TODO:开头冒号后跟描述。需要指定负责人的写成TODO(name): 描述。紧急缺陷用FIXME:非常规实现用HACK:。标记必须单独一行不和其他注释混写。已完成的标记及时删除不要留DONE。配合Todo Tree的配置团队里每个人打开项目侧边栏看到的树都是一样的颜色、分组、数量都一致。代码审查时Reviewer可以直接看Todo Tree的统计判断这个PR有没有引入新的FIXME。4.3 和CI/CD结合的思路Todo Tree本身是编辑器插件不直接参与CI。但它的配置思路可以延伸到CI里。比如在流水线里加一个步骤用grep统计FIXME数量超过阈值就告警。或者用脚本解析代码里的TODO(name)自动生成任务列表同步到项目管理工具。我试过的一个方案是在Git提交钩子里检查新增的FIXME如果一次提交新增超过3个FIXME就提示开发者确认。这个阈值可以根据项目阶段调整开发初期放宽上线前收紧。另一个思路是把Todo Tree的标签体系映射到代码扫描工具。比如SonarQube支持自定义规则可以把FIXME注释识别为“待修复问题”纳入技术债务统计。这样编辑器里的待办和质量管理平台的数据就打通了。5. 常见问题排查与避坑指南5.1 标记不显示或显示不全这是最常见的问题。排查顺序如下第一检查标签是否在todo-tree.general.tags里。如果你写了个XXX标记但没配进标签列表它不会显示。第二检查正则是否匹配。可以在VS Code的命令面板里运行Todo Tree: Show Output看插件的日志输出里面会显示扫描了哪些文件、匹配了多少标记。第三检查文件是否被排除。excludeGlobs和includeGlobs如果配错了目标文件可能被跳过。临时把includeGlobs清空看标记是否出现。第四检查文件大小是否超限。maxFileSize默认是1MB如果你的文件超过这个大小会被跳过。第五检查文件语言模式。Todo Tree依赖VS Code的语言识别如果文件没有被正确识别为某种语言注释符号可能匹配不上。比如.vue文件需要Vetur或Volar插件支持。5.2 侧边栏树太乱怎么整理标记一多树就乱。几个整理手段用groupedByTag按标签分组而不是按文件。用showCountsInTree显示数量快速判断哪个标签最多。用expanded: false默认折叠需要时再展开。用flat: true平铺展示适合标记少的项目。用过滤框输入关键词只显示相关标记。还有一个技巧给不同优先级的标记加前缀比如TODO[P0]、TODO[P1]然后在过滤框里输入[P0]只看最高优先级的。5.3 性能问题的排查思路如果VS Code明显变卡Todo Tree可能是元凶之一。排查方法打开命令面板运行Developer: Show Running Extensions看Todo Tree的CPU占用。如果持续偏高说明扫描太频繁或范围太大。优化手段按优先级排序加排除规则把node_modules、dist、build、.git排除。限制maxFileSize比如降到512KB。关闭autoRefresh改手动刷新。缩小includeGlobs范围只扫描源码目录。如果项目特别大考虑只在需要时启用Todo Tree平时禁用。踩过的坑有一次我把excludeGlobs写成了excludeGlob少了个s配置没生效插件扫描了整个node_modulesVS Code卡到无法编辑。后来养成习惯改完配置先看插件输出日志确认排除规则生效。5.4 常见问题速查表问题现象可能原因解决方法标记完全不显示标签未配置检查todo-tree.general.tags部分文件不显示被排除规则跳过检查excludeGlobs和includeGlobs大文件不显示超过大小限制调大maxFileSize颜色不生效标签名拼写错误检查customHighlight的键名侧边栏卡顿扫描范围太大加排除规则、关自动刷新多根工作区配置冲突子项目覆盖顶层顶层放通用配置子项目放差异正则不匹配注释符号不在正则里补充注释符号到正则开头标记重复显示正则捕获组过多简化正则减少捕获组5.5 几个我踩过的坑第一个坑标签名用了小写。Todo Tree默认区分大小写todo和TODO是两个不同的标签。如果你在代码里混用侧边栏会出现两个分组。统一用大写省心。第二个坑正则里的$TAGS变量。这个变量会自动替换成标签列表但如果你在正则里同时写了TODO和$TAGS会导致重复匹配。只用$TAGS就够了。第三个坑颜色配置用了RGB数组。Todo Tree的高亮配置支持十六进制字符串也支持RGB数组但格式要对。我试过写[255, 0, 0]结果不生效后来改成#FF0000才正常。建议统一用十六进制。第四个坑在.gitignore里忽略的文件Todo Tree默认也会忽略。如果你想让某个被git忽略的文件也被扫描需要在todo-tree.filtering.useBuiltInExcludes里关掉内置排除或者手动加includeGlobs。第五个坑多根工作区里如果某个根文件夹没有.vscode/settings.json它会继承顶层配置。但如果你在顶层配了includeGlobs子文件夹可能因为路径不匹配而扫不到东西。解决办法是子文件夹里单独配includeGlobs或者顶层不配includeGlobs让每个子项目自己管。6. 我个人的配置模板与使用习惯6.1 一份可以直接抄的settings.json下面是我在多数项目里用的Todo Tree配置直接复制到.vscode/settings.json就能用{ todo-tree.general.tags: [ TODO, FIXME, HACK, NOTE, OPTIMIZE, REVIEW, DEPRECATED ], todo-tree.regex.regex: (//|#|!--|;|/\\*|^|^\\s*(-|\\d.))\\s*($TAGS)(\\[[^\\]]*\\])?(\\([^)]*\\))?:?\\s*(.*), todo-tree.highlights.customHighlight: { TODO: { background: #FFCC00, foreground: #000000, icon: check, iconColour: #FFCC00 }, FIXME: { background: #FF0000, foreground: #FFFFFF, icon: bug, iconColour: #FF0000 }, HACK: { background: #FF6600, foreground: #FFFFFF, icon: alert, iconColour: #FF6600 }, NOTE: { background: #0099FF, foreground: #FFFFFF, icon: info, iconColour: #0099FF }, OPTIMIZE: { background: #00CC66, foreground: #FFFFFF, icon: zap, iconColour: #00CC66 }, REVIEW: { background: #9933FF, foreground: #FFFFFF, icon: eye, iconColour: #9933FF }, DEPRECATED: { background: #999999, foreground: #FFFFFF, icon: circle-slash, iconColour: #999999 } }, todo-tree.highlights.defaultHighlight: { background: #E0E0E0, foreground: #333333 }, todo-tree.tree.showCountsInTree: true, todo-tree.tree.groupedByTag: false, todo-tree.tree.sortTagsOnlyViewAlphabetically: true, todo-tree.tree.expanded: false, todo-tree.tree.flat: false, todo-tree.filtering.excludeGlobs: [ **/node_modules/**, **/dist/**, **/build/**, **/.git/**, **/coverage/**, **/*.min.js, **/*.map ], todo-tree.general.maxFileSize: 1048576, todo-tree.tree.autoRefresh: true, todo-tree.general.showActivityBarBadge: true }这份配置覆盖了标签、正则、颜色、展示、性能五个方面。你可以根据自己的项目调整标签列表和排除规则。6.2 日常使用中的几个小技巧第一个技巧用TODO[P0]标记最高优先级。在过滤框输入[P0]只看这些。处理完一个就删掉标记保持列表干净。第二个技巧用TODO(name)指定负责人。团队协作时每个人过滤自己的名字只看自己的待办。这个习惯坚持下来代码里的责任归属会清晰很多。第三个技巧定期清理。我每周五下午会花十分钟过一遍Todo Tree把已完成的标记删掉把过期的标记更新。这个习惯让代码里的标记始终可信不会变成“狼来了”。第四个技巧结合Git Blame。看到一个FIXME时用Git Blame看是谁、什么时候加的往往能快速理解上下文。VS Code的GitLens插件和Todo Tree配合很好用。第五个技巧在PR模板里加一条“是否新增TODO/FIXME”。让开发者自己声明Reviewer重点看这些标记。这个简单的流程改进能显著减少“临时标记永久化”的问题。6.3 后续可以怎么扩展Todo Tree的配置本身已经够用但如果想更进一步有几个方向。一是把标记数据导出用脚本生成技术债务报告。Todo Tree的输出日志是结构化的解析起来不难。二是和任务管理工具联动比如把TODO(name)自动同步到看板。三是自定义标签体系比如按模块加前缀TODO-auth:、TODO-payment:然后在过滤框按模块筛选。我最近在试的一个做法是给每个标记加一个“创建日期”写成TODO(2024-06-01): 描述然后用脚本统计标记的平均存活时间。存活时间越长说明技术债务越重。这个数据比单纯的标记数量更有说服力。配置这东西没有一劳永逸的版本。项目在变团队在变Todo Tree的配置也得跟着调。但核心思路不变让标记可见、可分类、可追踪、可清理。做到这四点代码里的待办就不再是“眼不见心不烦”的噪音而是真正能推动项目前进的清单。
