t3code 这个名字看起来像是某个开源项目的代号其实是我自己内部用了快两年的代码质量管控方案代号。以前我们团队经常出现这种场景功能开发完本地跑一遍没问题代码 review 也只是看看逻辑对不对结果合进主干后老代码被新代码变量名冲突搞挂或者某个 API 参数类型对不上线上报错后才手忙脚乱地回滚。t3code 就是为解决这种能跑但不敢保证稳定的问题而生。它不是框架也不是某个具体工具而是一套三层代码质量关卡Lint 静态检查、Typecheck 类型检查、Test 自动测试从前到后把问题拦截在进入主干之前。名字里的 T3 是 Tools、Typecheck、Test 的缩写叫顺口了就留下来了。这套思路适合正在带前端或 Node 小团队的技术负责人也适合想给个人项目建立质量门禁的独立开发者。如果你们团队的代码 review 还在靠人肉盯语法和低级错误那这套方案能把你从重复劳动里捞出来。1. t3code 到底解决什么问题1.1 名字的由来和定位先解释一下名字。T3 不是三体是我图省事把三个英文单词拼到一起Tools工具链、Typecheck类型检查、Test测试。为什么要拼成一个代号因为如果直接说“咱们要搞三层质量门禁”团队听起来像在听理论课但如果说“t3code”好像是一个已经存在的最佳实践大家下意识会觉得这个事情是有标准打法的配合度会高不少。这是个心理层面的小技巧实际用下来确实比抽象概念好推。定位也很简单它把代码问题的发现时机从“人肉 review 阶段”提前到“机器自动检查阶段”。代码提交前的五分钟lint 先扫一遍风格和低级错误类型检查再看一遍接口契约有没有被破坏最后测试把核心行为跑一遍。三层都过了才允许提交和合并。如果某层没过机器直接给出报错不需要 reviewer 手动指出来。这其实解决了一个被很多团队忽略的问题reviewer 的精力是有限的与其花在看缩进、变量命名、有没有 console.log 上不如把时间留给真正的逻辑评审和架构讨论。1.2 三层关卡的核心逻辑这三层的排序不是拍脑袋定的而是按“修复成本从低到高”排的。Lint 发现的问题基本在代码编辑器里就能改成本是分钟级的类型检查发现的问题说明接口契约被打破可能要改调用方成本是小时级的测试失败说明行为发生了变化可能需要重新设计用例、排查业务逻辑成本是小时到天级的。换句话说越早发现的问题修起来越便宜所以三道门禁必须按照从快到慢的反馈顺序来设计。这里有个常见的误解以为三层检查是“重复的”Lint 管风格、类型管契约、测试管行为三者完全正交。但实际上它们会互相补充Lint 能抓到的“未使用变量”“条件判断恒为真”这类问题类型检查并不关心类型检查能暴露的“参数结构传错”“返回类型不符”Lint 又完全无感测试则是把前面两层判定为“合法”的代码真正跑起来验证它们在运行时的行为是否符合预期。三层共同构成一道完整防线缺任何一个都容易出现盲区。我自己实测下来把这三层全部打开之后线上低级故障的比例降得非常明显而且是肉眼可见的那种下降不是玄学。2. 关键决策每一层用什么、怎么配2.1 第一层静态检查用什么规则怎么取舍先说第一层静态检查。以 JS/TS 生态为例我一般选 ESLint不推荐自己从零堆规则。ESLint 自带的 recommended 规则集是一个底线覆盖了未定义变量、未使用表达式、隐式类型转换等高频问题。但只用 recommended 还不够它更像一床被子能保暖但不合身。我实际做 t3code 的时候会在 recommended 基础上追加三组自定义规则第一组是“警示升级为错误”的规则比如 no-undef、no-unused-vars。把这类规则从 warn 改成 error配合--max-warnings 0参数让任何警告都无法蒙混过关。因为团队的实践里警告往往被忽略只有 error 才能挡住合并按钮。第二组是“代码味道”规则比如no-console、no-debugger。我一开始不把 console 完全禁掉而是允许在脚本里显式写一个别名函数比如通过debugLog统一封装。这样既能防止生产代码里到处是调试日志又不至于在排查问题时连日志都没法加。第三组是“边界约束”规则比如限制函数复杂度max-params、禁止空函数no-empty-function。这一类规则不用全开但要挑团队最容易出现问题的几个方向。我见过不少团队在这部分翻车规则开得太多太激进老代码无处可逃最后只能被迫加 ignore 注释反而破坏了规则的权威性。所以第一层的核心取舍是开得动、查得准、不会误伤。宁可少开 20 条规则也不要让团队养成“随手 ignore”的习惯。2.2 第二层接口与类型契约的严格度第二层是最容易被低估的。很多人以为 TypeScript 开了strict就万事大吉实际上远不够。t3code 对类型层的配置我建议至少做到三件事一是开启strict: true。这是 TypeScript 的核心严格开关它把strictNullChecks、noImplicitAny、noUncheckedIndexedAccess等一批关键检查全部打开让空指针、隐式 any、越界索引这些最经典的运行时隐患在编译期就被暴露。如果团队历史包袱重可以先只开strict: true等代码逐步改造完再把noUncheckedIndexedAccess也打开。二是开启noImplicitOverride。这个规则要求子类覆盖父类方法时必须显式写override关键字。它的价值在于当父类方法被删除或签名改变时子类的方法不会被“静默地”当成新方法从而避免一系列隐蔽的继承错误。这个规则在团队里可能引发一轮改动但收益非常明确——重构时敢放心改父类了。三是配置“类型严格但入口放松”。我见过很多项目为了接入 t3code把全量类型检查一次性打开结果几十个历史文件全报错根本改不完。更务实的做法是新代码默认严格老代码通过// ts-expect-error或文件级白名单过渡。但白名单必须是“按文件、按行”的绝不能直接.eslintrc里把整个目录 ignore 掉。白名单只用于存量债务不接纳新增问题这是类型检查能长期坚持下来的关键。2.3 第三层测试策略与覆盖率说是第三层我把它放在提交前最后一道。测试我推荐 Vitest Testing Library 的组合原因是 Vitest 对 TypeScript 和 ESM 的支持很自然跑起来速度也比老一代测试框架快不少。不过框架只是工具真正重要的是测试策略。t3code 对测试的定义是“关键行为验证”不是“指标刷分”。我见过很多人在覆盖率上死磕非要 90% 以上结果团队把大量时间花在给 getter/setter 补测试上业务核心却一层覆盖都没有。更合理的做法是把模块分成三类业务核心模块、普通业务模块、基础设施模块。业务核心模块要求覆盖率必须达到 80% 以上普通业务模块不设硬性指标但至少要有冒烟测试基础设施模块只做关键路径验证。另外我还要强调一个被大家忽视的点测试不仅是跑通还要跑得稳定。t3code 里我专门约定测试中禁止使用真实网络请求和真实数据库连接一律走 mock。因为真实依赖会导致“本地能过、CI 挂掉”的经典问题。维护一套时间稳定的测试比维护一套覆盖率高的测试更重要。测试不稳定团队就会慢慢失去对门禁的信任最后连提交都不愿意跑测试了。3. 从零落地 t3code 的完整步骤3.1 初始化项目与脚本编排很多人拿到这类方案第一个疑问是从哪开始我推荐一条很直接的路全部从 package.json 的 scripts 开始。先不用接 CI也不用建一堆配置文件第一步是把三层命令固化下来。以 Node 项目为例scripts 大概长这样{ scripts: { lint: eslint . --max-warnings 0 --ext .ts,.tsx,.js,.jsx, typecheck: tsc --noEmit, test: vitest run, check: npm run lint npm run typecheck npm run test } }这里关键是check脚本。它把三层命令用串起来保证按顺序执行一旦前面某层报错后面直接不跑。这条聚合命令就是 t3code 在本地环境里的入口团队成员开发完只需要敲npm run check机器就会按顺序把三层检查跑完。刚开始推这个方案的时候有同事问我既然有 lint-staged为什么还要全量跑我的回答很简单全量脚本是为了兼容各种不熟悉灵活的开发者保证“谁都能跑”lint-staged 是性能增强保证“跑得快”。两者不冲突先有全量再谈增量。如果一开始就只想走 git diff 增量检查反而容易因为漏掉某些文件留下死角。3.2 门禁接入pre-commit 和 CI本地脚本跑完之后下一步是把门禁接到 git 钩子和 CI 上。本地钩子我用 husky lint-staged目的是让改动只差一步时就能拿到快速反馈不用等全量检查。lint-staged 的配置大致如下lint-staged: { *.{ts,tsx,js,jsx}: [eslint --max-warnings 0, prettier --write] }这段配置的意思是提交时只对暂存区的文件做 ESLint 和格式化。这样本地反馈在毫秒级不会因为全量检查太慢而让团队想绕过钩子。注意我把 prettier 放在这里而不是单独开一个 pre-commit 任务是因为格式化放在 lint-staged 里天然只处理本次改动的文件避免误格式化其他文件造成无意义 diff。CI 这边我用的是 GitLab CI配置里核心跑三段 joblint、typecheck、test。三者之间不串行可以并行跑节省总耗时。有一点要实现重点提醒CI 里的命令必须和本地npm run check保持一致否则会出现“本地能过、CI 挂掉”的尴尬。我的做法是CI 里直接复用 package.json 的脚本而不是在 CI 配置里重新敲一遍等价命令。这样规则只有一份修改时只改一处不会漂移。3.3 常用参数说明与取舍表很多人在落地 t3code 时会被各种配置参数劝退其实需要调的参数没有想象中那么多。我整理了一张核心参数表这也是我入团队培训时第一发给新人的表格层级关键工具核心参数作用建议值静态检查ESLintmax-warnings警告数上限0静态检查ESLintno-console禁止调试日志漏网error类型检查TypeScriptstrict开启严格空值/隐式any检查true类型检查TypeScriptnoImplicitOverride显式覆盖标注true行为验证VitesttestTimeout单测超时上限10000 ms行为验证Vitestcoverage.threshold核心模块覆盖率下限80这些参数看着小但每一格背后都有一个真实踩坑故事。比如max-warnings设成 0很多人觉得太苛刻实际上它换来的是“零告警”的代码库状态告警为零后新增告警一出现就会被拦下。又比如noImplicitOverride我第一次开的时候团队里报了几十个错全是历史代码里“同名覆盖父类但没写 override”的情况。当时咬着牙改完了后续重构父类就再没出过静默覆盖的问题。参数建议值都是基于真实环境校准的不是拍脑袋照着配基本能跑得动。4. 我在接入 t3code 时踩过的坑4.1 排查实录与解决方案接入方案的过程中遇到最多的问题不是原理不理解而是各种莫名其妙的环境问题。我把最典型的几个记录在下面就当是给大家的避坑手册。第一个坑是 ESLint 版本冲突。我们项目里有个老包依赖了旧版 ESLint结果跑eslint .时报了一堆“Config List Error”。排查到最后发现是 ESLint 8 和 ESLint 9 的配置格式不兼容插件用的是 9 的配置却被老包拖回了 8 的解析模式。后来团队统一锁定 ESLint 版本并在根目录放.nvmrc锁定 Node 版本问题才消失。这类问题很隐蔽因为报错信息根本不会提示“版本不兼容”只会说“无法解析某文件”。第二个坑是 lint-staged 配置不生效。现象是修改文件后 git commit钩子没有跑 ESLint。排查半天发现是.husky/pre-commit里面 command 写错了写成了npx lint-staged但 husky 的 pre-commit 文件在 Windows 上因权限问题没有执行权限。修法是把 pre-commit 内容改成npx lint-staged --allow-empty并给 husky 钩子文件手动加上执行权限。这个坑在 Mac 上很少见在 Windows 上几乎必现大家留意。第三个坑是类型检查太慢导致npm run check时间飙到两分钟以上。原因是tsc --noEmit没有开启增量编译每次都是全量检查。后来我在 typecheck 脚本里加了--incremental --tsBuildInfoFile node_modules/.tmp/.tsbuildinfo第二次开始快了一倍多。需要注意的是tsc开启增量编译后会生成 .tsbuildinfo 文件这个文件必须加进 .gitignore否则会污染 git 仓库。我当时就漏了提交记录里多了一堆无意义的二进制变化。4.2 容易被忽略的细节清单除了上面的报错型问题还有一些细节是我在多次接入后总结出来的不容易一眼发现问题但长期下来很影响体验。第一点是 .gitignore 和 .eslintignore 不要混用。很多人只在 .gitignore 里配了dist、node_modules以为 ESLint 也会自动跳过。实际上 ESLint 默认只忽略 node_modulesdist 目录它照样扫。结果就是每次全量 lint 从 dist 目录里报了满屏错误。解决方法是单独配置.eslintignore或者更优雅的做法是在 ESLint 配置里写ignores: [**/dist/**, **/node_modules/**]。这一点如果不管会让团队觉得 t3code 很蠢明明产物目录还要查它。第二点是 Windows 下的路径分隔符问题。ESLint 和 lint-staged 在 Unix 上一切都好但在 Windows 下偶尔会遇到 glob 模式因为\和/混用导致匹配不上文件。我的建议是如果团队里有 Windows 开发者尽量让所有 glob 都用*.{ts,tsx}这种相对通用写法不要写src/**/*这种其实在部分环境下会被正确展开的复合路径。写死了路径格式可以省掉大量环境差异问题。第三点是 CI 与本地要共用同一份 lock 文件。如果 CI 里安装依赖时不带 lock 文件那每次安装的依赖版本都可能不同最终导致本地通过、CI 失败的“灵异事件”。这个问题在 npm 上尤其明显因为npm install和npm ci的解析策略不一样。我强烈建议 CI 里强制使用npm ci而不是npm install然后 package-lock.json 必须提交到仓库。我自己早期被这个问题坑了整整两个迭代周期后来才醒悟不是测试不稳定是依赖环境根本不在同一版本上。最后一点可能有点反直觉单测里不要过度 mock。t3code 的三层里测试用 mock 是为了稳定但 mock 过多会让测试变得无效因为它测的是“我们自己假装的实现”而不是真实代码。我见过一个模块测试里 mock 了三层对象全部跑通结果集成时一调线就挂因为真实对象之间的连接行为完全没被验证过。重点防线应该保持少量真实依赖只对网络、时间、外部 API 这类不可控因素做隔离。我个人在实际操作中有个体会t3code 这套方案能不能落地关键不在选什么工具而在规则串得顺不顺、反馈快不快。我刚开始推的时候也被人吐槽“跑一次 check 要两分钟太费时间”后来优化成增量编译 lint-staged 并行 CI 之后反馈基本控制在几秒内团队的抵触情绪一下就消了。如果你打算给自己的项目或团队接入这套思路一定要先保证本地反馈足够快再把门禁逐渐收紧。规则不是越严越好而是要在“能拦住问题”和“不打扰人”之间找到那个平衡点。t3code 只是这套三层思路的载体名字叫什么不重要里面的方法论才是真正能沉淀下来的东西。
t3code 这个名字看起来像是某个开源项目的代号其实是我自己内部用了快两年的代码质量管控方案代号。以前我们团队经常出现这种场景功能开发完本地跑一遍没问题代码 review 也只是看看逻辑对不对结果合进主干后老代码被新代码变量名冲突搞挂或者某个 API 参数类型对不上线上报错后才手忙脚乱地回滚。t3code 就是为解决这种能跑但不敢保证稳定的问题而生。它不是框架也不是某个具体工具而是一套三层代码质量关卡Lint 静态检查、Typecheck 类型检查、Test 自动测试从前到后把问题拦截在进入主干之前。名字里的 T3 是 Tools、Typecheck、Test 的缩写叫顺口了就留下来了。这套思路适合正在带前端或 Node 小团队的技术负责人也适合想给个人项目建立质量门禁的独立开发者。如果你们团队的代码 review 还在靠人肉盯语法和低级错误那这套方案能把你从重复劳动里捞出来。1. t3code 到底解决什么问题1.1 名字的由来和定位先解释一下名字。T3 不是三体是我图省事把三个英文单词拼到一起Tools工具链、Typecheck类型检查、Test测试。为什么要拼成一个代号因为如果直接说“咱们要搞三层质量门禁”团队听起来像在听理论课但如果说“t3code”好像是一个已经存在的最佳实践大家下意识会觉得这个事情是有标准打法的配合度会高不少。这是个心理层面的小技巧实际用下来确实比抽象概念好推。定位也很简单它把代码问题的发现时机从“人肉 review 阶段”提前到“机器自动检查阶段”。代码提交前的五分钟lint 先扫一遍风格和低级错误类型检查再看一遍接口契约有没有被破坏最后测试把核心行为跑一遍。三层都过了才允许提交和合并。如果某层没过机器直接给出报错不需要 reviewer 手动指出来。这其实解决了一个被很多团队忽略的问题reviewer 的精力是有限的与其花在看缩进、变量命名、有没有 console.log 上不如把时间留给真正的逻辑评审和架构讨论。1.2 三层关卡的核心逻辑这三层的排序不是拍脑袋定的而是按“修复成本从低到高”排的。Lint 发现的问题基本在代码编辑器里就能改成本是分钟级的类型检查发现的问题说明接口契约被打破可能要改调用方成本是小时级的测试失败说明行为发生了变化可能需要重新设计用例、排查业务逻辑成本是小时到天级的。换句话说越早发现的问题修起来越便宜所以三道门禁必须按照从快到慢的反馈顺序来设计。这里有个常见的误解以为三层检查是“重复的”Lint 管风格、类型管契约、测试管行为三者完全正交。但实际上它们会互相补充Lint 能抓到的“未使用变量”“条件判断恒为真”这类问题类型检查并不关心类型检查能暴露的“参数结构传错”“返回类型不符”Lint 又完全无感测试则是把前面两层判定为“合法”的代码真正跑起来验证它们在运行时的行为是否符合预期。三层共同构成一道完整防线缺任何一个都容易出现盲区。我自己实测下来把这三层全部打开之后线上低级故障的比例降得非常明显而且是肉眼可见的那种下降不是玄学。2. 关键决策每一层用什么、怎么配2.1 第一层静态检查用什么规则怎么取舍先说第一层静态检查。以 JS/TS 生态为例我一般选 ESLint不推荐自己从零堆规则。ESLint 自带的 recommended 规则集是一个底线覆盖了未定义变量、未使用表达式、隐式类型转换等高频问题。但只用 recommended 还不够它更像一床被子能保暖但不合身。我实际做 t3code 的时候会在 recommended 基础上追加三组自定义规则第一组是“警示升级为错误”的规则比如 no-undef、no-unused-vars。把这类规则从 warn 改成 error配合--max-warnings 0参数让任何警告都无法蒙混过关。因为团队的实践里警告往往被忽略只有 error 才能挡住合并按钮。第二组是“代码味道”规则比如no-console、no-debugger。我一开始不把 console 完全禁掉而是允许在脚本里显式写一个别名函数比如通过debugLog统一封装。这样既能防止生产代码里到处是调试日志又不至于在排查问题时连日志都没法加。第三组是“边界约束”规则比如限制函数复杂度max-params、禁止空函数no-empty-function。这一类规则不用全开但要挑团队最容易出现问题的几个方向。我见过不少团队在这部分翻车规则开得太多太激进老代码无处可逃最后只能被迫加 ignore 注释反而破坏了规则的权威性。所以第一层的核心取舍是开得动、查得准、不会误伤。宁可少开 20 条规则也不要让团队养成“随手 ignore”的习惯。2.2 第二层接口与类型契约的严格度第二层是最容易被低估的。很多人以为 TypeScript 开了strict就万事大吉实际上远不够。t3code 对类型层的配置我建议至少做到三件事一是开启strict: true。这是 TypeScript 的核心严格开关它把strictNullChecks、noImplicitAny、noUncheckedIndexedAccess等一批关键检查全部打开让空指针、隐式 any、越界索引这些最经典的运行时隐患在编译期就被暴露。如果团队历史包袱重可以先只开strict: true等代码逐步改造完再把noUncheckedIndexedAccess也打开。二是开启noImplicitOverride。这个规则要求子类覆盖父类方法时必须显式写override关键字。它的价值在于当父类方法被删除或签名改变时子类的方法不会被“静默地”当成新方法从而避免一系列隐蔽的继承错误。这个规则在团队里可能引发一轮改动但收益非常明确——重构时敢放心改父类了。三是配置“类型严格但入口放松”。我见过很多项目为了接入 t3code把全量类型检查一次性打开结果几十个历史文件全报错根本改不完。更务实的做法是新代码默认严格老代码通过// ts-expect-error或文件级白名单过渡。但白名单必须是“按文件、按行”的绝不能直接.eslintrc里把整个目录 ignore 掉。白名单只用于存量债务不接纳新增问题这是类型检查能长期坚持下来的关键。2.3 第三层测试策略与覆盖率说是第三层我把它放在提交前最后一道。测试我推荐 Vitest Testing Library 的组合原因是 Vitest 对 TypeScript 和 ESM 的支持很自然跑起来速度也比老一代测试框架快不少。不过框架只是工具真正重要的是测试策略。t3code 对测试的定义是“关键行为验证”不是“指标刷分”。我见过很多人在覆盖率上死磕非要 90% 以上结果团队把大量时间花在给 getter/setter 补测试上业务核心却一层覆盖都没有。更合理的做法是把模块分成三类业务核心模块、普通业务模块、基础设施模块。业务核心模块要求覆盖率必须达到 80% 以上普通业务模块不设硬性指标但至少要有冒烟测试基础设施模块只做关键路径验证。另外我还要强调一个被大家忽视的点测试不仅是跑通还要跑得稳定。t3code 里我专门约定测试中禁止使用真实网络请求和真实数据库连接一律走 mock。因为真实依赖会导致“本地能过、CI 挂掉”的经典问题。维护一套时间稳定的测试比维护一套覆盖率高的测试更重要。测试不稳定团队就会慢慢失去对门禁的信任最后连提交都不愿意跑测试了。3. 从零落地 t3code 的完整步骤3.1 初始化项目与脚本编排很多人拿到这类方案第一个疑问是从哪开始我推荐一条很直接的路全部从 package.json 的 scripts 开始。先不用接 CI也不用建一堆配置文件第一步是把三层命令固化下来。以 Node 项目为例scripts 大概长这样{ scripts: { lint: eslint . --max-warnings 0 --ext .ts,.tsx,.js,.jsx, typecheck: tsc --noEmit, test: vitest run, check: npm run lint npm run typecheck npm run test } }这里关键是check脚本。它把三层命令用串起来保证按顺序执行一旦前面某层报错后面直接不跑。这条聚合命令就是 t3code 在本地环境里的入口团队成员开发完只需要敲npm run check机器就会按顺序把三层检查跑完。刚开始推这个方案的时候有同事问我既然有 lint-staged为什么还要全量跑我的回答很简单全量脚本是为了兼容各种不熟悉灵活的开发者保证“谁都能跑”lint-staged 是性能增强保证“跑得快”。两者不冲突先有全量再谈增量。如果一开始就只想走 git diff 增量检查反而容易因为漏掉某些文件留下死角。3.2 门禁接入pre-commit 和 CI本地脚本跑完之后下一步是把门禁接到 git 钩子和 CI 上。本地钩子我用 husky lint-staged目的是让改动只差一步时就能拿到快速反馈不用等全量检查。lint-staged 的配置大致如下lint-staged: { *.{ts,tsx,js,jsx}: [eslint --max-warnings 0, prettier --write] }这段配置的意思是提交时只对暂存区的文件做 ESLint 和格式化。这样本地反馈在毫秒级不会因为全量检查太慢而让团队想绕过钩子。注意我把 prettier 放在这里而不是单独开一个 pre-commit 任务是因为格式化放在 lint-staged 里天然只处理本次改动的文件避免误格式化其他文件造成无意义 diff。CI 这边我用的是 GitLab CI配置里核心跑三段 joblint、typecheck、test。三者之间不串行可以并行跑节省总耗时。有一点要实现重点提醒CI 里的命令必须和本地npm run check保持一致否则会出现“本地能过、CI 挂掉”的尴尬。我的做法是CI 里直接复用 package.json 的脚本而不是在 CI 配置里重新敲一遍等价命令。这样规则只有一份修改时只改一处不会漂移。3.3 常用参数说明与取舍表很多人在落地 t3code 时会被各种配置参数劝退其实需要调的参数没有想象中那么多。我整理了一张核心参数表这也是我入团队培训时第一发给新人的表格层级关键工具核心参数作用建议值静态检查ESLintmax-warnings警告数上限0静态检查ESLintno-console禁止调试日志漏网error类型检查TypeScriptstrict开启严格空值/隐式any检查true类型检查TypeScriptnoImplicitOverride显式覆盖标注true行为验证VitesttestTimeout单测超时上限10000 ms行为验证Vitestcoverage.threshold核心模块覆盖率下限80这些参数看着小但每一格背后都有一个真实踩坑故事。比如max-warnings设成 0很多人觉得太苛刻实际上它换来的是“零告警”的代码库状态告警为零后新增告警一出现就会被拦下。又比如noImplicitOverride我第一次开的时候团队里报了几十个错全是历史代码里“同名覆盖父类但没写 override”的情况。当时咬着牙改完了后续重构父类就再没出过静默覆盖的问题。参数建议值都是基于真实环境校准的不是拍脑袋照着配基本能跑得动。4. 我在接入 t3code 时踩过的坑4.1 排查实录与解决方案接入方案的过程中遇到最多的问题不是原理不理解而是各种莫名其妙的环境问题。我把最典型的几个记录在下面就当是给大家的避坑手册。第一个坑是 ESLint 版本冲突。我们项目里有个老包依赖了旧版 ESLint结果跑eslint .时报了一堆“Config List Error”。排查到最后发现是 ESLint 8 和 ESLint 9 的配置格式不兼容插件用的是 9 的配置却被老包拖回了 8 的解析模式。后来团队统一锁定 ESLint 版本并在根目录放.nvmrc锁定 Node 版本问题才消失。这类问题很隐蔽因为报错信息根本不会提示“版本不兼容”只会说“无法解析某文件”。第二个坑是 lint-staged 配置不生效。现象是修改文件后 git commit钩子没有跑 ESLint。排查半天发现是.husky/pre-commit里面 command 写错了写成了npx lint-staged但 husky 的 pre-commit 文件在 Windows 上因权限问题没有执行权限。修法是把 pre-commit 内容改成npx lint-staged --allow-empty并给 husky 钩子文件手动加上执行权限。这个坑在 Mac 上很少见在 Windows 上几乎必现大家留意。第三个坑是类型检查太慢导致npm run check时间飙到两分钟以上。原因是tsc --noEmit没有开启增量编译每次都是全量检查。后来我在 typecheck 脚本里加了--incremental --tsBuildInfoFile node_modules/.tmp/.tsbuildinfo第二次开始快了一倍多。需要注意的是tsc开启增量编译后会生成 .tsbuildinfo 文件这个文件必须加进 .gitignore否则会污染 git 仓库。我当时就漏了提交记录里多了一堆无意义的二进制变化。4.2 容易被忽略的细节清单除了上面的报错型问题还有一些细节是我在多次接入后总结出来的不容易一眼发现问题但长期下来很影响体验。第一点是 .gitignore 和 .eslintignore 不要混用。很多人只在 .gitignore 里配了dist、node_modules以为 ESLint 也会自动跳过。实际上 ESLint 默认只忽略 node_modulesdist 目录它照样扫。结果就是每次全量 lint 从 dist 目录里报了满屏错误。解决方法是单独配置.eslintignore或者更优雅的做法是在 ESLint 配置里写ignores: [**/dist/**, **/node_modules/**]。这一点如果不管会让团队觉得 t3code 很蠢明明产物目录还要查它。第二点是 Windows 下的路径分隔符问题。ESLint 和 lint-staged 在 Unix 上一切都好但在 Windows 下偶尔会遇到 glob 模式因为\和/混用导致匹配不上文件。我的建议是如果团队里有 Windows 开发者尽量让所有 glob 都用*.{ts,tsx}这种相对通用写法不要写src/**/*这种其实在部分环境下会被正确展开的复合路径。写死了路径格式可以省掉大量环境差异问题。第三点是 CI 与本地要共用同一份 lock 文件。如果 CI 里安装依赖时不带 lock 文件那每次安装的依赖版本都可能不同最终导致本地通过、CI 失败的“灵异事件”。这个问题在 npm 上尤其明显因为npm install和npm ci的解析策略不一样。我强烈建议 CI 里强制使用npm ci而不是npm install然后 package-lock.json 必须提交到仓库。我自己早期被这个问题坑了整整两个迭代周期后来才醒悟不是测试不稳定是依赖环境根本不在同一版本上。最后一点可能有点反直觉单测里不要过度 mock。t3code 的三层里测试用 mock 是为了稳定但 mock 过多会让测试变得无效因为它测的是“我们自己假装的实现”而不是真实代码。我见过一个模块测试里 mock 了三层对象全部跑通结果集成时一调线就挂因为真实对象之间的连接行为完全没被验证过。重点防线应该保持少量真实依赖只对网络、时间、外部 API 这类不可控因素做隔离。我个人在实际操作中有个体会t3code 这套方案能不能落地关键不在选什么工具而在规则串得顺不顺、反馈快不快。我刚开始推的时候也被人吐槽“跑一次 check 要两分钟太费时间”后来优化成增量编译 lint-staged 并行 CI 之后反馈基本控制在几秒内团队的抵触情绪一下就消了。如果你打算给自己的项目或团队接入这套思路一定要先保证本地反馈足够快再把门禁逐渐收紧。规则不是越严越好而是要在“能拦住问题”和“不打扰人”之间找到那个平衡点。t3code 只是这套三层思路的载体名字叫什么不重要里面的方法论才是真正能沉淀下来的东西。
