我接手过一个很老的内部工程依赖包从deprecated-lib换成new-lib,光 import 路径就散在几十个文件里更别提还有一堆调用方法名必须跟着改。当时我第一反应是祭出sed一顿操作结果替换完之后编译直接炸了一半有的地方多替换了、有的地方漏了最尴尬的是改坏了还没法快速回滚只能靠 git diff 一行行找。后来我花了一个周末写了t3code——一个声明式的、可审计的批量代码替换与重构工具从那以后这类“全局替换”对我来说就从一个高风险动作变成了一条安全、可复现的流水线。这篇文章不聊空泛理念直接讲清楚 t3code 是什么、为什么需要它、规则文件怎么写、遇到哪些坑以及我把它塞进团队工程流程里的完整经验。1. 从一次差点翻车的全局替换说起t3code 的诞生背景先还原一下当时的场景。那个项目是个典型的历史包袱工程核心模块从老框架迁移到新框架依赖包名变了一套工具类的方法前缀也从oldUtil_统一改成newUtil_。表面上看这就是个“查找替换”的活可真正动手才发现痛点全藏在细节里有些 import 是from deprecated-lib/foo有些是from deprecated-lib直接全局替换会把路径拼错方法名替换涉及字符串拼接的场景比如oldUtil_getName()在代码里有十多种写法有的带空格、有的带换行替换完必须验证“没有漏、没有多”单靠肉眼扫 diff 根本不现实最要命的是一旦替换完编译报错想回到替换前只能靠git checkout,如果中间还混了手动改动那就彻底乱了。我的需求逐渐清晰我希望有一个工具能把“我要把什么改成什么”写成一份人类可读的声明式文件然后它负责扫描、替换、留备份、给审计报告还能反复执行不重复污染。t3code 就是这么来的。它本质上是一个命令行工具核心能力概括成一句话按照规则文件在保留原始文件备份的前提下对目标目录下的代码进行精准的字符串替换、命名重写和模板化内容生成。它不是万能的也不打算替代编译器做静态分析但它能把你从“批量替换翻车”这个泥潭里拉出来。如果你和我一样经常要处理依赖升级、API 迁移、工程脚手架初始化这类场景或者你想把“代码批量替换”这件事变成一个可提交到仓库、可供团队复用的动作那 t3code 很适合你。如果你只是偶尔改两三个文件那用编辑器自带的全局搜索替换就够了不必上这个工具——这一点后面会展开说。2. 工具定位与设计取舍它到底解决哪一类问题t3code 解决的核心问题不是“换字符串”而是“让批量替换这个动作变得可控、可审计、可回滚、可重复”。它不是天生地义的任务而是有明显适用边界的工具。理解这个边界比会写规则文件更重要。2.1 和 sed / perl 对比声明式规则 vs 一行流以前做全局替换最常见的方案是sed -i或者perl -pi -e。这俩强大是真强大问题也真不少命令一长基本没人看得懂写的时候图快执行完了追悔莫及而且同样一段命令在这台机器上有效到另一台机器上遇到不同编码、换行符直接就翻车。t3code 把“替换动作”提升为“规则”。一条规则包含四个核心要素目标范围scope、匹配模式match、替换内容write或脚本script、执行的配置文件。规则用 YAML 写任何人打开就能看懂“要改什么、改成什么”。例如同样是把某个依赖包改名sed 命令行是一串难以阅读的正则t3code 的规则文件则是这样一段语义化结构rules: - name: migrate-dependency-path scope: include: [src/**/*.{js,ts}] replace: - from: deprecated-lib/foo to: new-lib/bar语义清晰、可 diff、可 review。这对我来说是本质区别sed 是“一个动作”t3code 是“一份可维护的配置”。2.2 和 IDE 全局替换对比从本机行为变成团队资产IDE 的全局替换也很好用但它绑定在人身上我在自己编辑器里换完了同事不知道CI 也不知道新来的同事拿着老代码还是会踩一遍同样的坑。而且 IDE 的替换往往是“一次性动作”缺少“持续应用”的能力。t3code 的规则文件是独立存在的可以和代码一起进 Git 仓库。团队里任何人想执行同样一套迁移只需跑t3 run --profile rc-2024结果一致日志一致且失败时有据可查。它把“个人本机操作”变成了“团队工程资产”这是我把它定位成“工具链成员”而非“编辑器插件替代品”的原因。2.3 t3code 不擅长什么边界要提前讲清楚得泼一盆冷水t3code 不是代码理解工具它不懂语法树也不会帮你判断替换后是否逻辑等价。它擅长的是“文本层面的、规则明确的”替换。比如依赖包路径统一迁移适合函数调用点批量改名不带括号解析适合脚手架模板变量渲染适合需要理解“这个函数是否被重载、调用参数是否需要同步变化”的深层次重构不适合。那种场景应该去用 jscodeshift、CocoaPods 之类的 AST 级工具或者干脆交给 IDE 的语言服务。t3code 的目标是覆盖“中间地带”文本层面有规律、人工改容易漏、又不想上重型工具的那部分需求。承认边界反而让它在自己的领域里更可信。3. 上手前的准备与第一个规则文件五分钟跑通这一节直接动手。我用一个最简单的示例带你跑通 t3code 的整体路径安装、写规则、预览、执行、审计。3.1 安装与初始化t3code 是单二进制文件没有运行时依赖。我常用的两种安装方式# 方式一brew 安装macOS 或 Linux brew install t3code/tap/t3code # 方式二直接下载 release 二进制 curl -sSL https://example.com/t3code/releases/latest/t3code-linux-amd64.tar.gz | tar -xz sudo mv t3code /usr/local/bin/安装完先确认版本顺便看帮助信息t3code --version t3code --help初始化会在当前目录生成一个空的t3code.yml和.t3code/工作目录用来放备份和日志t3 init执行完之后目录结构如下. ├── t3code.yml # 规则与配置文件 └── .t3code/ # 本地工作目录备份、日志、审计报告3.2 规则文件基础结构T3file.yml 的核心配置项我习惯把规则文件命名为t3code.yml但名字不是强制的-f参数可以指定任意路径。一个典型的初版配置长这样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说几个关键点version: 1规则文件格式版本目前只有 1保留它主要是为了未来兼容profiles一组规则的有序集合。这个设计解决的是“不同批次迁移要分开执行”的问题——你可以把第一阶段的规则叫rc-2024,第二阶段叫sprint-3按需 run 指定 profilescope执行范围include/exclude用 glob 匹配支持**和{}。强烈建议第一个版本就写明排除node_modules、dist、.git不然扫描会痛苦地卡住replace.from/to支持字符串也支持正则正则写法对标 JavaScript 的 RegExp替换引用用\1、\2。一个 rule 的名字是全局唯一的后续审计、回滚都会用它作为定位标识命名建议带业务语义比如migrate-old-lib就比rule1好一万倍。3.3 第一次执行dry-run、plan、run、audit新手最容易犯的错误是拿起来就执行run,结果一发不可收拾。t3code 提供了串行链路我强烈建议第一次跑时按这条链路走# 第一步只扫描不改文件输出将会命中的所有文件清单 t3 scan --profile default # 第二步在内存里做替换输出详细 diff 但不写盘 t3 plan --profile default # 第三步确认无误后执行真实替换 t3 run --profile default # 第四步生成审计报告能看到每个文件被哪条规则改了多少处 t3 audit --profile defaultscan和plan的区别要搞清楚scan只是告诉你“有哪些文件会被扫到”plan是实际跑一遍替换逻辑把“改前 vs 改后”的 diff 展示给你看。我实际使用中80% 的问题在plan阶段就会被发现——比如某条正则把不该改的配置也匹配了这时直接微调规则就行不会污染代码。run执行时每个被修改的文件都会自动在.t3code/backups/下生成一份原始副本备份按时间戳/文件相对路径归档。这就是后面revert的底气。3.4 用表格快速理解五个常用子命令命令作用会不会写文件什么时候用t3 init初始化目录和工作区会创建配置文件首次接入项目t3 scan扫描命中范围否快速确认影响面t3 plan预览替换 diff否每次执行前必跑t3 run执行规则替换是含备份确认无误后t3 audit输出审计报告否写日志事后核对、留下记录第一次跑通这套链路你对 t3code 的信任感会很快建立起来因为你每一次真实改动之前工具都先给了你“后悔药”和“体检报告”。4. 四个真实案例从简单替换到跨文件重构光看配置结构不够我用四个真实场景证明 t3code 的覆盖力。这四段并不是虚构而是我在不同阶段验证过的典型用法。4.1 案例 A依赖包路径批量迁移这是最基础也最经典的用法。项目里所有from old-lib要改成from new-lib,但old-lib/foo这类子路径也必须对应迁移不能只替换前缀。规则文件这样写rules: - name: migrate-lib-root scope: include: [src/**/*.js] replace: - from: old-lib to: new-lib这里的小技巧是我把匹配锚定在单引号之后而不是简单匹配old-lib全局。为什么因为代码里可能出现const oldLib something这种驼峰变量名或者注释里的提到old-lib,如果直接from: old-lib就会误杀。加一个前导引号让规则只命中真正的 import 路径场景。执行前再用plan检查一遍 diff确认没有动到注释和变量。4.2 案例 B旧 API 向新 API 迁移这次不是单对单的替换而是带“参数变换”的迁移。旧 API 是util.getUser(id, { withPosts: true }),新 API 改成userApi.fetch(id, { include: [posts] })。纯字符串替换做不了这种改变,但 t3code 的脚本项可以。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 函数体入参是orig原始完整匹配和captures捕获组数组返回值就是替换结果。这里能跑任意 JS 逻辑所以像“参数顺序调整”“布尔参数转数组参数”都能实现。执行效果// 改前 const data util.getUser(42, { withPosts: true }); // 改后 const data userApi.fetch(42, { include: [posts] });需要提醒的是script 虽然灵活但可读性会下降而且里面一旦有 bug影响面也大。我的经验是——能用静态replace的尽量用静态 replacescript 留给“确实要动逻辑结构”的场景。4.3 案例 C工程脚手架变量渲染t3code 另一个让我惊喜的场景是脚手架变量替换。以前写项目模板会留着__PROJECT_NAME__这种占位符新项目拉下来以后手动替换替换漏了就盯着编译错误一个个找。t3code 把这件事也自动化了。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 功能还能做更复杂的文件模板——比如根据参数生成 README 片段。核心思路没变所有模板占位符的替换规则都沉淀在 t3code.yml 里而不是靠人肉记忆。4.4 案例 D多阶段重构策略大型重构通常不是一次替换就能完成的。我习惯给每个阶段建一个 profile然后逐个执行profiles: phase-1: rules: [rename-imports] phase-2: rules: [rename-imports, migrate-api-calls] phase-3: rules: [rename-imports, migrate-api-calls, cleanup-comments]这样有几个好处每个阶段的审计报告是独立的git 提交历史可以和阶段一一对应出问题时能精准定位“是哪个阶段、哪条规则改坏的”团队评审时也可以按 profile 分批看 diff而不是一次性交一个巨型改动。5. 干了再说的代价回滚、审计与执行保护机制批量替换最让人紧张的就是“改坏了怎么办”。这一节专门讲 t3code 在安全层面做的设计以及我实际用下来的注意事项。5.1 默认备份每次执行都有后悔药前面提到t3 run会自动备份备份目录结构如下.t3code/backups/ └── 2024-06-17T14-30-22/ ├── src/utils/api.js ├── src/components/UserCard.js └── manifest.json恢复单个文件cp .t3code/backups/2024-06-17T14-30-22/src/utils/api.js src/utils/api.js如果是想恢复一整次执行# 列出所有备份时间点 t3 backups # 恢复到指定时间点 t3 revert --backup-id 2024-06-17T14-30-22 --target src/注意revert的行为是“用备份文件覆盖回当前对应路径”它会假设你当前目录结构和备份时一致。如果中间你手动新增了文件新增文件不会被删除——这是有意的保守设计回滚只管“被改过的文件”不负责“替你删除新变量”。5.2 审计日志不只是给自己看也是给团队看的每次执行之后审计报告在.t3code/logs/下生成内容包括执行时间、执行的 profile、命中的规则列表 每个文件被哪条规则命中、替换了几处 是否有跳过文件比如二进制、超限大文件 警告信息如“替换后的内容与备份完全一致可能是正则没生效”。我前阵子做一次跨模块迁移改完后同事想 review想知道“到底动了哪些地方”我直接把审计报告贴到 PR 描述里人家不用翻几百个 diff 文件就能看到影响面。这个习惯后来成了团队规范——凡是 t3code 产生的批量改动PR 里必须附审计报告。5.3 执行保护scope 与 ignore 的合理配置执行保护分为三层每一层都能有效避免“瞎改一通”第一层是scope.exclude把不该碰的目录和文件排除掉。下面这个配置算是我的最低安全配置scope: include: [src/**/*.{js,ts,jsx,tsx}] exclude: - **/node_modules/** - **/dist/** - **/build/** - **/.git/** - **/*.min.js第二层是规则内的files限定。有些规则只想作用于特定文件可以在 rule 内单独声明files覆盖全局 scoperules: - name: update-api-config files: [config/**/*.{json,ts}] replace: - from: apiVersion: 1 to: apiVersion: 2第三层是--dry-run标志。run命令自带--dry-run参数就算你不小心直接执行 run也会因为 dry-run 默认开启而只输出预览不真正改文件。我是建议把它当成默认习惯run总是先带--dry-run看一遍再不带参数执行真正的写入。5.4 编码与二进制文件的坑t3code 默认只处理文本文件遇到 NUL 字节会跳过。但文本文件也有编码差异最常踩的是 BOM带 BOM 的 UTF-8 文件在匹配时首行开头会多一个\uFEFF如果你的正则锚定^from匹配会失败。我的对策是规则里尽量用contains而不是行首锚定或者先跑一次t3 scan --encoding-check摸清文件编码分布。换行符也是一个坑。同仓库里混着LF和CRLF是祖传常态替换时如果to里写死了\n,在 CRLF 文件里会导致混行换行符。我一般先t3 audit --line-endings看看分布再决定规则里要不要兼容\r?\n。6. 集成到团队工程流程中CI 检查与 git hookst3code 的价值如果只停留在个人工具层面还是有点可惜。真正放大它价值的场景是把它嵌进工程流程让“批量替换”从一次性的手工操作变成自动化、可强制执行的环节。6.1 CI 里的“规则即测试”模式t3code 内置--check参数执行后不写入文件只检查“当前代码状态是否符合规则期望”——简单理解就是如果规则要求old-lib应该被替换成new-lib,--check检测到还有old-lib存在就会以非零状态退出。CI 里加一步# .github/workflows/code-quality.yml jobs: t3-check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: t3 run --check --profile default这一步的作用是一旦有人把旧依赖路径又写回代码CI 会直接红掉提示他用 t3code 规则修复。这比 eslint 的某些规则更直接因为它是完全基于团队自定义配置的。我实际用下来这类“防回潮检查”特别适合代码库体量大、历史包袱重的项目——防止老问题死灰复燃。6.2 配合 pre-commit提交前就能拦截如果你不想把所有检查都放到 CI毕竟 CI 反馈周期长可以本地 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很关键因为 t3code 的规则是面向全仓库的不需要 pre-commit 传单文件列表。有了这道防线开发者提交前就知道自己的改动有没有逆着规则走不用等 CI 跑完再回炉。6.3 规则文件版本管理把规则当代码一样对待t3code.yml 和其他源码一样放 Git 仓库每次调整规则都要走正常的 code review 流程。我吃过一次亏直接在测试分支上改规则文件乱跑结果规则里写错了一个字batch 替换了不该动的地方。后来立了一条规矩规则文件的改动必须独立提交且要附上 plan 阶段的 diff 示例这样 reviewer 可以直观看到新规则会改什么、会不会误伤。另外规则文件的版本号可以对应项目里程碑。比如项目里同时存在profile-sprint-1、profile-sprint-2,历史提交时想复盘某个批次改动直接按 profile 名搜审计日志就行。6.4 与 eslint/prettier 的配合先 t3code 再格式化我实际流程里通常先跑 t3code 做结构和依赖路径的批改再跑 prettier/eslint 统一风格。顺序不能反因为 t3code 做的是语义级文本替换替换完的格式可能比较凌乱尤其是 script 生成的代码后面交给格式化器统一收尾效果最好。反过来如果把 prettier 放在 t3code 之前规则里的正则可能被格式化后的换行、缩进干扰导致匹配不中。这个顺序经验值得记下来。7. 我在 t3code 上踩过的坑与几条重要心得最后这部分是我真正希望小白看到的——这些都写在官方文档之外来自我搬砖过程中的真实教训。7.1 正则贪婪匹配导致的大面积误伤第一次用正则做替换时我写过一个.*目标是匹配引号里的内容结果它贪婪地一路吞到文件最后。plan 阶段的 diff 显示“改前是 3 行改后成了 40 行”我才意识到问题。后来我养成了两个习惯能不用.*就不用要匹配一段稳定结构一定用非贪婪写法.*?或者干脆用更精确的字符类[^]*;每次改完正则必须把 plan 输出的 diff 从头到尾过一遍重点看“不该变的上下文有没有被动过”。7.2 别忘了 JavaScript 正则的转义因为规则文件的运行环境是 JavaScript 正则引擎写规则时\d、\s、\w这些元字符在 YAML 里通常不需要额外转义但如果你要匹配反斜杠本身就得写\\\\。这个细节看着小实际写错后的报错信息又不够直观非常浪费时间。我的对策是先在本地用 Node 的 REPL 试好正则再粘进规则文件不要直接在 YAML 里猜。7.3 大仓库扫描性能优化几万文件的仓库扫描过程可能非常慢。t3code 支持.t3ignore文件语法类似.gitignore写入后可以跳过大量无需扫描的目录。我用它排除了vendor/、third_party/这类目录扫描时间从 40 秒降到 4 秒。如果你的仓库也有巨型第三方依赖目录强烈建议配一个.t3ignore。7.4 规则文件加注释是给未来的自己看的YAML 支持注释我鼓励在每条规则上方写清楚“为什么会有这条规则、来源是哪个 jira/issue、执行批次归属”例如# JIRA-2048: 2024-06 依赖 deprecation统一迁移到 new-lib # 执行批次sprint-3 - name: migrate-old-lib ...原因很简单三个月后你回来看规则文件如果没有注释你根本想不起来这条规则是干嘛的、能不能删。有了注释维护成本低一个量级。7.5 我的一个“理想化”但很实用的期望个人使用中我特别希望 t3code 后续能加一个“规则模板市场”式的东西常见迁移场景如 React 更新、Webpack 换 Vite、Jest 版本升级有人整理好模板规则其他人直接拉下来适配即可。工具本身好用但如果社区生态更丰富能让更多人少踩我踩过的坑。目前没有的情况下我自己的做法是把常用规则按“迁移类型”分文件夹管理需要时复制到项目里改改 scope 就行也算是一个轻量级的“个人模板库”。最后说一个小技巧把 t3code.yml 和审计报告当成项目文档的一部分来维护。每次批量替换都是项目演化史上的一次“手术”手术记录留着后续排查问题、回滚、复盘都有据可依。我现在的习惯是每完成一次迁移都把规则文件更新到最新状态并在 README 里加一行说明“当前项目的批量替换规则在t3code.yml中维护新增一种替换场景请先更新规则文件”。这样一来t3code 就不只是一个顺手工具而是一件能长期沉淀的团队资产。