很多开发者在代码里都有这种经历：遇到临时问题，随手敲一行// TODO: 这里待优化，或者标注// FIXME: 逻辑有坑，写完继续往下赶进度。两周以后这个文件被改了七八次，回头想找那行 TODO，全靠翻历史记录，运气好十分钟，运气差一个下午就没了。VSCode Todo Tree 插件解决的正是这个痛点，它能把代码里所有注释标记统一扫进一个树状列表，打开编辑器就能看到还有哪些遗留任务没有处理。这一篇我打算一次讲透三件事：Todo Tree 怎么装怎么配，TODO / FIXME / XXX 这三种标记到底怎么用才是正确的，以及怎么在 VSCode 里做一套属于自己的 TODO 图标样式。内容不算短，但从基础原理到实操配置都会覆盖，适合刚接触插件的入门用户，也适合想规范团队注释习惯的开发者参考。1. 为什么要在代码里写标记，又为什么要用 Todo Tree1.1 三种标记的职责划分经常有人问，TODO、FIXME、XXX 到底有什么区别？在 VSCode 的默认认知里，TODO 就是待办事项，FIXME 是这里有 bug 需要修，XXX 被大部分团队当作“这里很危险，动之前要想想”。我个人的理解更简单直接：TODO 是“未来要做的功能”，FIXME 是“已知要修的缺陷”，XXX 是“请务必注意、容易踩坑的地方”。这个区分不是拍脑袋定的，它直接影响代码的排查路径。假如一个接口在临界条件下会返回空对象，你只写一行// TODO: 判断空值，三个月后接手的人会把它当成普通功能优化，排期排到天荒地老。但如果你写成// FIXME: 这里未判空会导致崩溃，任何人看到的第一反应就是“需要立刻处理”。语义化的标记比单纯的中文注释靠谱，因为可被工具识别，也能统一所有人的心智模型。我自己在实际项目里遇到过更典型的例子：某段临时逻辑写死了一个阈值，上线后业务量翻倍，系统开始在高峰期超时。代码里当时写的是// 注意：这里写死不能改，结果新来的同事真的没敢改，直到问题爆发。后来我复盘才意识到，如果用XXX标记并附带保护期限，任何人在 Todo Tree 里扫一眼就会知道“这个临时方案已经到期了，必须处理”。三种标记的分工可以简单归纳成一张表：标记语义典型场景紧急程度TODO待完成功能后续要接接口、优化性能、补充分支逻辑低FIXME已知缺陷崩溃、超卖、内存泄漏、兼容性问题高XXX危险代码临时方案、写法反常、容易误改极高1.2 从“搜代码”到“看清单”的转变Todo Tree 干的事情其实很朴素，本质就是“正则匹配 + 树形展示”的扫描器。它启动后会遍历你当前打开的工作区文件，用你配置的正则表达式匹配代码注释，命中 TODO / FIXME / XXX 就把那一行收进侧边栏树节点。编辑器保存文件和变更文件时，插件会自动重新扫描，所以写一行新注释保存后立刻就能在树里看到。这里有个容易被忽略的点：Todo Tree 不是搜索引擎。它面向的是“已知我要找什么”的人。你不需要记得 TODO 在哪个文件哪个函数，只要打开侧边栏，所有待办任务按文件目录层级铺开，节点上还能显示数量统计，双击直接跳转到对应行。以前我习惯用 Ctrl+Shift+F 全局搜TODO，结果一团糟。搜索框会同时搜到 README 里的优化列表、日志字符串里的"TODO: 处理超时"、依赖包源码里的注释，甚至有同事写的“这不是 TODO”。每次搜完还要人工过滤十几条无关结果，体验极差。Todo Tree 把“搜索注释”变成了“浏览清单”，这一步很关键：所有被标记的待办事项被提升到了编辑器的主界面，而不是隐藏在文本搜索的临时结果里。1.3 最值得使用 Todo Tree 的场景装了插件不等于一定要用，我见过不少人装完一周就卸载，原因是小项目里总共没几个 TODO，手动翻两下就找到了。所以先想清楚自己的场景：多分支并行开发的时候最值得装。你在 feature 分支留下一堆临时方案，切回主分支修 bug，等再切回来，那些 TODO 如果没有清单，几乎必然被遗忘。Todo Tree 能跨分支保留你的待办视图，只要工作区打开的是同一项目，清单永远在。长期维护的老项目也值得装。老代码里沉淀了大量历史注释，有些是很重要的已知风险，有些是过时信息。用 Todo Tree 把它们全部列出来，配合 FIXME 和 XXX 的语义，能快速筛出真正需要投入精力的风险点，而不是靠翻提交历史猜。团队协作场景里，如果能约定统一的注释格式，Todo Tree 的价值会进一步放大。后面第 3 节我会专门讲团队注释规范怎么写，这里先不展开。2. 装好并配置 Todo Tree，让扫描符合你的节奏2.1 两种安装方式，2 分钟内跑起来安装没什么难度。打开 VSCode 左侧扩展面板，输入Todo Tree，找到对应的插件点安装就行。装完之后左侧活动栏会多出一个图标，点击可以在侧边栏看到扫描结果。如果你习惯用命令行管理扩展，也可以直接执行：code --install-extension Gruntfuggly.todo-tree这个命令的具体写法可能随版本略有变化，但思路就一个：把扩展装好，重启窗口让插件注册。装完之后默认情况下它就会自动扫描当前工作区，不需要任何额外配置。很多第一次用的人会问“为什么我装完没反应”，大概率是没打开文件夹，只是打开了单个文件；Todo Tree 是按工作区扫描的，最好先打开项目根目录。2.2 settings.json 里最值得动的 5 个配置项Todo Tree 的默认配置能直接用，但想获得好的体验，还是得改几个地方。我建议打开设置界面搜索todo-tree，或者直接编辑settings.json，把下面这些核心配置加上：{ "todo-tree.general.tags": [ "TODO", "FIXME", "XXX", "HACK" ], "todo-tree.regex.regex": "//\\s*(TODO|FIXME|XXX|HACK)", "todo-tree.filter.excludeGlobs": [ "**/node_modules/**", "**/dist/**", "**/coverage/**", "**/build/**" ], "todo-tree.tree.showCountsInTree": true, "todo-tree.highlights.enabled": true }第一个todo-tree.general.tags决定插件识别哪些标记。默认只有 TODO、FIXME、XXX，如果你团队里还常用 HACK（临时方案）、BUG（已知问题）、NOTE（重要注意），都可以加进去。这里要注意：标记最好统一大写，因为预设的颜色和图标通常按大写标记分配，混用大小写会导致同一语义出现两套样式。第二个正则配置决定了“什么样的一行会被收进清单”。我给的写法是匹配//注释并紧跟 TODO 或 FIXME 等标记，前面的\\s*表示允许注释符号和标记之间有一个或多个空格。第三个todo-tree.filter.excludeGlobs是性能关键。如果不排除node_modules和构建产物目录，插件每次扫描都要遍历成千上万个依赖文件，侧边栏会卡顿，内存占用也会上涨。保存后观察一下，扫描速度通常会有感知级别的提升。第四个showCountsInTree会在树节点后面显示该文件或文件夹下命中的标记数量，比如src/App.tsx (3)，方便你快速判断哪个文件堆积的待办最多。最后一个highlights.enabled控制是否在代码编辑器里高亮命中行。如果关闭，你就只能看到侧边栏清单，代码里不会有彩色高亮。我个人建议保持开启，因为高亮本身就是一种视觉提醒。2.3 大型仓库的扫描性能优化中大型项目里，除了排除目录，还有一个容易被忽略的参数：todo-tree.filter.includeGlobs。它的含义是“只扫描哪些目录”，和excludeGlobs正好互补。比如说一个前后端仓库，你短期只关心前端代码，可以配置只扫src/**，这样 Todo Tree 完全不会碰后端目录，性能会再上一个台阶。但这里有个取舍：如果你经常要全局搜索历史 TODO，include 范围太窄可能漏掉其他模块的遗留任务。我通常的配置是只做 exclude，不做 include，因为 include 的误伤面比较大。还有一个小细节：刚写完一条 TODO 注释时，插件可能不会立即高亮，需要等几百毫秒的延迟，这是todo-tree.highlights.highlightDelay控制的。VSCode 本身就是异步架构，插件如果每次都实时全量重扫，编辑时容易卡。默认值 100 毫秒左右已经够用，不需要去动它。工具是死的，关键是让它匹配你的工作流。3. 实操：TODO、FIXME、XXX 注释怎么写才规范3.1 一段典型代码，教你三种标记的角色分配光知道三个单词的含义，写起来还是很容易走样。我放一个实际开发里常见的例子：public class OrderService { // TODO: 这里后续要接库存系统，先返回固定结果 public int queryStock(String skuId) { return 100; } // FIXME: 并发下库存扣减存在超卖风险，需要加分布式锁 public boolean deductStock(String skuId, int count) { return true; } // XXX: 这段临时逻辑千万别动，动了会影响双十一活动页 public List<String> buildPageData() { // 临时写死 return List.of("item1", "item2"); } }这三段注释分别对应了三种典型场景。TODO描述的是“未来要做的事”，它本身不影响当前代码运行，但需要明确告诉别人“接什么、为什么现在不接”。只说“要接库存系统”不够好，更好的写法是把“先返回固定结果”这个现状也写出来，接手的人才知道这不是漏掉了，而是刻意先简化。FIXME必须带上“风险后果”。比如“并发下库存扣减存在超卖风险”，这句话信息量很大——它告诉了后来者这是个临界条件问题，也暗示当前实现不完整，需要在生产环境处理前优先修复。如果只写 “FIXME: 优化库存”，很多人不知道这事到底有多急。XXX最常见的误用是被当成 TODO 用了。实际上 XXX 最适合标注“反常规但当下不得不这么写”的代码。我给buildPageData()加的注释，包含了“临时”“别动”“影响活动页”三层信息。任何人看到 XXX，又看到理由，才敢判断是继续忍着还是找产品重新商量方案。3.2 加责任人、时间戳和编号，让待办可追溯让注释规范真正落地的关键，是给标记加上“元信息”，也就是责任人、日期和关联编号。这样做的好处是：Todo Tree 的树节点里直接就能看到一段完整上下文，不需要跳转到代码再猜是谁写的。我推荐在团队里推行这样的格式：// TODO(张三): 2025-01-20 完成订单导出功能，排期见 PRD-023 // FIXME: 2025-01-20 登录态偶现丢失，现场版本为 v2.1.3，见 issue #8812 // XXX: 2025-01-20 生产环境临时加的白名单逻辑，需在 2025-02-01 前移除这里的要点有两条。第一，责任人和日期不要写在一堆零碎说明里，最好在标记后用括号或冒号开头单独列出。比如TODO(张三):，这样扫描结果扫一眼就能知道“谁的活还没干”。日期信息也很关键，因为待办事项有时效性，没有日期的 FIXME 放三个月后，谁也说不清是不是已经解决、只是注释忘了删。第二，能关联编号就关联编号。项目管理系统里的任务号、代码仓库里的 issue 号都行。只写一句“修复登录态丢失”，三个月后回来看，还得重新排查一遍；如果写issue #8812，直接跳转上下文，省掉大量沟通成本。我在团队里反复强调这一点，因为注释本质上是一种异步沟通，编号就是沟通的索引。3.3 我推荐的注释书写格式如果你不想搞太复杂，可以先从一套最简格式开始。我自己的惯用格式是“标记 + 冒号 + 一句话说明”，例如：// TODO: 接入消息中心，当前逻辑只在本服务内模拟 // FIXME: 排序在数据量超过 5000 条时为 O(n²)，现网数据已触发告警 // XXX: 这里依赖外部接口的返回顺序，接口方已给出废弃计划写注释时别过度修饰。好注释的核心是“能让人快速继续工作”，不需要把实现细节全写进去。比如 “FIXME: 并发下库存扣减存在超卖风险，需要加分布式锁” 已经足够，不用再解释分布式锁的原理——那是面试题，不是注释。有一个几乎人人都踩过的坑：把注释标记写成了小写，比如todo: 优化这里。VSCode 默认是大小写敏感的，todo和TODO是两个完全不同的词，Todo Tree 默认也只匹配大写。虽然可以在正则里设置caseSensitive: false，但我不建议这么干，因为统一大写本身就是团队规范的一部分。再补一个容易忽略的细节：要在行首放标记。someMethod(); // TODO: 优化这种行尾注释，Todo Tree 默认也能识别，但在正则配置里如果只写了//\\s*TODO，要求 TODO 必须紧跟//注释符号之后，行尾注释的识别就可能出问题。最稳定的做法是让标记出现在注释内容开头，比如独立一行写注释。4. 自制自己的 TODO 图标样式，不再千篇一律4.1 图标配置底层逻辑：Codicons 与高亮属性标题里最强需求的部分，也就是“自制自己的 TODO 图标样式”，其实做起来没有想象中复杂。Todo Tree 的图标体系建立在 VSCode 自带的 Codicons 图标库之上，不需要你自己准备图片文件，只要在配置里填写图标的名称即可。Codicons 是 VSCode 界面那些内置图标，比如设置齿轮、搜索放大镜、对勾圆形、警告三角等。在customHighlight配置项里，每种标记都可以设置一套独立样式。最常用的属性有：icon：图标名称，比如check-circle、error、warningiconColor：图标颜色，常用十六进制色值foreground：文字颜色background：文字背景高亮色rulerLane：代码右侧标尺上的位置，可选 left、rightgutterIcon：是否在行号槽显示图标这里有一个容易踩的坑：图标名称拼错时，插件不会立刻报错，只是图标显示不出来。下图标的名称来自 Codicons 内置集合，比如check-circle、error、warning、flame、bell、bookmark、lightbulb、package、zap等等。你可以在 VSCode 的图标预览面板里搜索确认名字，或者直接看官方文档的 Codicons 列表。配色上需要注意一个底层逻辑：VSCode 主题本身会定义某些标记的默认颜色，你自定义的foreground和background是在主题之上叠加的。如果配置后颜色没生效，先检查是否有工作区级别的设置覆盖了用户设置；其次检查颜色值是否带了透明通道，比如#16C60C22最后两位是透明度，写成22表示约 13% 的透明度，背景会非常淡。4.2 一套完整的自定义图标配置示例我给你一套我自己在用的配置，可以作为起点直接复制："todo-tree.highlights.customHighlight": { "TODO": { "icon": "check-circle", "iconColor": "#28C840", "foreground": "#28C840", "background": "#28C84022", "rulerLane": "left", "gutterIcon": true }, "FIXME": { "icon": "error", "iconColor": "#F14C4C", "foreground": "#F14C4C", "background": "#F14C4C22", "rulerLane": "left", "gutterIcon": true }, "XXX": { "icon": "warning", "iconColor": "#CC7832", "foreground": "#CC7832", "background": "#CC783222", "rulerLane": "left", "gutterIcon": true } }逐个解释一下。TODO 我用了check-circle圆形的对勾图标，颜色是绿色，代表“这件事还没做、但方向是正向的待办”。这里有个小设计：TODO 并不是坏事，它只是排期待完成，所以用绿色不会让人紧张，也符合“任务清单”的直觉。FIXME 用了error红色图标，一眼看上去就是错的。红色在 UI 里天然代表危险，配合#F14C4C的亮红，能有效提高修复事项的警觉度。我的建议是 FIXME 的颜色饱和度一定要高，否则它和 TODO 在目录树里会显得差不多，容易错过。XXX 用了warning橙色三角，代表“危险但暂时没爆”。为什么不用红色？因为如果 XXX 也用红色，会和 FIXME 的优先级混淆。我的习惯是：“红”只留给 FIXME，橙色留给 XXX，绿色留给 TODO，这样三类标记在视觉上天然分出了层级。background里的22是给背景加一点透明度的写法。如果颜色显示不明显，可以把透明度数值调高，比如40表示约 25% 的透明度，但太深会影响代码阅读，建议控制在22到40之间。还有一个小建议：如果你喜欢在行号槽（编辑器左侧装订线）显示图标，记得先确保todo-tree.highlights.defaultHighlight里的gutterIcon为true。否则单个自定义项里的gutterIcon可能被默认配置覆盖而看不到图标。4.3 分组和排序：把 FIXME 提到 TODO 前面图标样式解决的是“识别速度”问题，而分组排序解决的是“优先级顺序”问题。在 Todo Tree 中，可以对标记做分组，比如让 FIXME 和 XXX 归到“紧急”组，TODO 归到“日常”组，目录树就会按组展示，紧急事项自动排在前面。可以参考这样的配置："todo-tree.general.tagGroups": { "紧急": [ "FIXME", "XXX" ], "日常": [ "TODO" ] }配置完之后，侧边栏树会多出“紧急”“日常”两个父节点，FIXME 和 XXX 被收进“紧急”分支。这样打开 Todo Tree 的第一眼，看到的不是平铺的所有标记，而是先看到风险最高的部分。我个人还会给每个标记配置一个人单独的图标颜色偏好。比如前端项目里我习惯把 HACK 标记成紫色，因为 HACK 通常意味着“不优雅但能用”，紫色正好是种略带无奈的信号色，看到紫色就知道这段代码将来需要重构。如果你不止一个项目，不同项目可能想用不同图标风格，可以把配置放到工作区settings.json里而不是用户级设置。这两种配置的优先级不同，用户级是全局，工作区级只对当前项目生效。我的经验是：全局用默认的一套保守配色，重要项目的工作区里再定制一套更激进醒目的样式。5. 常见问题与排查技巧实录5.1 5 个高频问题速查表不管是新手还是老手，装完插件后总会遇到几个问题。我把最常见的 5 个整理成一张表，方便你对照排查：现象可能原因解决办法新写的 TODO 不出现文件没保存，或正则没匹配到先保存文件；检查todo-tree.regex.regex是否包含了当前注释格式扫描整个项目特别慢node_modules、构建产物没有被排除在todo-tree.filter.excludeGlobs中加入**/node_modules/**、**/dist/**自定义图标不显示icon 名称拼写有误，或gutterIcon没开启核对 Codicons 名称；检查todo-tree.highlights.defaultHighlight.gutterIcon颜色和设置不一致主题覆盖了自定义颜色，或颜色带透明通道把透明度调低；确认优先级是用户级还是工作区级某些文件里的标记扫不到该文件被 include/exclude 规则排除检查todo-tree.filter.includeGlobs和excludeGlobs的配置范围这 5 个问题是我见过最集中的情况。前四个都属于配置层面，第五个则和你的工作目录结构强相关。如果遇到排除目录里确实有标记需要跟踪，可以单独加入 include 规则，比如includeGlobs里写上**/src/**/legacy/**，只补回需要的目录。5.2 降低误匹配率的小技巧Todo Tree 默认的正则比较宽，实际使用中会有不少误匹配。常见误报来源有三种：日志字符串里包含TODO、Markdown 文档里用TODO做列表、代码注释里讨论 TODO 本身。比如console.log("TODO: 任务已启动")这种行，就会被插件当成一个待办。降低误匹配最直接的手段是收紧正则在注释中的位置。我常用的写法是只匹配以//开头的行："todo-tree.regex.regex": "^\\s*//\\s*(TODO|FIXME|XXX|HACK)"这个正则要求标记出现在行首，前面只能有空格，然后必须是//注释。相比.*TODO这种写法，它能排除大量日志内容和字符串里的误报。代价是行尾注释（比如someFunction(); // TODO: 优化）不再被识别。两者权衡，我宁愿牺牲少数行尾注释，因为误报对清单的污染更让人头疼。如果你用的语言是 Python、Ruby 这类#注释为主，正则就要对应调整，比如："todo-tree.regex.regex": "^\\s*#\\s*(TODO|FIXME|XXX)"还有一个特别容易忽略的点：块注释/* TODO */里的标记，默认正则也可能扫不到。如果项目里大量使用块注释，可以专门加一条正则，或者干脆在团队规范里约定“待办一律写行注释”。我倾向于后者，因为行注释对 Todo Tree 更友好，也更容易在 Code Review 时被看到。5.3 团队规范落地，比插件配置更难配置部分聊到这里，其实真正想多说两句的是团队落地。插件配置再花哨，如果团队里每个人都按自己的心情写注释，Todo Tree 的清单最终还是会变成一团乱麻。我在带项目的时候做过三件事。第一件是把三格注释规范写进项目 README 的“开发约定”一节，明确 TODO 该写什么、FIXME 必须带上风险描述、XXX 必须有保护期限。第二件是在 Code Review 时把 Todo Tree 侧边栏截图贴在评审记录里，每周扫一眼新增的待办数量，超过一周没处理的 FIXME 必须转成真正的 issue。第三件是避免把注释当成需求池，任何计划中的功能如果排期超过两个迭代，都应该进入项目管理工具，而不是留在代码里发霉。工具本身不产生纪律，但好工具能把纪律可视化。这句话是我折腾完 Todo Tree 后最深的体会。结尾我在实际使用中比较深的体会是，Todo Tree 能救的从来不是“写注释”这件事，而是“找注释”这件事。插件只负责把散落的 TODO / FIXME / XXX 汇总成清单，真正让清单发挥作用的，是你给标记定义完好的语义、可追溯的负责人和明确的截止时间。前期花十分钟把图标和规范配好，后面省下来的是每天翻文件的半小时。最后再分享一个小技巧：如果你带的是新手团队，把注释规范写进项目 README，并在 Todo Tree 的设置里把 FIXME、XXX 的图标颜色调成醒目的红橙色，新手同学看到侧边栏里的高亮预警，通常就不敢随手把一段危代码留到线上。工具本身不产生纪律，但好工具能把纪律可视化，这一点我觉得比任何规范文档都更有用。
很多开发者在代码里都有这种经历：遇到临时问题，随手敲一行// TODO: 这里待优化，或者标注// FIXME: 逻辑有坑，写完继续往下赶进度。两周以后这个文件被改了七八次，回头想找那行 TODO，全靠翻历史记录，运气好十分钟，运气差一个下午就没了。VSCode Todo Tree 插件解决的正是这个痛点，它能把代码里所有注释标记统一扫进一个树状列表，打开编辑器就能看到还有哪些遗留任务没有处理。这一篇我打算一次讲透三件事：Todo Tree 怎么装怎么配，TODO / FIXME / XXX 这三种标记到底怎么用才是正确的，以及怎么在 VSCode 里做一套属于自己的 TODO 图标样式。内容不算短，但从基础原理到实操配置都会覆盖，适合刚接触插件的入门用户，也适合想规范团队注释习惯的开发者参考。1. 为什么要在代码里写标记，又为什么要用 Todo Tree1.1 三种标记的职责划分经常有人问，TODO、FIXME、XXX 到底有什么区别？在 VSCode 的默认认知里，TODO 就是待办事项，FIXME 是这里有 bug 需要修，XXX 被大部分团队当作“这里很危险，动之前要想想”。我个人的理解更简单直接：TODO 是“未来要做的功能”，FIXME 是“已知要修的缺陷”，XXX 是“请务必注意、容易踩坑的地方”。这个区分不是拍脑袋定的，它直接影响代码的排查路径。假如一个接口在临界条件下会返回空对象，你只写一行// TODO: 判断空值，三个月后接手的人会把它当成普通功能优化，排期排到天荒地老。但如果你写成// FIXME: 这里未判空会导致崩溃，任何人看到的第一反应就是“需要立刻处理”。语义化的标记比单纯的中文注释靠谱，因为可被工具识别，也能统一所有人的心智模型。我自己在实际项目里遇到过更典型的例子：某段临时逻辑写死了一个阈值，上线后业务量翻倍，系统开始在高峰期超时。代码里当时写的是// 注意：这里写死不能改，结果新来的同事真的没敢改，直到问题爆发。后来我复盘才意识到，如果用XXX标记并附带保护期限，任何人在 Todo Tree 里扫一眼就会知道“这个临时方案已经到期了，必须处理”。三种标记的分工可以简单归纳成一张表：标记语义典型场景紧急程度TODO待完成功能后续要接接口、优化性能、补充分支逻辑低FIXME已知缺陷崩溃、超卖、内存泄漏、兼容性问题高XXX危险代码临时方案、写法反常、容易误改极高1.2 从“搜代码”到“看清单”的转变Todo Tree 干的事情其实很朴素，本质就是“正则匹配 + 树形展示”的扫描器。它启动后会遍历你当前打开的工作区文件，用你配置的正则表达式匹配代码注释，命中 TODO / FIXME / XXX 就把那一行收进侧边栏树节点。编辑器保存文件和变更文件时，插件会自动重新扫描，所以写一行新注释保存后立刻就能在树里看到。这里有个容易被忽略的点：Todo Tree 不是搜索引擎。它面向的是“已知我要找什么”的人。你不需要记得 TODO 在哪个文件哪个函数，只要打开侧边栏，所有待办任务按文件目录层级铺开，节点上还能显示数量统计，双击直接跳转到对应行。以前我习惯用 Ctrl+Shift+F 全局搜TODO，结果一团糟。搜索框会同时搜到 README 里的优化列表、日志字符串里的"TODO: 处理超时"、依赖包源码里的注释，甚至有同事写的“这不是 TODO”。每次搜完还要人工过滤十几条无关结果，体验极差。Todo Tree 把“搜索注释”变成了“浏览清单”，这一步很关键：所有被标记的待办事项被提升到了编辑器的主界面，而不是隐藏在文本搜索的临时结果里。1.3 最值得使用 Todo Tree 的场景装了插件不等于一定要用，我见过不少人装完一周就卸载，原因是小项目里总共没几个 TODO，手动翻两下就找到了。所以先想清楚自己的场景：多分支并行开发的时候最值得装。你在 feature 分支留下一堆临时方案，切回主分支修 bug，等再切回来，那些 TODO 如果没有清单，几乎必然被遗忘。Todo Tree 能跨分支保留你的待办视图，只要工作区打开的是同一项目，清单永远在。长期维护的老项目也值得装。老代码里沉淀了大量历史注释，有些是很重要的已知风险，有些是过时信息。用 Todo Tree 把它们全部列出来，配合 FIXME 和 XXX 的语义，能快速筛出真正需要投入精力的风险点，而不是靠翻提交历史猜。团队协作场景里，如果能约定统一的注释格式，Todo Tree 的价值会进一步放大。后面第 3 节我会专门讲团队注释规范怎么写，这里先不展开。2. 装好并配置 Todo Tree，让扫描符合你的节奏2.1 两种安装方式，2 分钟内跑起来安装没什么难度。打开 VSCode 左侧扩展面板，输入Todo Tree，找到对应的插件点安装就行。装完之后左侧活动栏会多出一个图标，点击可以在侧边栏看到扫描结果。如果你习惯用命令行管理扩展，也可以直接执行：code --install-extension Gruntfuggly.todo-tree这个命令的具体写法可能随版本略有变化，但思路就一个：把扩展装好，重启窗口让插件注册。装完之后默认情况下它就会自动扫描当前工作区，不需要任何额外配置。很多第一次用的人会问“为什么我装完没反应”，大概率是没打开文件夹，只是打开了单个文件；Todo Tree 是按工作区扫描的，最好先打开项目根目录。2.2 settings.json 里最值得动的 5 个配置项Todo Tree 的默认配置能直接用，但想获得好的体验，还是得改几个地方。我建议打开设置界面搜索todo-tree，或者直接编辑settings.json，把下面这些核心配置加上：{ "todo-tree.general.tags": [ "TODO", "FIXME", "XXX", "HACK" ], "todo-tree.regex.regex": "//\\s*(TODO|FIXME|XXX|HACK)", "todo-tree.filter.excludeGlobs": [ "**/node_modules/**", "**/dist/**", "**/coverage/**", "**/build/**" ], "todo-tree.tree.showCountsInTree": true, "todo-tree.highlights.enabled": true }第一个todo-tree.general.tags决定插件识别哪些标记。默认只有 TODO、FIXME、XXX，如果你团队里还常用 HACK（临时方案）、BUG（已知问题）、NOTE（重要注意），都可以加进去。这里要注意：标记最好统一大写，因为预设的颜色和图标通常按大写标记分配，混用大小写会导致同一语义出现两套样式。第二个正则配置决定了“什么样的一行会被收进清单”。我给的写法是匹配//注释并紧跟 TODO 或 FIXME 等标记，前面的\\s*表示允许注释符号和标记之间有一个或多个空格。第三个todo-tree.filter.excludeGlobs是性能关键。如果不排除node_modules和构建产物目录，插件每次扫描都要遍历成千上万个依赖文件，侧边栏会卡顿，内存占用也会上涨。保存后观察一下，扫描速度通常会有感知级别的提升。第四个showCountsInTree会在树节点后面显示该文件或文件夹下命中的标记数量，比如src/App.tsx (3)，方便你快速判断哪个文件堆积的待办最多。最后一个highlights.enabled控制是否在代码编辑器里高亮命中行。如果关闭，你就只能看到侧边栏清单，代码里不会有彩色高亮。我个人建议保持开启，因为高亮本身就是一种视觉提醒。2.3 大型仓库的扫描性能优化中大型项目里，除了排除目录，还有一个容易被忽略的参数：todo-tree.filter.includeGlobs。它的含义是“只扫描哪些目录”，和excludeGlobs正好互补。比如说一个前后端仓库，你短期只关心前端代码，可以配置只扫src/**，这样 Todo Tree 完全不会碰后端目录，性能会再上一个台阶。但这里有个取舍：如果你经常要全局搜索历史 TODO，include 范围太窄可能漏掉其他模块的遗留任务。我通常的配置是只做 exclude，不做 include，因为 include 的误伤面比较大。还有一个小细节：刚写完一条 TODO 注释时，插件可能不会立即高亮，需要等几百毫秒的延迟，这是todo-tree.highlights.highlightDelay控制的。VSCode 本身就是异步架构，插件如果每次都实时全量重扫，编辑时容易卡。默认值 100 毫秒左右已经够用，不需要去动它。工具是死的，关键是让它匹配你的工作流。3. 实操：TODO、FIXME、XXX 注释怎么写才规范3.1 一段典型代码，教你三种标记的角色分配光知道三个单词的含义，写起来还是很容易走样。我放一个实际开发里常见的例子：public class OrderService { // TODO: 这里后续要接库存系统，先返回固定结果 public int queryStock(String skuId) { return 100; } // FIXME: 并发下库存扣减存在超卖风险，需要加分布式锁 public boolean deductStock(String skuId, int count) { return true; } // XXX: 这段临时逻辑千万别动，动了会影响双十一活动页 public List<String> buildPageData() { // 临时写死 return List.of("item1", "item2"); } }这三段注释分别对应了三种典型场景。TODO描述的是“未来要做的事”，它本身不影响当前代码运行，但需要明确告诉别人“接什么、为什么现在不接”。只说“要接库存系统”不够好，更好的写法是把“先返回固定结果”这个现状也写出来，接手的人才知道这不是漏掉了，而是刻意先简化。FIXME必须带上“风险后果”。比如“并发下库存扣减存在超卖风险”，这句话信息量很大——它告诉了后来者这是个临界条件问题，也暗示当前实现不完整，需要在生产环境处理前优先修复。如果只写 “FIXME: 优化库存”，很多人不知道这事到底有多急。XXX最常见的误用是被当成 TODO 用了。实际上 XXX 最适合标注“反常规但当下不得不这么写”的代码。我给buildPageData()加的注释，包含了“临时”“别动”“影响活动页”三层信息。任何人看到 XXX，又看到理由，才敢判断是继续忍着还是找产品重新商量方案。3.2 加责任人、时间戳和编号，让待办可追溯让注释规范真正落地的关键，是给标记加上“元信息”，也就是责任人、日期和关联编号。这样做的好处是：Todo Tree 的树节点里直接就能看到一段完整上下文，不需要跳转到代码再猜是谁写的。我推荐在团队里推行这样的格式：// TODO(张三): 2025-01-20 完成订单导出功能，排期见 PRD-023 // FIXME: 2025-01-20 登录态偶现丢失，现场版本为 v2.1.3，见 issue #8812 // XXX: 2025-01-20 生产环境临时加的白名单逻辑，需在 2025-02-01 前移除这里的要点有两条。第一，责任人和日期不要写在一堆零碎说明里，最好在标记后用括号或冒号开头单独列出。比如TODO(张三):，这样扫描结果扫一眼就能知道“谁的活还没干”。日期信息也很关键，因为待办事项有时效性，没有日期的 FIXME 放三个月后，谁也说不清是不是已经解决、只是注释忘了删。第二，能关联编号就关联编号。项目管理系统里的任务号、代码仓库里的 issue 号都行。只写一句“修复登录态丢失”，三个月后回来看，还得重新排查一遍；如果写issue #8812，直接跳转上下文，省掉大量沟通成本。我在团队里反复强调这一点，因为注释本质上是一种异步沟通，编号就是沟通的索引。3.3 我推荐的注释书写格式如果你不想搞太复杂，可以先从一套最简格式开始。我自己的惯用格式是“标记 + 冒号 + 一句话说明”，例如：// TODO: 接入消息中心，当前逻辑只在本服务内模拟 // FIXME: 排序在数据量超过 5000 条时为 O(n²)，现网数据已触发告警 // XXX: 这里依赖外部接口的返回顺序，接口方已给出废弃计划写注释时别过度修饰。好注释的核心是“能让人快速继续工作”，不需要把实现细节全写进去。比如 “FIXME: 并发下库存扣减存在超卖风险，需要加分布式锁” 已经足够，不用再解释分布式锁的原理——那是面试题，不是注释。有一个几乎人人都踩过的坑：把注释标记写成了小写，比如todo: 优化这里。VSCode 默认是大小写敏感的，todo和TODO是两个完全不同的词，Todo Tree 默认也只匹配大写。虽然可以在正则里设置caseSensitive: false，但我不建议这么干，因为统一大写本身就是团队规范的一部分。再补一个容易忽略的细节：要在行首放标记。someMethod(); // TODO: 优化这种行尾注释，Todo Tree 默认也能识别，但在正则配置里如果只写了//\\s*TODO，要求 TODO 必须紧跟//注释符号之后，行尾注释的识别就可能出问题。最稳定的做法是让标记出现在注释内容开头，比如独立一行写注释。4. 自制自己的 TODO 图标样式，不再千篇一律4.1 图标配置底层逻辑：Codicons 与高亮属性标题里最强需求的部分，也就是“自制自己的 TODO 图标样式”，其实做起来没有想象中复杂。Todo Tree 的图标体系建立在 VSCode 自带的 Codicons 图标库之上，不需要你自己准备图片文件，只要在配置里填写图标的名称即可。Codicons 是 VSCode 界面那些内置图标，比如设置齿轮、搜索放大镜、对勾圆形、警告三角等。在customHighlight配置项里，每种标记都可以设置一套独立样式。最常用的属性有：icon：图标名称，比如check-circle、error、warningiconColor：图标颜色，常用十六进制色值foreground：文字颜色background：文字背景高亮色rulerLane：代码右侧标尺上的位置，可选 left、rightgutterIcon：是否在行号槽显示图标这里有一个容易踩的坑：图标名称拼错时，插件不会立刻报错，只是图标显示不出来。下图标的名称来自 Codicons 内置集合，比如check-circle、error、warning、flame、bell、bookmark、lightbulb、package、zap等等。你可以在 VSCode 的图标预览面板里搜索确认名字，或者直接看官方文档的 Codicons 列表。配色上需要注意一个底层逻辑：VSCode 主题本身会定义某些标记的默认颜色，你自定义的foreground和background是在主题之上叠加的。如果配置后颜色没生效，先检查是否有工作区级别的设置覆盖了用户设置；其次检查颜色值是否带了透明通道，比如#16C60C22最后两位是透明度，写成22表示约 13% 的透明度，背景会非常淡。4.2 一套完整的自定义图标配置示例我给你一套我自己在用的配置，可以作为起点直接复制："todo-tree.highlights.customHighlight": { "TODO": { "icon": "check-circle", "iconColor": "#28C840", "foreground": "#28C840", "background": "#28C84022", "rulerLane": "left", "gutterIcon": true }, "FIXME": { "icon": "error", "iconColor": "#F14C4C", "foreground": "#F14C4C", "background": "#F14C4C22", "rulerLane": "left", "gutterIcon": true }, "XXX": { "icon": "warning", "iconColor": "#CC7832", "foreground": "#CC7832", "background": "#CC783222", "rulerLane": "left", "gutterIcon": true } }逐个解释一下。TODO 我用了check-circle圆形的对勾图标，颜色是绿色，代表“这件事还没做、但方向是正向的待办”。这里有个小设计：TODO 并不是坏事，它只是排期待完成，所以用绿色不会让人紧张，也符合“任务清单”的直觉。FIXME 用了error红色图标，一眼看上去就是错的。红色在 UI 里天然代表危险，配合#F14C4C的亮红，能有效提高修复事项的警觉度。我的建议是 FIXME 的颜色饱和度一定要高，否则它和 TODO 在目录树里会显得差不多，容易错过。XXX 用了warning橙色三角，代表“危险但暂时没爆”。为什么不用红色？因为如果 XXX 也用红色，会和 FIXME 的优先级混淆。我的习惯是：“红”只留给 FIXME，橙色留给 XXX，绿色留给 TODO，这样三类标记在视觉上天然分出了层级。background里的22是给背景加一点透明度的写法。如果颜色显示不明显，可以把透明度数值调高，比如40表示约 25% 的透明度，但太深会影响代码阅读，建议控制在22到40之间。还有一个小建议：如果你喜欢在行号槽（编辑器左侧装订线）显示图标，记得先确保todo-tree.highlights.defaultHighlight里的gutterIcon为true。否则单个自定义项里的gutterIcon可能被默认配置覆盖而看不到图标。4.3 分组和排序：把 FIXME 提到 TODO 前面图标样式解决的是“识别速度”问题，而分组排序解决的是“优先级顺序”问题。在 Todo Tree 中，可以对标记做分组，比如让 FIXME 和 XXX 归到“紧急”组，TODO 归到“日常”组，目录树就会按组展示，紧急事项自动排在前面。可以参考这样的配置："todo-tree.general.tagGroups": { "紧急": [ "FIXME", "XXX" ], "日常": [ "TODO" ] }配置完之后，侧边栏树会多出“紧急”“日常”两个父节点，FIXME 和 XXX 被收进“紧急”分支。这样打开 Todo Tree 的第一眼，看到的不是平铺的所有标记，而是先看到风险最高的部分。我个人还会给每个标记配置一个人单独的图标颜色偏好。比如前端项目里我习惯把 HACK 标记成紫色，因为 HACK 通常意味着“不优雅但能用”，紫色正好是种略带无奈的信号色，看到紫色就知道这段代码将来需要重构。如果你不止一个项目，不同项目可能想用不同图标风格，可以把配置放到工作区settings.json里而不是用户级设置。这两种配置的优先级不同，用户级是全局，工作区级只对当前项目生效。我的经验是：全局用默认的一套保守配色，重要项目的工作区里再定制一套更激进醒目的样式。5. 常见问题与排查技巧实录5.1 5 个高频问题速查表不管是新手还是老手，装完插件后总会遇到几个问题。我把最常见的 5 个整理成一张表，方便你对照排查：现象可能原因解决办法新写的 TODO 不出现文件没保存，或正则没匹配到先保存文件；检查todo-tree.regex.regex是否包含了当前注释格式扫描整个项目特别慢node_modules、构建产物没有被排除在todo-tree.filter.excludeGlobs中加入**/node_modules/**、**/dist/**自定义图标不显示icon 名称拼写有误，或gutterIcon没开启核对 Codicons 名称；检查todo-tree.highlights.defaultHighlight.gutterIcon颜色和设置不一致主题覆盖了自定义颜色，或颜色带透明通道把透明度调低；确认优先级是用户级还是工作区级某些文件里的标记扫不到该文件被 include/exclude 规则排除检查todo-tree.filter.includeGlobs和excludeGlobs的配置范围这 5 个问题是我见过最集中的情况。前四个都属于配置层面，第五个则和你的工作目录结构强相关。如果遇到排除目录里确实有标记需要跟踪，可以单独加入 include 规则，比如includeGlobs里写上**/src/**/legacy/**，只补回需要的目录。5.2 降低误匹配率的小技巧Todo Tree 默认的正则比较宽，实际使用中会有不少误匹配。常见误报来源有三种：日志字符串里包含TODO、Markdown 文档里用TODO做列表、代码注释里讨论 TODO 本身。比如console.log("TODO: 任务已启动")这种行，就会被插件当成一个待办。降低误匹配最直接的手段是收紧正则在注释中的位置。我常用的写法是只匹配以//开头的行："todo-tree.regex.regex": "^\\s*//\\s*(TODO|FIXME|XXX|HACK)"这个正则要求标记出现在行首，前面只能有空格，然后必须是//注释。相比.*TODO这种写法，它能排除大量日志内容和字符串里的误报。代价是行尾注释（比如someFunction(); // TODO: 优化）不再被识别。两者权衡，我宁愿牺牲少数行尾注释，因为误报对清单的污染更让人头疼。如果你用的语言是 Python、Ruby 这类#注释为主，正则就要对应调整，比如："todo-tree.regex.regex": "^\\s*#\\s*(TODO|FIXME|XXX)"还有一个特别容易忽略的点：块注释/* TODO */里的标记，默认正则也可能扫不到。如果项目里大量使用块注释，可以专门加一条正则，或者干脆在团队规范里约定“待办一律写行注释”。我倾向于后者，因为行注释对 Todo Tree 更友好，也更容易在 Code Review 时被看到。5.3 团队规范落地，比插件配置更难配置部分聊到这里，其实真正想多说两句的是团队落地。插件配置再花哨，如果团队里每个人都按自己的心情写注释，Todo Tree 的清单最终还是会变成一团乱麻。我在带项目的时候做过三件事。第一件是把三格注释规范写进项目 README 的“开发约定”一节，明确 TODO 该写什么、FIXME 必须带上风险描述、XXX 必须有保护期限。第二件是在 Code Review 时把 Todo Tree 侧边栏截图贴在评审记录里，每周扫一眼新增的待办数量，超过一周没处理的 FIXME 必须转成真正的 issue。第三件是避免把注释当成需求池，任何计划中的功能如果排期超过两个迭代，都应该进入项目管理工具，而不是留在代码里发霉。工具本身不产生纪律，但好工具能把纪律可视化。这句话是我折腾完 Todo Tree 后最深的体会。结尾我在实际使用中比较深的体会是，Todo Tree 能救的从来不是“写注释”这件事，而是“找注释”这件事。插件只负责把散落的 TODO / FIXME / XXX 汇总成清单，真正让清单发挥作用的，是你给标记定义完好的语义、可追溯的负责人和明确的截止时间。前期花十分钟把图标和规范配好，后面省下来的是每天翻文件的半小时。最后再分享一个小技巧：如果你带的是新手团队，把注释规范写进项目 README，并在 Todo Tree 的设置里把 FIXME、XXX 的图标颜色调成醒目的红橙色，新手同学看到侧边栏里的高亮预警，通常就不敢随手把一段危代码留到线上。工具本身不产生纪律，但好工具能把纪律可视化，这一点我觉得比任何规范文档都更有用。