如果你寫過一段時間代碼大概率會有這樣的經歷在某處寫了個// TODO: 這里要處理邊界情況三個月后翻了七八個文件都找不到最后發(fā)現它藏在工具函數里旁邊還長出了三四個新的FIXME。我自己之前維護一個中大型工程的時候這種感覺尤其強烈。后來我在 VS Code 里裝了 Todo Tree 這個擴展散落在代碼里的 TODO 類注釋終于有了一個統一的“匯總視圖”。說白了Todo Tree 就是一個能把代碼注釋中的TODO、FIXME、BUG等標記自動掃描出來并按照樹形結構展示在側邊欄的 VS Code 插件。它解決的核心痛點就一句話讓代碼里的臨時提醒不再因為散落各處而變成沒人認領的壞賬。這東西幾乎適配所有用 VS Code 的開發(fā)者不管你是寫前端、后端還是腳本語言裝的成本極低但每天節(jié)省的找代碼時間非?？捎^。1. 為什么你需要一個 Todo Tree散落注釋背后的管理難題1.1 代碼里的“便利貼墻”是怎么失控的很多團隊其實都有一套“代碼注釋規(guī)范”比如要求開發(fā)者把臨時計劃寫成// TODO把已知問題寫成// FIXME。初衷很好但實際執(zhí)行起來注釋就會像工位旁的便利貼一樣越貼越多越來越亂。你可能在某個函數里看到TODO: 優(yōu)化性能又在某個配置文件里看到FIXME: 這個地址寫死了但沒人能快速統計出這個倉庫里到底有多少個待辦項更別說分清哪些重要、哪些已經過時。我在一個小項目里試過總共幾千行代碼手動用全局搜索搜TODO結果也就幾十條勉強能掃一遍?？梢坏╉椖可狭艘?guī)模或者從 monorepo 里拉出幾個子項目一起開發(fā)文件數量上千語言類型混雜這時候再靠記憶或者全局搜索效率就非常低了。全局搜索固然能搜到所有TODO但它會把 node_modules、打包產物、日志文件里的無關內容全部帶進來而且結果是一長串平鋪的列表沒有按照業(yè)務模塊或者文件歸屬做歸類看完反而更暈。更麻煩的是這類注釋經?！俺恋怼钡經]人負責的狀態(tài)。一個人寫的HACK注釋另一個人看到后不敢動因為不知道當初為什么這么寫也不知道改了對不對。時間一長注釋就變成了“考古現場”。真正該做的不是禁止大家寫注釋而是給這些注釋一個統一的管理入口。1.2 Todo Tree 的核心思路用“樹”重新組織零散標記Todo Tree 這個擴展的原始名稱就很有畫面感它把代碼里那些“待辦事項”集中到一棵樹里展示。它的工作方式大體分成三步掃描、識別、展示。擴展會按你配置的規(guī)則去掃描工作區(qū)里的文件找出匹配特定標簽默認是TODO和FIXME的注釋然后把結果按目錄結構、文件歸屬或者標簽分組顯示在側邊欄的樹視圖里。這種設計的聰明之處在于它不只是把搜索到的結果列出來而是建立了一個“匯總、索引、跳轉”三合一的入口。你在樹視圖里看到一個文件下有幾個 TODO點一下就能跳到對應行不用自己記路徑也不用在文件里翻來翻去。對于開發(fā)者來說這種低成本調用的方式很重要因為寫臨時注釋本來就是順手的事查看這些注釋也應該順手否則就不會有人愿意用了。另外一個很關鍵的細節(jié)是Todo Tree 天然支持對不同標簽做區(qū)分。TODO和FIXME在語義上并不一樣TODO 偏向計劃開發(fā)的任務FIXME 則代表已知缺陷或待修復問題。如果都用同一種顏色、同一個列表展示重點很容易被稀釋。Todo Tree 可以直接給不同標簽分配不同配色緊急程度一目了然。1.3 跟其他方案對比搜索面板、書簽、TODO 的取舍你可能會想VS Code 自帶的全局搜索不也能搜TODO嗎確實能但它只是檢索文本不管語義。搜出來的結果里可能包含字符串文本、誤報而且不能按模塊做樹狀歸類。搜索面板適合“一次性查找”不適合“持續(xù)跟蹤”。還有人會提到書簽功能VS Code 的“書簽”擴展可以把指定位置存下來但這畢竟要手動添加而且書簽主要用于臨時定位不會自動感知代碼里新寫的 TODO 注釋。跟 Todo Tree 思路更接近的是另一個擴展TODO它同樣掃描 TODO 并展示側邊欄但在可配置性和樹視圖的細化程度上Todo Tree 更靈活。比如對正則的開放度、對不同文件過濾規(guī)則的支持、對標簽分組展示的能力Todo Tree 明顯更“能打”。我選 Todo Tree最看重的是它的“低心智負擔”裝完默認就能用配置項雖然多但大多數情況下只需要改 tags 和過濾規(guī)則兩部分。相比其他方案它把“掃描-索引-跳轉”閉環(huán)做得很順滑而且沒有強行把“任務管理”的概念塞進來它就是一個干凈的注釋索引器。2. 安裝與上手5分鐘把樹視圖跑起來2.1 安裝方式安裝 Todo Tree 有兩種方式最常規(guī)的是打開 VS Code 的擴展市場搜索Todo Tree找到作者為 Gruntfuggly 的擴展直接安裝。另一個方式是調出命令面板輸入ext install Gruntfuggly.todo-tree回車安裝。我個人更推薦后者因為擴展 ID 不會因為名稱撞車而裝錯。安裝完成之后側邊欄上會出現一個“TODO Tree”的視圖容器圖標點擊就能打開樹視圖。如果你打開一個比較大的項目它會立刻開始掃描。掃描速度通常很快因為默認情況下它會跳過 node_modules、.git 這類目錄除非你主動告訴它去掃描。2.2 基本操作流程打開樹視圖之后你會發(fā)現它按文件夾和文件的層級關系展示每個匹配項。比如src/utils/index.js下面掛著兩個 TODO一個 FIXME每一行還可以展開顯示具體注釋內容。點擊任意一條記錄右側編輯器會自動打開對應文件并定位到那一行。視圖頂部有幾個快捷按鈕刷新按鈕最重要。雖然擴展默認在文件保存時自動更新但某些版本或特殊場景下自動刷新可能不夠及時手動刷新一下更穩(wěn)妥。折疊按鈕可以把所有樹節(jié)點收起適合快速瀏覽整體分布。有些版本還提供文本過濾輸入框可以在樹內篩選出你關注的關鍵字這類細節(jié)在項目很大時非常有用。我第一次上手時只做了三件事刪掉了視圖里的“默認高亮全開”因為覺得太花把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. 配置參數詳解從默認值到自己掌控掃描規(guī)則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之間的匹配默認是忽略了大小寫還是嚴格區(qū)分取決于你的配置方式。如果你直接寫死正則比如regex: //\\s*(TODO)那它就不會匹配todo。如果你用 tags 標簽數組大小寫敏感的開關由擴展內部邏輯決定具體可以通過實際測試確定。我的習慣是代碼注釋里統一用大寫TODO/FIXME約定簡單配置也簡單。3.2 過濾規(guī)則哪些文件該掃哪些該忽略過濾配置是整個擴展里最需要花心思的部分因為它直接影響掃描準確度和性能。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中的排除規(guī)則。這兩個默認基本都是開著的能幫你過濾掉大量無關文件。我個人傾向于保持開啟只有在想“故意找點歷史遺留”的時候才會臨時關掉比如排查某個被 .gitignore 忽略的配置文件里有沒有 TODO。3.3 高亮與展示讓緊急標記一眼可見樹視圖只是索引真正在你寫代碼時給你提醒的是高亮功能。todo-tree.highlighting.enabled控制總開關默認開啟。開啟后匹配到的標簽和注釋內容會在編輯器內上色。todo-tree.highlighting.useColoredBackground決定了是用背景色還是文字顏色來突出顯示。我個人的習慣是開啟背景色因為文字顏色容易被主題配色干擾背景色更醒目。todo-tree.highlighting.backgroundColor可以自定義成半透明色避免遮擋代碼。此外還可以通過todo-tree.highlighting.opacity調透明度。更實用的是給不同標簽分配不同顏色。假設項目里定了這樣一套規(guī)則FIXME用紅色背景表示必須盡快處理HACK用橙色TODO用藍色REVIEW用綠色。代碼掃一眼就知道當前區(qū)塊有沒有坑比逐個讀注釋快得多。配色雖然有個人傾向但團隊合作時建議稍微統一一下否則互相看的代碼“五顏六色”反而造成理解成本。3.4 團隊級配置把 .vscode/settings.json 作為事實標準如果你是一個人在自己的機器上用 Todo Tree改設置只管自己爽。但如果要在團隊里統一推廣靠每個人手動改配置是不可靠的總有人漏裝擴展或者用了不同版本導致行為不一致。更穩(wěn)妥的做法是把 Todo Tree 的配置放在項目根目錄的.vscode/settings.json里。只要團隊成員打開這個倉庫就會自動加載工作區(qū)配置。再加上.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 }這份配置只依賴比較穩(wěn)定的核心字段。把它提交到倉庫之前記得跟團隊說明一下這不是強制大家寫注釋而是統一一下注釋的“可見度”讓大家寫下的 TODO 能被更可靠地看到。4. 進階玩法讓 Todo Tree 融入代碼管理與團隊協作4.1 標記分級用不同標簽表達不同緊急度Todo Tree 擅長識別標簽但光識別還不夠你得讓標簽本身具備語義。我建議把常見標簽當成“級別”來用而不是隨手亂標。TODO代表計劃中的任務可能是下一階段要做的優(yōu)化、功能補齊不一定有明確的 deadlineFIXME代表已知問題比如邏輯 bug、數據異常優(yōu)先級高于 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 有什么區(qū)別我認為它們各有分工。ticket 管的是“為完成而進行的項目任務”包含排期、負責人、驗收標準代碼注釋里的 TODO 則負責“上下文內聯提醒”它就在出問題的代碼旁邊不需要你切到 Jira 或者看板去對應。更好的做法是把兩者結合。在寫 TODO 時順手帶上問題背景和日期比如// TODO(2025-06-10): 這里需要處理分頁參數丟失的問題相關 ticket T-2231。這樣 Todo Tree 掃描結果里直接就能看到時間和編號。配合 Git 提交歷史別人用git blame也能追到到底是哪個 commit 加上了這條注釋誰寫的、什么時候寫的一目了然。另外把.vscode/settings.json中的配置提交到版本庫后Todo Tree 的掃描規(guī)則也會成為團隊規(guī)范的一部分。代碼評審時如果你的 diff 里帶著FIXME或者HACK評審人可以很自然地追問一句“這個改動是臨時繞法還是遺留問題”這種透明性恰恰是很多團隊缺少的。4.3 自動化提效快捷鍵綁定與工作臺側欄布局樹視圖再好如果每次都要鼠標點一下側邊欄圖標再切回來體驗還是會打折扣。我建議給 Todo Tree 綁一個快捷鍵來切換視圖焦點。在 keybindings.json 里加一條{ key: ctrlaltt, command: todo-tree.focus }這樣寫代碼時隨手按一下就能打開 TODO 樹再按一下焦點回到編輯器。另一個常用的命令是todo-tree.refresh如果你發(fā)現某些文件沒被掃描到手動刷新。側邊欄布局也有講究。我的習慣是把 TODO Tree 視圖放在資源管理器的下方或者放到輔助側欄里這樣編輯器主區(qū)域不被壓縮樹視圖作為“第二面板”存在。多顯示器用戶甚至可以把它拖到副屏常駐寫代碼和看待辦互不干擾。布局這東西看個人習慣但值得花幾分鐘調成順手的樣子因為每天都會用到。5. 常見問題與排查技巧實錄5.1 樹視圖是空的為什么裝完 Todo Tree 打開視圖結果空空如也這是新手最常碰到的情況。原因通常有這么幾類。第一項目里可能真的沒有匹配到。默認 tags 只有TODO、FIXME如果你寫的注釋是todo小寫或者用的是FIX、NOTE它就不會識別。先把 tags 范圍調大一點掃一把看看。第二你的代碼注釋符號沒被正則覆蓋。比如用的/** ... */塊注釋或者是用--開頭的 SQL 注釋默認正則可能匹配不到。這時候需要自定義 regex把注釋符號加進匹配規(guī)則。第三工作區(qū)根目錄選錯了。如果你打開的是一個文件夾但項目代碼實際在backend子目錄里而 includeGlobs 又寫了從根目錄開始的絕對路徑就會掃不到。檢查 includeGlobs 用的**通配符是否到位。第四掃描被過濾規(guī)則擋掉的概率很大。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 之外的臨時目錄都要排掉。接著可以配置自動刷新間隔避免每次保存文件都觸發(fā)一次全量掃描。把刷新間隔調到 5 到 10 秒或者干脆關閉自動刷新用快捷鍵手動刷新。方案是todo-tree.general.autoRefresh: false不過autoRefresh在不同版本行為可能不一樣有的版本默認就是文件變更后自動更新。性能實在不行時打開 VS Code 的“輸出”面板切換擴展日志到 Todo Tree看看它掃描了哪些目錄能幫你快速找到“幕后黑手”。5.4 高亮沒生效/顏色錯亂有時候側邊欄樹視圖里有內容但編輯器內部的高亮不顯示。先確認todo-tree.highlighting.enabled有沒有被工作區(qū)配置覆蓋掉。VS Code 的配置優(yōu)先級是工作區(qū)配置 用戶配置所以項目里的.vscode/settings.json如果有別的值會覆蓋你的個人設置。如果你用了自定義主題某些主題自帶注釋高亮可能會跟 Todo Tree 的顏色互相干擾。這時候開啟useColoredBackground通常能解決因為背景色比文字色的沖突概率小。還有一個很容易踩的坑不同標簽設置了相同顏色導致看起來像“高亮失效”。我給每個標簽分配顏色時會特意錯開色相比如 TODO 用藍色、FIXME 用紅、HACK 用橙這樣即使輕微干擾也能區(qū)分。6. 我的實際工作流與使用建議6.1 高效利用樹視圖的三種工作方式我實際用 Todo Tree 的方式大概有三種場景。早上打開電腦第一件事就是展開側邊欄掃一遍看哪個文件下面掛著一堆 FIXME 和 HACK能當天處理就當天處理掉別讓它們躺在代碼里過夜。這是“待辦巡檢”模式。第二種是寫新功能時臨時用 TODO 占位把拆解好的子任務寫在對應代碼附近。等實現到那個位置的時候樹視圖剛好提醒我還有哪些占位沒填完。這等于把一個大需求拆成了代碼里的“子任務線”非常順手不會漏。第三種是代碼評審前打開樹視圖按標簽過濾專門看本次改動涉及的文件里有沒有新增 TODO 或 FIXME。如果發(fā)現某個 PR 同時又加了不少 TODO就要追問這些是刻意留下的跟進事項還是半成品6.2 給團隊推廣的三條建議第一統一標簽和配色。開發(fā)者在哪個文件里寫了什么標記其他人一眼能看懂減少“這個 XXX 是什么”的溝通成本。真別小看這一點等團隊里混入了FIXME、BUG、ISSUE、PROBLEM等各種叫法之后樹視圖會亂到沒人愿意打開。第二把配置放進倉庫而不是口頭約定。.vscode/settings.json.vscode/extensions.json雙重保障讓任何新加入的成員 clone 項目就能用上同一套規(guī)則。第三維護注釋“衛(wèi)生”意識。Todo Tree 能幫你看到所有 TODO但它不能替你做決定。過期的 TODO、已經解決的 FIXME、失去價值的 HACK要定期清理。不然樹視圖也會積累成新的“沒人認領”注釋到那時候工具再好都是白搭。6.3 對這個小工具的一點個人體會裝一個擴展只需要幾秒鐘但用得好不好差別在于你有沒有認真想過“標簽語義”這件事。Todo Tree 并不復雜它像一個非常樸素的助手把散落各處的注釋備注變成一棵可視化的樹。它不會自動幫你寫代碼也不會主動催促你但每次你想起來“我當時是不是有件事沒做完”的時候打開側邊欄樹就在那里安安靜靜地提醒你這里還欠著一點那邊還有個隱患。代碼世界里的很多事缺的不是意志力而是這樣一個隨時能想起來、一眼能看見的入口。對我這種記性不太好的開發(fā)者來說這已經非常值了。