我接手過(guò)一個(gè)很老的內(nèi)部工程依賴包從deprecated-lib換成new-lib,光 import 路徑就散在幾十個(gè)文件里更別提還有一堆調(diào)用方法名必須跟著改。當(dāng)時(shí)我第一反應(yīng)是祭出sed一頓操作結(jié)果替換完之后編譯直接炸了一半有的地方多替換了、有的地方漏了最尷尬的是改壞了還沒法快速回滾只能靠 git diff 一行行找。后來(lái)我花了一個(gè)周末寫了t3code——一個(gè)聲明式的、可審計(jì)的批量代碼替換與重構(gòu)工具從那以后這類“全局替換”對(duì)我來(lái)說(shuō)就從一個(gè)高風(fēng)險(xiǎn)動(dòng)作變成了一條安全、可復(fù)現(xiàn)的流水線。這篇文章不聊空泛理念直接講清楚 t3code 是什么、為什么需要它、規(guī)則文件怎么寫、遇到哪些坑以及我把它塞進(jìn)團(tuán)隊(duì)工程流程里的完整經(jīng)驗(yàn)。1. 從一次差點(diǎn)翻車的全局替換說(shuō)起t3code 的誕生背景先還原一下當(dāng)時(shí)的場(chǎng)景。那個(gè)項(xiàng)目是個(gè)典型的歷史包袱工程核心模塊從老框架遷移到新框架依賴包名變了一套工具類的方法前綴也從oldUtil_統(tǒng)一改成newUtil_。表面上看這就是個(gè)“查找替換”的活可真正動(dòng)手才發(fā)現(xiàn)痛點(diǎn)全藏在細(xì)節(jié)里有些 import 是from deprecated-lib/foo有些是from deprecated-lib直接全局替換會(huì)把路徑拼錯(cuò)方法名替換涉及字符串拼接的場(chǎng)景比如oldUtil_getName()在代碼里有十多種寫法有的帶空格、有的帶換行替換完必須驗(yàn)證“沒有漏、沒有多”單靠肉眼掃 diff 根本不現(xiàn)實(shí)最要命的是一旦替換完編譯報(bào)錯(cuò)想回到替換前只能靠git checkout,如果中間還混了手動(dòng)改動(dòng)那就徹底亂了。我的需求逐漸清晰我希望有一個(gè)工具能把“我要把什么改成什么”寫成一份人類可讀的聲明式文件然后它負(fù)責(zé)掃描、替換、留備份、給審計(jì)報(bào)告還能反復(fù)執(zhí)行不重復(fù)污染。t3code 就是這么來(lái)的。它本質(zhì)上是一個(gè)命令行工具核心能力概括成一句話按照規(guī)則文件在保留原始文件備份的前提下對(duì)目標(biāo)目錄下的代碼進(jìn)行精準(zhǔn)的字符串替換、命名重寫和模板化內(nèi)容生成。它不是萬(wàn)能的也不打算替代編譯器做靜態(tài)分析但它能把你從“批量替換翻車”這個(gè)泥潭里拉出來(lái)。如果你和我一樣經(jīng)常要處理依賴升級(jí)、API 遷移、工程腳手架初始化這類場(chǎng)景或者你想把“代碼批量替換”這件事變成一個(gè)可提交到倉(cāng)庫(kù)、可供團(tuán)隊(duì)復(fù)用的動(dòng)作那 t3code 很適合你。如果你只是偶爾改兩三個(gè)文件那用編輯器自帶的全局搜索替換就夠了不必上這個(gè)工具——這一點(diǎn)后面會(huì)展開說(shuō)。2. 工具定位與設(shè)計(jì)取舍它到底解決哪一類問(wèn)題t3code 解決的核心問(wèn)題不是“換字符串”而是“讓批量替換這個(gè)動(dòng)作變得可控、可審計(jì)、可回滾、可重復(fù)”。它不是天生地義的任務(wù)而是有明顯適用邊界的工具。理解這個(gè)邊界比會(huì)寫規(guī)則文件更重要。2.1 和 sed / perl 對(duì)比聲明式規(guī)則 vs 一行流以前做全局替換最常見的方案是sed -i或者perl -pi -e。這倆強(qiáng)大是真強(qiáng)大問(wèn)題也真不少命令一長(zhǎng)基本沒人看得懂寫的時(shí)候圖快執(zhí)行完了追悔莫及而且同樣一段命令在這臺(tái)機(jī)器上有效到另一臺(tái)機(jī)器上遇到不同編碼、換行符直接就翻車。t3code 把“替換動(dòng)作”提升為“規(guī)則”。一條規(guī)則包含四個(gè)核心要素目標(biāo)范圍scope、匹配模式match、替換內(nèi)容write或腳本script、執(zhí)行的配置文件。規(guī)則用 YAML 寫任何人打開就能看懂“要改什么、改成什么”。例如同樣是把某個(gè)依賴包改名sed 命令行是一串難以閱讀的正則t3code 的規(guī)則文件則是這樣一段語(yǔ)義化結(jié)構(gòu)rules: - name: migrate-dependency-path scope: include: [src/**/*.{js,ts}] replace: - from: deprecated-lib/foo to: new-lib/bar語(yǔ)義清晰、可 diff、可 review。這對(duì)我來(lái)說(shuō)是本質(zhì)區(qū)別sed 是“一個(gè)動(dòng)作”t3code 是“一份可維護(hù)的配置”。2.2 和 IDE 全局替換對(duì)比從本機(jī)行為變成團(tuán)隊(duì)資產(chǎn)IDE 的全局替換也很好用但它綁定在人身上我在自己編輯器里換完了同事不知道CI 也不知道新來(lái)的同事拿著老代碼還是會(huì)踩一遍同樣的坑。而且 IDE 的替換往往是“一次性動(dòng)作”缺少“持續(xù)應(yīng)用”的能力。t3code 的規(guī)則文件是獨(dú)立存在的可以和代碼一起進(jìn) Git 倉(cāng)庫(kù)。團(tuán)隊(duì)里任何人想執(zhí)行同樣一套遷移只需跑t3 run --profile rc-2024結(jié)果一致日志一致且失敗時(shí)有據(jù)可查。它把“個(gè)人本機(jī)操作”變成了“團(tuán)隊(duì)工程資產(chǎn)”這是我把它定位成“工具鏈成員”而非“編輯器插件替代品”的原因。2.3 t3code 不擅長(zhǎng)什么邊界要提前講清楚得潑一盆冷水t3code 不是代碼理解工具它不懂語(yǔ)法樹也不會(huì)幫你判斷替換后是否邏輯等價(jià)。它擅長(zhǎng)的是“文本層面的、規(guī)則明確的”替換。比如依賴包路徑統(tǒng)一遷移適合函數(shù)調(diào)用點(diǎn)批量改名不帶括號(hào)解析適合腳手架模板變量渲染適合需要理解“這個(gè)函數(shù)是否被重載、調(diào)用參數(shù)是否需要同步變化”的深層次重構(gòu)不適合。那種場(chǎng)景應(yīng)該去用 jscodeshift、CocoaPods 之類的 AST 級(jí)工具或者干脆交給 IDE 的語(yǔ)言服務(wù)。t3code 的目標(biāo)是覆蓋“中間地帶”文本層面有規(guī)律、人工改容易漏、又不想上重型工具的那部分需求。承認(rèn)邊界反而讓它在自己的領(lǐng)域里更可信。3. 上手前的準(zhǔn)備與第一個(gè)規(guī)則文件五分鐘跑通這一節(jié)直接動(dòng)手。我用一個(gè)最簡(jiǎn)單的示例帶你跑通 t3code 的整體路徑安裝、寫規(guī)則、預(yù)覽、執(zhí)行、審計(jì)。3.1 安裝與初始化t3code 是單二進(jìn)制文件沒有運(yùn)行時(shí)依賴。我常用的兩種安裝方式# 方式一brew 安裝macOS 或 Linux brew install t3code/tap/t3code # 方式二直接下載 release 二進(jìn)制 curl -sSL https://example.com/t3code/releases/latest/t3code-linux-amd64.tar.gz | tar -xz sudo mv t3code /usr/local/bin/安裝完先確認(rèn)版本順便看幫助信息t3code --version t3code --help初始化會(huì)在當(dāng)前目錄生成一個(gè)空的t3code.yml和.t3code/工作目錄用來(lái)放備份和日志t3 init執(zhí)行完之后目錄結(jié)構(gòu)如下. ├── t3code.yml # 規(guī)則與配置文件 └── .t3code/ # 本地工作目錄備份、日志、審計(jì)報(bào)告3.2 規(guī)則文件基礎(chǔ)結(jié)構(gòu)T3file.yml 的核心配置項(xiàng)我習(xí)慣把規(guī)則文件命名為t3code.yml但名字不是強(qiáng)制的-f參數(shù)可以指定任意路徑。一個(gè)典型的初版配置長(zhǎng)這樣version: 1 profiles: default: rules: [migrate-old-lib] rc-2024: rules: [migrate-old-lib, rename-utils-prefix] rules: - name: migrate-old-lib scope: include: [src/**/*.{js,ts,jsx,tsx}] exclude: [**/node_modules/**, **/dist/**] replace: - from: old-lib to: new-lib - from: from old-lib/(\\w) to: from new-lib/\\1說(shuō)幾個(gè)關(guān)鍵點(diǎn)version: 1規(guī)則文件格式版本目前只有 1保留它主要是為了未來(lái)兼容profiles一組規(guī)則的有序集合。這個(gè)設(shè)計(jì)解決的是“不同批次遷移要分開執(zhí)行”的問(wèn)題——你可以把第一階段的規(guī)則叫rc-2024,第二階段叫sprint-3按需 run 指定 profilescope執(zhí)行范圍include/exclude用 glob 匹配支持**和{}。強(qiáng)烈建議第一個(gè)版本就寫明排除node_modules、dist、.git不然掃描會(huì)痛苦地卡住replace.from/to支持字符串也支持正則正則寫法對(duì)標(biāo) JavaScript 的 RegExp替換引用用\1、\2。一個(gè) rule 的名字是全局唯一的后續(xù)審計(jì)、回滾都會(huì)用它作為定位標(biāo)識(shí)命名建議帶業(yè)務(wù)語(yǔ)義比如migrate-old-lib就比rule1好一萬(wàn)倍。3.3 第一次執(zhí)行dry-run、plan、run、audit新手最容易犯的錯(cuò)誤是拿起來(lái)就執(zhí)行run,結(jié)果一發(fā)不可收拾。t3code 提供了串行鏈路我強(qiáng)烈建議第一次跑時(shí)按這條鏈路走# 第一步只掃描不改文件輸出將會(huì)命中的所有文件清單 t3 scan --profile default # 第二步在內(nèi)存里做替換輸出詳細(xì) diff 但不寫盤 t3 plan --profile default # 第三步確認(rèn)無(wú)誤后執(zhí)行真實(shí)替換 t3 run --profile default # 第四步生成審計(jì)報(bào)告能看到每個(gè)文件被哪條規(guī)則改了多少處 t3 audit --profile defaultscan和plan的區(qū)別要搞清楚scan只是告訴你“有哪些文件會(huì)被掃到”plan是實(shí)際跑一遍替換邏輯把“改前 vs 改后”的 diff 展示給你看。我實(shí)際使用中80% 的問(wèn)題在plan階段就會(huì)被發(fā)現(xiàn)——比如某條正則把不該改的配置也匹配了這時(shí)直接微調(diào)規(guī)則就行不會(huì)污染代碼。run執(zhí)行時(shí)每個(gè)被修改的文件都會(huì)自動(dòng)在.t3code/backups/下生成一份原始副本備份按時(shí)間戳/文件相對(duì)路徑歸檔。這就是后面revert的底氣。3.4 用表格快速理解五個(gè)常用子命令命令作用會(huì)不會(huì)寫文件什么時(shí)候用t3 init初始化目錄和工作區(qū)會(huì)創(chuàng)建配置文件首次接入項(xiàng)目t3 scan掃描命中范圍否快速確認(rèn)影響面t3 plan預(yù)覽替換 diff否每次執(zhí)行前必跑t3 run執(zhí)行規(guī)則替換是含備份確認(rèn)無(wú)誤后t3 audit輸出審計(jì)報(bào)告否寫日志事后核對(duì)、留下記錄第一次跑通這套鏈路你對(duì) t3code 的信任感會(huì)很快建立起來(lái)因?yàn)槟忝恳淮握鎸?shí)改動(dòng)之前工具都先給了你“后悔藥”和“體檢報(bào)告”。4. 四個(gè)真實(shí)案例從簡(jiǎn)單替換到跨文件重構(gòu)光看配置結(jié)構(gòu)不夠我用四個(gè)真實(shí)場(chǎng)景證明 t3code 的覆蓋力。這四段并不是虛構(gòu)而是我在不同階段驗(yàn)證過(guò)的典型用法。4.1 案例 A依賴包路徑批量遷移這是最基礎(chǔ)也最經(jīng)典的用法。項(xiàng)目里所有from old-lib要改成from new-lib,但old-lib/foo這類子路徑也必須對(duì)應(yīng)遷移不能只替換前綴。規(guī)則文件這樣寫rules: - name: migrate-lib-root scope: include: [src/**/*.js] replace: - from: old-lib to: new-lib這里的小技巧是我把匹配錨定在單引號(hào)之后而不是簡(jiǎn)單匹配old-lib全局。為什么因?yàn)榇a里可能出現(xiàn)const oldLib something這種駝峰變量名或者注釋里的提到old-lib,如果直接from: old-lib就會(huì)誤殺。加一個(gè)前導(dǎo)引號(hào)讓規(guī)則只命中真正的 import 路徑場(chǎng)景。執(zhí)行前再用plan檢查一遍 diff確認(rèn)沒有動(dòng)到注釋和變量。4.2 案例 B舊 API 向新 API 遷移這次不是單對(duì)單的替換而是帶“參數(shù)變換”的遷移。舊 API 是util.getUser(id, { withPosts: true }),新 API 改成userApi.fetch(id, { include: [posts] })。純字符串替換做不了這種改變,但 t3code 的腳本項(xiàng)可以。rules: - name: migrate-get-user-api scope: include: [src/**/*.js] script: - re: util\\.getUser\\((\\w), \\{ withPosts: true \\}\\) run: | (orig, captures) { const id captures[1]; return userApi.fetch(${id}, { include: [posts] }); }script 塊支持三段式re是正則匹配run是一段 JavaScript 函數(shù)體入?yún)⑹莖rig原始完整匹配和captures捕獲組數(shù)組返回值就是替換結(jié)果。這里能跑任意 JS 邏輯所以像“參數(shù)順序調(diào)整”“布爾參數(shù)轉(zhuǎn)數(shù)組參數(shù)”都能實(shí)現(xiàn)。執(zhí)行效果// 改前 const data util.getUser(42, { withPosts: true }); // 改后 const data userApi.fetch(42, { include: [posts] });需要提醒的是script 雖然靈活但可讀性會(huì)下降而且里面一旦有 bug影響面也大。我的經(jīng)驗(yàn)是——能用靜態(tài)replace的盡量用靜態(tài) replacescript 留給“確實(shí)要?jiǎng)舆壿嫿Y(jié)構(gòu)”的場(chǎng)景。4.3 案例 C工程腳手架變量渲染t3code 另一個(gè)讓我驚喜的場(chǎng)景是腳手架變量替換。以前寫項(xiàng)目模板會(huì)留著__PROJECT_NAME__這種占位符新項(xiàng)目拉下來(lái)以后手動(dòng)替換替換漏了就盯著編譯錯(cuò)誤一個(gè)個(gè)找。t3code 把這件事也自動(dòng)化了。rules: - name: render-project-vars scope: include: [**/*.{json,ts,js,md}] exclude: [**/node_modules/**, **/package-lock.json] replace: - from: __PROJECT_NAME__ to: my-cool-project - from: __AUTHOR_NAME__ to: litao配合 snippet 功能還能做更復(fù)雜的文件模板——比如根據(jù)參數(shù)生成 README 片段。核心思路沒變所有模板占位符的替換規(guī)則都沉淀在 t3code.yml 里而不是靠人肉記憶。4.4 案例 D多階段重構(gòu)策略大型重構(gòu)通常不是一次替換就能完成的。我習(xí)慣給每個(gè)階段建一個(gè) profile然后逐個(gè)執(zhí)行profiles: phase-1: rules: [rename-imports] phase-2: rules: [rename-imports, migrate-api-calls] phase-3: rules: [rename-imports, migrate-api-calls, cleanup-comments]這樣有幾個(gè)好處每個(gè)階段的審計(jì)報(bào)告是獨(dú)立的git 提交歷史可以和階段一一對(duì)應(yīng)出問(wèn)題時(shí)能精準(zhǔn)定位“是哪個(gè)階段、哪條規(guī)則改壞的”團(tuán)隊(duì)評(píng)審時(shí)也可以按 profile 分批看 diff而不是一次性交一個(gè)巨型改動(dòng)。5. 干了再說(shuō)的代價(jià)回滾、審計(jì)與執(zhí)行保護(hù)機(jī)制批量替換最讓人緊張的就是“改壞了怎么辦”。這一節(jié)專門講 t3code 在安全層面做的設(shè)計(jì)以及我實(shí)際用下來(lái)的注意事項(xiàng)。5.1 默認(rèn)備份每次執(zhí)行都有后悔藥前面提到t3 run會(huì)自動(dòng)備份備份目錄結(jié)構(gòu)如下.t3code/backups/ └── 2024-06-17T14-30-22/ ├── src/utils/api.js ├── src/components/UserCard.js └── manifest.json恢復(fù)單個(gè)文件cp .t3code/backups/2024-06-17T14-30-22/src/utils/api.js src/utils/api.js如果是想恢復(fù)一整次執(zhí)行# 列出所有備份時(shí)間點(diǎn) t3 backups # 恢復(fù)到指定時(shí)間點(diǎn) t3 revert --backup-id 2024-06-17T14-30-22 --target src/注意revert的行為是“用備份文件覆蓋回當(dāng)前對(duì)應(yīng)路徑”它會(huì)假設(shè)你當(dāng)前目錄結(jié)構(gòu)和備份時(shí)一致。如果中間你手動(dòng)新增了文件新增文件不會(huì)被刪除——這是有意的保守設(shè)計(jì)回滾只管“被改過(guò)的文件”不負(fù)責(zé)“替你刪除新變量”。5.2 審計(jì)日志不只是給自己看也是給團(tuán)隊(duì)看的每次執(zhí)行之后審計(jì)報(bào)告在.t3code/logs/下生成內(nèi)容包括執(zhí)行時(shí)間、執(zhí)行的 profile、命中的規(guī)則列表 每個(gè)文件被哪條規(guī)則命中、替換了幾處 是否有跳過(guò)文件比如二進(jìn)制、超限大文件 警告信息如“替換后的內(nèi)容與備份完全一致可能是正則沒生效”。我前陣子做一次跨模塊遷移改完后同事想 review想知道“到底動(dòng)了哪些地方”我直接把審計(jì)報(bào)告貼到 PR 描述里人家不用翻幾百個(gè) diff 文件就能看到影響面。這個(gè)習(xí)慣后來(lái)成了團(tuán)隊(duì)規(guī)范——凡是 t3code 產(chǎn)生的批量改動(dòng)PR 里必須附審計(jì)報(bào)告。5.3 執(zhí)行保護(hù)scope 與 ignore 的合理配置執(zhí)行保護(hù)分為三層每一層都能有效避免“瞎改一通”第一層是scope.exclude把不該碰的目錄和文件排除掉。下面這個(gè)配置算是我的最低安全配置scope: include: [src/**/*.{js,ts,jsx,tsx}] exclude: - **/node_modules/** - **/dist/** - **/build/** - **/.git/** - **/*.min.js第二層是規(guī)則內(nèi)的files限定。有些規(guī)則只想作用于特定文件可以在 rule 內(nèi)單獨(dú)聲明files覆蓋全局 scoperules: - name: update-api-config files: [config/**/*.{json,ts}] replace: - from: apiVersion: 1 to: apiVersion: 2第三層是--dry-run標(biāo)志。run命令自帶--dry-run參數(shù)就算你不小心直接執(zhí)行 run也會(huì)因?yàn)?dry-run 默認(rèn)開啟而只輸出預(yù)覽不真正改文件。我是建議把它當(dāng)成默認(rèn)習(xí)慣run總是先帶--dry-run看一遍再不帶參數(shù)執(zhí)行真正的寫入。5.4 編碼與二進(jìn)制文件的坑t3code 默認(rèn)只處理文本文件遇到 NUL 字節(jié)會(huì)跳過(guò)。但文本文件也有編碼差異最常踩的是 BOM帶 BOM 的 UTF-8 文件在匹配時(shí)首行開頭會(huì)多一個(gè)\uFEFF如果你的正則錨定^from匹配會(huì)失敗。我的對(duì)策是規(guī)則里盡量用contains而不是行首錨定或者先跑一次t3 scan --encoding-check摸清文件編碼分布。換行符也是一個(gè)坑。同倉(cāng)庫(kù)里混著LF和CRLF是祖?zhèn)鞒B(tài)替換時(shí)如果to里寫死了\n,在 CRLF 文件里會(huì)導(dǎo)致混行換行符。我一般先t3 audit --line-endings看看分布再?zèng)Q定規(guī)則里要不要兼容\r?\n。6. 集成到團(tuán)隊(duì)工程流程中CI 檢查與 git hookst3code 的價(jià)值如果只停留在個(gè)人工具層面還是有點(diǎn)可惜。真正放大它價(jià)值的場(chǎng)景是把它嵌進(jìn)工程流程讓“批量替換”從一次性的手工操作變成自動(dòng)化、可強(qiáng)制執(zhí)行的環(huán)節(jié)。6.1 CI 里的“規(guī)則即測(cè)試”模式t3code 內(nèi)置--check參數(shù)執(zhí)行后不寫入文件只檢查“當(dāng)前代碼狀態(tài)是否符合規(guī)則期望”——簡(jiǎn)單理解就是如果規(guī)則要求old-lib應(yīng)該被替換成new-lib,--check檢測(cè)到還有old-lib存在就會(huì)以非零狀態(tài)退出。CI 里加一步# .github/workflows/code-quality.yml jobs: t3-check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: t3 run --check --profile default這一步的作用是一旦有人把舊依賴路徑又寫回代碼CI 會(huì)直接紅掉提示他用 t3code 規(guī)則修復(fù)。這比 eslint 的某些規(guī)則更直接因?yàn)樗峭耆趫F(tuán)隊(duì)自定義配置的。我實(shí)際用下來(lái)這類“防回潮檢查”特別適合代碼庫(kù)體量大、歷史包袱重的項(xiàng)目——防止老問(wèn)題死灰復(fù)燃。6.2 配合 pre-commit提交前就能攔截如果你不想把所有檢查都放到 CI畢竟 CI 反饋周期長(zhǎng)可以本地 pre-commit 鉤子里加 t3code 檢查# .pre-commit-config.yaml repos: - repo: local hooks: - id: t3code name: t3code rule enforcement entry: t3 run --check --profile default language: system pass_filenames: falsepass_filenames: false很關(guān)鍵因?yàn)?t3code 的規(guī)則是面向全倉(cāng)庫(kù)的不需要 pre-commit 傳單文件列表。有了這道防線開發(fā)者提交前就知道自己的改動(dòng)有沒有逆著規(guī)則走不用等 CI 跑完再回爐。6.3 規(guī)則文件版本管理把規(guī)則當(dāng)代碼一樣對(duì)待t3code.yml 和其他源碼一樣放 Git 倉(cāng)庫(kù)每次調(diào)整規(guī)則都要走正常的 code review 流程。我吃過(guò)一次虧直接在測(cè)試分支上改規(guī)則文件亂跑結(jié)果規(guī)則里寫錯(cuò)了一個(gè)字batch 替換了不該動(dòng)的地方。后來(lái)立了一條規(guī)矩規(guī)則文件的改動(dòng)必須獨(dú)立提交且要附上 plan 階段的 diff 示例這樣 reviewer 可以直觀看到新規(guī)則會(huì)改什么、會(huì)不會(huì)誤傷。另外規(guī)則文件的版本號(hào)可以對(duì)應(yīng)項(xiàng)目里程碑。比如項(xiàng)目里同時(shí)存在profile-sprint-1、profile-sprint-2,歷史提交時(shí)想復(fù)盤某個(gè)批次改動(dòng)直接按 profile 名搜審計(jì)日志就行。6.4 與 eslint/prettier 的配合先 t3code 再格式化我實(shí)際流程里通常先跑 t3code 做結(jié)構(gòu)和依賴路徑的批改再跑 prettier/eslint 統(tǒng)一風(fēng)格。順序不能反因?yàn)?t3code 做的是語(yǔ)義級(jí)文本替換替換完的格式可能比較凌亂尤其是 script 生成的代碼后面交給格式化器統(tǒng)一收尾效果最好。反過(guò)來(lái)如果把 prettier 放在 t3code 之前規(guī)則里的正則可能被格式化后的換行、縮進(jìn)干擾導(dǎo)致匹配不中。這個(gè)順序經(jīng)驗(yàn)值得記下來(lái)。7. 我在 t3code 上踩過(guò)的坑與幾條重要心得最后這部分是我真正希望小白看到的——這些都寫在官方文檔之外來(lái)自我搬磚過(guò)程中的真實(shí)教訓(xùn)。7.1 正則貪婪匹配導(dǎo)致的大面積誤傷第一次用正則做替換時(shí)我寫過(guò)一個(gè).*目標(biāo)是匹配引號(hào)里的內(nèi)容結(jié)果它貪婪地一路吞到文件最后。plan 階段的 diff 顯示“改前是 3 行改后成了 40 行”我才意識(shí)到問(wèn)題。后來(lái)我養(yǎng)成了兩個(gè)習(xí)慣能不用.*就不用要匹配一段穩(wěn)定結(jié)構(gòu)一定用非貪婪寫法.*?或者干脆用更精確的字符類[^]*;每次改完正則必須把 plan 輸出的 diff 從頭到尾過(guò)一遍重點(diǎn)看“不該變的上下文有沒有被動(dòng)過(guò)”。7.2 別忘了 JavaScript 正則的轉(zhuǎn)義因?yàn)橐?guī)則文件的運(yùn)行環(huán)境是 JavaScript 正則引擎寫規(guī)則時(shí)\d、\s、\w這些元字符在 YAML 里通常不需要額外轉(zhuǎn)義但如果你要匹配反斜杠本身就得寫\\\\。這個(gè)細(xì)節(jié)看著小實(shí)際寫錯(cuò)后的報(bào)錯(cuò)信息又不夠直觀非常浪費(fèi)時(shí)間。我的對(duì)策是先在本地用 Node 的 REPL 試好正則再粘進(jìn)規(guī)則文件不要直接在 YAML 里猜。7.3 大倉(cāng)庫(kù)掃描性能優(yōu)化幾萬(wàn)文件的倉(cāng)庫(kù)掃描過(guò)程可能非常慢。t3code 支持.t3ignore文件語(yǔ)法類似.gitignore寫入后可以跳過(guò)大量無(wú)需掃描的目錄。我用它排除了vendor/、third_party/這類目錄掃描時(shí)間從 40 秒降到 4 秒。如果你的倉(cāng)庫(kù)也有巨型第三方依賴目錄強(qiáng)烈建議配一個(gè).t3ignore。7.4 規(guī)則文件加注釋是給未來(lái)的自己看的YAML 支持注釋我鼓勵(lì)在每條規(guī)則上方寫清楚“為什么會(huì)有這條規(guī)則、來(lái)源是哪個(gè) jira/issue、執(zhí)行批次歸屬”例如# JIRA-2048: 2024-06 依賴 deprecation統(tǒng)一遷移到 new-lib # 執(zhí)行批次sprint-3 - name: migrate-old-lib ...原因很簡(jiǎn)單三個(gè)月后你回來(lái)看規(guī)則文件如果沒有注釋你根本想不起來(lái)這條規(guī)則是干嘛的、能不能刪。有了注釋維護(hù)成本低一個(gè)量級(jí)。7.5 我的一個(gè)“理想化”但很實(shí)用的期望個(gè)人使用中我特別希望 t3code 后續(xù)能加一個(gè)“規(guī)則模板市場(chǎng)”式的東西常見遷移場(chǎng)景如 React 更新、Webpack 換 Vite、Jest 版本升級(jí)有人整理好模板規(guī)則其他人直接拉下來(lái)適配即可。工具本身好用但如果社區(qū)生態(tài)更豐富能讓更多人少踩我踩過(guò)的坑。目前沒有的情況下我自己的做法是把常用規(guī)則按“遷移類型”分文件夾管理需要時(shí)復(fù)制到項(xiàng)目里改改 scope 就行也算是一個(gè)輕量級(jí)的“個(gè)人模板庫(kù)”。最后說(shuō)一個(gè)小技巧把 t3code.yml 和審計(jì)報(bào)告當(dāng)成項(xiàng)目文檔的一部分來(lái)維護(hù)。每次批量替換都是項(xiàng)目演化史上的一次“手術(shù)”手術(shù)記錄留著后續(xù)排查問(wèn)題、回滾、復(fù)盤都有據(jù)可依。我現(xiàn)在的習(xí)慣是每完成一次遷移都把規(guī)則文件更新到最新狀態(tài)并在 README 里加一行說(shuō)明“當(dāng)前項(xiàng)目的批量替換規(guī)則在t3code.yml中維護(hù)新增一種替換場(chǎng)景請(qǐng)先更新規(guī)則文件”。這樣一來(lái)t3code 就不只是一個(gè)順手工具而是一件能長(zhǎng)期沉淀的團(tuán)隊(duì)資產(chǎn)。