很多开发者在代码里都有这种经历遇到临时问题随手敲一行// 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 在哪个文件哪个函数只要打开侧边栏所有待办任务按文件目录层级铺开节点上还能显示数量统计双击直接跳转到对应行。以前我习惯用 CtrlShiftF 全局搜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 完全不会碰后端目录性能会再上一个台阶。但这里有个取舍如果你经常要全局搜索历史 TODOinclude 范围太窄可能漏掉其他模块的遗留任务。我通常的配置是只做 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 ListString 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 的图标颜色调成醒目的红橙色新手同学看到侧边栏里的高亮预警通常就不敢随手把一段危代码留到线上。工具本身不产生纪律但好工具能把纪律可视化这一点我觉得比任何规范文档都更有用。