如果你写过一段时间代码大概率会有这样的经历在某处写了个// TODO: 这里要处理边界情况三个月后翻了七八个文件都找不到最后发现它藏在工具函数里旁边还长出了三四个新的FIXME。我自己之前维护一个中大型工程的时候这种感觉尤其强烈。后来我在 VS Code 里装了 Todo Tree 这个扩展散落在代码里的 TODO 类注释终于有了一个统一的“汇总视图”。说白了Todo Tree 就是一个能把代码注释中的TODO、FIXME、BUG等标记自动扫描出来并按照树形结构展示在侧边栏的 VS Code 插件。它解决的核心痛点就一句话让代码里的临时提醒不再因为散落各处而变成没人认领的坏账。这东西几乎适配所有用 VS Code 的开发者不管你是写前端、后端还是脚本语言装的成本极低但每天节省的找代码时间非常可观。1. 为什么你需要一个 Todo Tree散落注释背后的管理难题1.1 代码里的“便利贴墙”是怎么失控的很多团队其实都有一套“代码注释规范”比如要求开发者把临时计划写成// TODO把已知问题写成// FIXME。初衷很好但实际执行起来注释就会像工位旁的便利贴一样越贴越多越来越乱。你可能在某个函数里看到TODO: 优化性能又在某个配置文件里看到FIXME: 这个地址写死了但没人能快速统计出这个仓库里到底有多少个待办项更别说分清哪些重要、哪些已经过时。我在一个小项目里试过总共几千行代码手动用全局搜索搜TODO结果也就几十条勉强能扫一遍。可一旦项目上了规模或者从 monorepo 里拉出几个子项目一起开发文件数量上千语言类型混杂这时候再靠记忆或者全局搜索效率就非常低了。全局搜索固然能搜到所有TODO但它会把 node_modules、打包产物、日志文件里的无关内容全部带进来而且结果是一长串平铺的列表没有按照业务模块或者文件归属做归类看完反而更晕。更麻烦的是这类注释经常“沉淀”到没人负责的状态。一个人写的HACK注释另一个人看到后不敢动因为不知道当初为什么这么写也不知道改了对不对。时间一长注释就变成了“考古现场”。真正该做的不是禁止大家写注释而是给这些注释一个统一的管理入口。1.2 Todo Tree 的核心思路用“树”重新组织零散标记Todo Tree 这个扩展的原始名称就很有画面感它把代码里那些“待办事项”集中到一棵树里展示。它的工作方式大体分成三步扫描、识别、展示。扩展会按你配置的规则去扫描工作区里的文件找出匹配特定标签默认是TODO和FIXME的注释然后把结果按目录结构、文件归属或者标签分组显示在侧边栏的树视图里。这种设计的聪明之处在于它不只是把搜索到的结果列出来而是建立了一个“汇总、索引、跳转”三合一的入口。你在树视图里看到一个文件下有几个 TODO点一下就能跳到对应行不用自己记路径也不用在文件里翻来翻去。对于开发者来说这种低成本调用的方式很重要因为写临时注释本来就是顺手的事查看这些注释也应该顺手否则就不会有人愿意用了。另外一个很关键的细节是Todo Tree 天然支持对不同标签做区分。TODO和FIXME在语义上并不一样TODO 偏向计划开发的任务FIXME 则代表已知缺陷或待修复问题。如果都用同一种颜色、同一个列表展示重点很容易被稀释。Todo Tree 可以直接给不同标签分配不同配色紧急程度一目了然。1.3 跟其他方案对比搜索面板、书签、TODO 的取舍你可能会想VS Code 自带的全局搜索不也能搜TODO吗确实能但它只是检索文本不管语义。搜出来的结果里可能包含字符串文本、误报而且不能按模块做树状归类。搜索面板适合“一次性查找”不适合“持续跟踪”。还有人会提到书签功能VS Code 的“书签”扩展可以把指定位置存下来但这毕竟要手动添加而且书签主要用于临时定位不会自动感知代码里新写的 TODO 注释。跟 Todo Tree 思路更接近的是另一个扩展TODO它同样扫描 TODO 并展示侧边栏但在可配置性和树视图的细化程度上Todo Tree 更灵活。比如对正则的开放度、对不同文件过滤规则的支持、对标签分组展示的能力Todo Tree 明显更“能打”。我选 Todo Tree最看重的是它的“低心智负担”装完默认就能用配置项虽然多但大多数情况下只需要改 tags 和过滤规则两部分。相比其他方案它把“扫描-索引-跳转”闭环做得很顺滑而且没有强行把“任务管理”的概念塞进来它就是一个干净的注释索引器。2. 安装与上手5分钟把树视图跑起来2.1 安装方式安装 Todo Tree 有两种方式最常规的是打开 VS Code 的扩展市场搜索Todo Tree找到作者为 Gruntfuggly 的扩展直接安装。另一个方式是调出命令面板输入ext install Gruntfuggly.todo-tree回车安装。我个人更推荐后者因为扩展 ID 不会因为名称撞车而装错。安装完成之后侧边栏上会出现一个“TODO Tree”的视图容器图标点击就能打开树视图。如果你打开一个比较大的项目它会立刻开始扫描。扫描速度通常很快因为默认情况下它会跳过 node_modules、.git 这类目录除非你主动告诉它去扫描。2.2 基本操作流程打开树视图之后你会发现它按文件夹和文件的层级关系展示每个匹配项。比如src/utils/index.js下面挂着两个 TODO一个 FIXME每一行还可以展开显示具体注释内容。点击任意一条记录右侧编辑器会自动打开对应文件并定位到那一行。视图顶部有几个快捷按钮刷新按钮最重要。虽然扩展默认在文件保存时自动更新但某些版本或特殊场景下自动刷新可能不够及时手动刷新一下更稳妥。折叠按钮可以把所有树节点收起适合快速浏览整体分布。有些版本还提供文本过滤输入框可以在树内筛选出你关注的关键字这类细节在项目很大时非常有用。我第一次上手时只做了三件事删掉了视图里的“默认高亮全开”因为觉得太花把BUG和HACK加入 tags调整了刷新频率避免保存文件时频繁扫描打断思路。做完这些之后整个体验就顺了。2.3 第一次需要调的三处设置打开设置面板搜索todo-tree你会看到一大串配置项。新手不需要全部了解但下面三个建议先调好。第一todo-tree.general.tags。默认只有TODO和FIXME很多人写代码时还会用BUG、HACK、REVIEW、XXX这类标记。把它们加进列表Todo Tree 才会识别。比如todo-tree.general.tags: [TODO, FIXME, BUG, HACK, REVIEW, XXX]第二todo-tree.filtering.includeGlobs。如果你只想扫描特定类型的文件或者只想看某个目录用这个配置限定范围减少无关干扰。例如todo-tree.filtering.includeGlobs: [**/*.{js,ts,jsx,tsx,vue}]第三todo-tree.highlighting.enabled。默认高亮是开的所有匹配到的标签都会在编辑器里上色。如果觉得刺眼可以先关掉只保留侧边栏树视图。建议先用默认效果跑一天再决定怎么调整。3. 配置参数详解从默认值到自己掌控扫描规则3.1 标签tags与正则regex的关系Todo Tree 的匹配逻辑里tags 和正则是一体两面。tags 是你要匹配的关键词集合但代码里出现某个关键词并不一定就是注释。比如字符串里也可能会出现TODO这个词const text TODO: 明天开会这明明是一条聊天文本不是代码注释如果不加限制就会被误报。于是 Todo Tree 提供了todo-tree.general.regex这个配置。它允许你定义一个完整正则模板其中用占位符$TAGS代表 tags 的集合。官方文档给出的典型写法是匹配//、#、!--、;、*这类注释符号出现的行再跟着$TAGS。例如todo-tree.general.regex: (//|#|!--|;|\\*\\s|^\\s*-)\\s*($TAGS)这段正则可以覆盖很多主流语言的注释风格JavaScript 的//、Python 的#、HTML 的!--、Lisp 风格的分号、C 系文档注释里的*。如果项目全是 TypeScript 和 Rust你可以写得更精确只匹配//和///减少不必要的扫描开销。正则里还有一点要注意$TAGS之间的匹配默认是忽略了大小写还是严格区分取决于你的配置方式。如果你直接写死正则比如regex: //\\s*(TODO)那它就不会匹配todo。如果你用 tags 标签数组大小写敏感的开关由扩展内部逻辑决定具体可以通过实际测试确定。我的习惯是代码注释里统一用大写TODO/FIXME约定简单配置也简单。3.2 过滤规则哪些文件该扫哪些该忽略过滤配置是整个扩展里最需要花心思的部分因为它直接影响扫描准确度和性能。todo-tree.filtering.includeGlobs用来声明“只扫描哪些文件”。如果你的项目是一个前后端混合仓库前端只关心 src 下的js/ts文件后端关心py/go文件那就用 includeGlobs 把彼此的范围隔开。举个例子todo-tree.filtering.includeGlobs: [ src/**/*.ts, src/**/*.tsx, server/**/*.py ]这样扫出来的结果会比较干净不会把dist、build、coverage这些产物目录里的小写标注也扫进来。todo-tree.filtering.excludeGlobs则是反向排除适合在 includeGlobs 不够细分时做兜底。比如你确实想扫描整个仓库但排除掉third_party和mock目录todo-tree.filtering.excludeGlobs: [ **/node_modules/**, **/dist/**, **/build/**, **/third_party/** ]还有两个隐藏文件相关的开关todo-tree.filtering.excludeHidden和todo-tree.filtering.excludeGitIgnore。前者控制是否排除点开头文件比如.eslintrc.js后者会让扩展遵循.gitignore中的排除规则。这两个默认基本都是开着的能帮你过滤掉大量无关文件。我个人倾向于保持开启只有在想“故意找点历史遗留”的时候才会临时关掉比如排查某个被 .gitignore 忽略的配置文件里有没有 TODO。3.3 高亮与展示让紧急标记一眼可见树视图只是索引真正在你写代码时给你提醒的是高亮功能。todo-tree.highlighting.enabled控制总开关默认开启。开启后匹配到的标签和注释内容会在编辑器内上色。todo-tree.highlighting.useColoredBackground决定了是用背景色还是文字颜色来突出显示。我个人的习惯是开启背景色因为文字颜色容易被主题配色干扰背景色更醒目。todo-tree.highlighting.backgroundColor可以自定义成半透明色避免遮挡代码。此外还可以通过todo-tree.highlighting.opacity调透明度。更实用的是给不同标签分配不同颜色。假设项目里定了这样一套规则FIXME用红色背景表示必须尽快处理HACK用橙色TODO用蓝色REVIEW用绿色。代码扫一眼就知道当前区块有没有坑比逐个读注释快得多。配色虽然有个人倾向但团队合作时建议稍微统一一下否则互相看的代码“五颜六色”反而造成理解成本。3.4 团队级配置把 .vscode/settings.json 作为事实标准如果你是一个人在自己的机器上用 Todo Tree改设置只管自己爽。但如果要在团队里统一推广靠每个人手动改配置是不可靠的总有人漏装扩展或者用了不同版本导致行为不一致。更稳妥的做法是把 Todo Tree 的配置放在项目根目录的.vscode/settings.json里。只要团队成员打开这个仓库就会自动加载工作区配置。再加上.vscode/extensions.json写入推荐的扩展 ID其他人打开项目时VS Code 会提示安装 Todo Tree避免“你看到了 TODO 树我却看不到”的尴尬。下面是适合放到项目里的一份精简配置{ todo-tree.general.tags: [TODO, FIXME, BUG, HACK, REVIEW], todo-tree.general.regex: (//|#|!--|;|\\*\\s|^\\s*-)\\s*($TAGS), todo-tree.filtering.excludeGlobs: [**/node_modules/**, **/dist/**, **/build/**, **/coverage/**], todo-tree.highlighting.enabled: true, todo-tree.highlighting.useColoredBackground: true }这份配置只依赖比较稳定的核心字段。把它提交到仓库之前记得跟团队说明一下这不是强制大家写注释而是统一一下注释的“可见度”让大家写下的 TODO 能被更可靠地看到。4. 进阶玩法让 Todo Tree 融入代码管理与团队协作4.1 标记分级用不同标签表达不同紧急度Todo Tree 擅长识别标签但光识别还不够你得让标签本身具备语义。我建议把常见标签当成“级别”来用而不是随手乱标。TODO代表计划中的任务可能是下一阶段要做的优化、功能补齐不一定有明确的 deadlineFIXME代表已知问题比如逻辑 bug、数据异常优先级高于 TODOHACK代表临时绕过的方案这种往往带有“你知道这是脏代码但暂时没时间处理”的意味风险最高必须加注释说明为什么这么做REVIEW代表需要别人 review 的代码适合在写完后拉同事确认。XXX可以留给“这里有大坑极其危险慎动”的警示。定义好语义之后配合todo-tree.general.tagGroups还能做标签归类。比如把FIXME和BUG归到一个组展示的时候它们会合并到一个聚合标签下面避免侧边栏标签太多导致视觉噪音。例如todo-tree.general.tagGroups: { Unfinished: [TODO, WORKING], Defects: [FIXME, BUG] }分组会让树视图的层级更清晰不会出现七八个标签平行罗列的散乱效果。不过分组之后原本标签的独立颜色可能被覆盖这一点要测试确认免得高亮失效。4.2 结合 Git 分支和 commit message 使用有人会问代码注释里的 TODO 和任务管理工具里的 ticket 有什么区别我认为它们各有分工。ticket 管的是“为完成而进行的项目任务”包含排期、负责人、验收标准代码注释里的 TODO 则负责“上下文内联提醒”它就在出问题的代码旁边不需要你切到 Jira 或者看板去对应。更好的做法是把两者结合。在写 TODO 时顺手带上问题背景和日期比如// TODO(2025-06-10): 这里需要处理分页参数丢失的问题相关 ticket T-2231。这样 Todo Tree 扫描结果里直接就能看到时间和编号。配合 Git 提交历史别人用git blame也能追到到底是哪个 commit 加上了这条注释谁写的、什么时候写的一目了然。另外把.vscode/settings.json中的配置提交到版本库后Todo Tree 的扫描规则也会成为团队规范的一部分。代码评审时如果你的 diff 里带着FIXME或者HACK评审人可以很自然地追问一句“这个改动是临时绕法还是遗留问题”这种透明性恰恰是很多团队缺少的。4.3 自动化提效快捷键绑定与工作台侧栏布局树视图再好如果每次都要鼠标点一下侧边栏图标再切回来体验还是会打折扣。我建议给 Todo Tree 绑一个快捷键来切换视图焦点。在 keybindings.json 里加一条{ key: ctrlaltt, command: todo-tree.focus }这样写代码时随手按一下就能打开 TODO 树再按一下焦点回到编辑器。另一个常用的命令是todo-tree.refresh如果你发现某些文件没被扫描到手动刷新。侧边栏布局也有讲究。我的习惯是把 TODO Tree 视图放在资源管理器的下方或者放到辅助侧栏里这样编辑器主区域不被压缩树视图作为“第二面板”存在。多显示器用户甚至可以把它拖到副屏常驻写代码和看待办互不干扰。布局这东西看个人习惯但值得花几分钟调成顺手的样子因为每天都会用到。5. 常见问题与排查技巧实录5.1 树视图是空的为什么装完 Todo Tree 打开视图结果空空如也这是新手最常碰到的情况。原因通常有这么几类。第一项目里可能真的没有匹配到。默认 tags 只有TODO、FIXME如果你写的注释是todo小写或者用的是FIX、NOTE它就不会识别。先把 tags 范围调大一点扫一把看看。第二你的代码注释符号没被正则覆盖。比如用的/** ... */块注释或者是用--开头的 SQL 注释默认正则可能匹配不到。这时候需要自定义 regex把注释符号加进匹配规则。第三工作区根目录选错了。如果你打开的是一个文件夹但项目代码实际在backend子目录里而 includeGlobs 又写了从根目录开始的绝对路径就会扫不到。检查 includeGlobs 用的**通配符是否到位。第四扫描被过滤规则挡掉的概率很大。node_modules、dist、build 这类目录默认会被跳过如果你把代码放在一个叫build_output的自定义目录里恰好又匹配了 excludeGlobs 中的**/build*/**那也会被吞掉。逐条检查过滤配置是最快的排查路径。5.2 搜索结果错位字符串和注释混在一起Todo Tree 的匹配核心是正则而正则本身无法理解“这是注释还是字符串”。它只能看到一个符号和后面的关键字。比如下面这行const WARNING FIXME: 该模块已废弃;这明显是一段字符串但默认正则如果没做限定就可能被误判成注释。解决办法是让正则更贴合你项目的注释风格。比如 JS/TS 项目把正则写成todo-tree.general.regex: (//|\\*\\s|/\\*|!--)\\s*($TAGS)这样只匹配//、*、/*、!--后面的内容字符串里的FIXME就不会被抓到。不同语言有不同的注释前缀建议在看板里整理一份团队内常用语言的注释风格清单再统一更新 regex。另一个常见的错位是跨行注释被拆开。比如/* TODO: xxx和yyy */跨了多行匹配逻辑可能只认第一行导致注释后半部分信息丢失。这种情况一般不影响定位但如果你确实需要完整展示多行注释就得把 regex 设计成支持匹配到块注释尾部复杂度会上升。我的建议是定位靠行号完整内容靠编辑器不需要强迫 Todo Tree 把整段注释都展示出来。5.3 刷新不及时/性能问题在特别大的仓库里Todo Tree 扫描全量文件可能需要好几秒甚至让人觉得卡顿。首先确认 excludeGlobs 是否覆盖了所有会拖慢扫描的目录node_modules、dist、build、.git 之外的临时目录都要排掉。接着可以配置自动刷新间隔避免每次保存文件都触发一次全量扫描。把刷新间隔调到 5 到 10 秒或者干脆关闭自动刷新用快捷键手动刷新。方案是todo-tree.general.autoRefresh: false不过autoRefresh在不同版本行为可能不一样有的版本默认就是文件变更后自动更新。性能实在不行时打开 VS Code 的“输出”面板切换扩展日志到 Todo Tree看看它扫描了哪些目录能帮你快速找到“幕后黑手”。5.4 高亮没生效/颜色错乱有时候侧边栏树视图里有内容但编辑器内部的高亮不显示。先确认todo-tree.highlighting.enabled有没有被工作区配置覆盖掉。VS Code 的配置优先级是工作区配置 用户配置所以项目里的.vscode/settings.json如果有别的值会覆盖你的个人设置。如果你用了自定义主题某些主题自带注释高亮可能会跟 Todo Tree 的颜色互相干扰。这时候开启useColoredBackground通常能解决因为背景色比文字色的冲突概率小。还有一个很容易踩的坑不同标签设置了相同颜色导致看起来像“高亮失效”。我给每个标签分配颜色时会特意错开色相比如 TODO 用蓝色、FIXME 用红、HACK 用橙这样即使轻微干扰也能区分。6. 我的实际工作流与使用建议6.1 高效利用树视图的三种工作方式我实际用 Todo Tree 的方式大概有三种场景。早上打开电脑第一件事就是展开侧边栏扫一遍看哪个文件下面挂着一堆 FIXME 和 HACK能当天处理就当天处理掉别让它们躺在代码里过夜。这是“待办巡检”模式。第二种是写新功能时临时用 TODO 占位把拆解好的子任务写在对应代码附近。等实现到那个位置的时候树视图刚好提醒我还有哪些占位没填完。这等于把一个大需求拆成了代码里的“子任务线”非常顺手不会漏。第三种是代码评审前打开树视图按标签过滤专门看本次改动涉及的文件里有没有新增 TODO 或 FIXME。如果发现某个 PR 同时又加了不少 TODO就要追问这些是刻意留下的跟进事项还是半成品6.2 给团队推广的三条建议第一统一标签和配色。开发者在哪个文件里写了什么标记其他人一眼能看懂减少“这个 XXX 是什么”的沟通成本。真别小看这一点等团队里混入了FIXME、BUG、ISSUE、PROBLEM等各种叫法之后树视图会乱到没人愿意打开。第二把配置放进仓库而不是口头约定。.vscode/settings.json.vscode/extensions.json双重保障让任何新加入的成员 clone 项目就能用上同一套规则。第三维护注释“卫生”意识。Todo Tree 能帮你看到所有 TODO但它不能替你做决定。过期的 TODO、已经解决的 FIXME、失去价值的 HACK要定期清理。不然树视图也会积累成新的“没人认领”注释到那时候工具再好都是白搭。6.3 对这个小工具的一点个人体会装一个扩展只需要几秒钟但用得好不好差别在于你有没有认真想过“标签语义”这件事。Todo Tree 并不复杂它像一个非常朴素的助手把散落各处的注释备注变成一棵可视化的树。它不会自动帮你写代码也不会主动催促你但每次你想起来“我当时是不是有件事没做完”的时候打开侧边栏树就在那里安安静静地提醒你这里还欠着一点那边还有个隐患。代码世界里的很多事缺的不是意志力而是这样一个随时能想起来、一眼能看见的入口。对我这种记性不太好的开发者来说这已经非常值了。