“t3code”这个名字是我内部一个代码治理项目起的代号，项目刚跑完第一轮试点的时候，团队里几个人坐在一起复盘，有人开玩笑说这名字听着像个加密协议，其实它就是我们给代码质量工程链起的短代号：三层（three-tier）代码控制。从那时起，“t3code”就成了我们晨会、周报、述职里高频出现的一个词。这篇博文就把这套体系的完整设计、落地过程、踩过的坑和实际效果一次性聊透，给正在做代码治理、CI流水线改造或工程效能建设的团队一个可以直接抄作业的参考。
我先把项目背景交代清楚。我们属于一个中等规模的前端业务团队，十几条业务线共用一个前端基建仓库，平时最头疼的问题有三个：代码风格不一致、合并请求评审流于形式、技术债越堆越深。之前团队也试过零散地引入一些代码检查工具，但都是各写各的配置，有人用了有人不用，CI上也没卡死，效果一直不行。t3code的定位就是把“代码规范”从口头要求变成一套可执行的工程机制，从开发者本地的提交钩子一直延伸到CI流水线的合入闸门，任何代码只要不满足阈值就不能合入主干。
1. t3code：不是工具，是一整套代码控制机制
1.1 这个代号的由来与项目核心目标
t3code里的“t3”代表三层控制（Three-Tier Control），这是我们梳理代码质量问题时自己总结的一个框架。传统代码治理往往只盯住“静态检查”这中间一层，但实际代码从编写到上线要经过很多环节，每个环节都有失控的可能。三层控制分别指：本地开发层的即时反馈、CI集成层的强制校验、以及技术债治理层的持续度量。
- 第一层是开发者本地的钩子与格式化工具，目标是让问题在写代码的同时就被发现，不给开发者增加额外的返工成本；
- 第二层是CI流水线里的静态检查、复杂度阈值、单测覆盖率闸门，目标是让问题在合入主干前被拦截，不把错误留给下游；
- 第三层是定期的技术债报告与代码健康度评分，目标是让质量问题清晰可见，让团队知道接下来的优化重心在哪。
t3code围绕这三层展开，贯穿“提交代码—合并请求—回归验证—定期体检”这条链路。项目启动时我们定了四个核心指标：静态检查规则覆盖率100%、代码格式通过率100%、合入主干前的检查拦截率100%、以及核心业务模块的全局单测覆盖率不低于70%。这四个指标一直贴在项目墙板上，每一条都有对应的工具链和看板数据支撑。
1.2 为什么不用现成全家桶，而要自建编排层
市面上已经有很多成熟的代码质量工具，像ESLint、Prettier、Stylelint、Husky、lint-staged、Commitlint、SonarQube等等，单拎出来任何一个都很好用。但把它们组合起来跑通一条“让开发不用记规则、让规则不用靠自觉”的链路，需要自己做一层编排，这层编排才是t3code真正的工作量所在。
我见过不少团队直接装了一套全家桶，配置文件加起来几百行，但效果依然很差。原因很简单：工具之间没有联动。比如提交钩子只做了格式化检查，但没有做Commit Message规范校验；CI上跑了一堆静态检查，但不区分新增代码和历史代码，最后整个仓库都是报错，没人敢开“全量修复”这个开关。t3code做的第一件事就是把每个环节的输入、输出、阻塞条件定义清楚，形成一张完整的控制网，而不是简单的“检查项堆叠”。
2. 核心链路拆解：规范、检查与闸门设计
2.1 三层规范体系：格式层、静态层、复杂度层
t3code在第一层和第二层里各设了两组规则，分别叫做“硬规则”和“软规则”。硬规则是格式化和可以直接判断对错的检查项，由Prettier统一管理；软规则是需要人工确认或需要上下文本判断的检查项，比如循环复杂度、函数参数数量、嵌套深度等，由ESLint配合自定义规则实现。
格式层我们定了几个基调：缩进统一2个空格、字符串单引号优先、语句末尾不带分号、对象尾括号保留尾逗号、单行长度上限100字符。这些都是Prettier的默认配置或轻量定制，没什么好争议的。我自己的经验是格式问题千万别靠ESLint管，Prettier加editorconfig就够，因为Prettier是“全量重写式”的格式化器，不会跟开发者讨价还价，而ESLint的格式规则不仅开销大，还会和Prettier冲突，最后陷入互相覆盖的尴尬。
静态层则围绕ESLint来做，我们直接沿用了业界推荐规则集，同时针对自己的业务代码加了几个自定义规则：
- 禁止在核心业务模块里使用
any类型，必须显式定义类型； - 禁止
console.log提交到主干（开发调试可以通过环境变量开关绕过）； - 禁止直接修改全局状态对象，所有全局变更必须走统一的状态管理入口；
- 命中第三方依赖耦合点时必须给出解释性注释，否则视为违规。
这些规则听起来很常见，但真正落地时有不少说法。比如“禁止console.log”这条，如果一刀切全禁，开发本地调试会非常难受，最后大概率会被绕过。我们的做法是增加一个前置条件：只有生产构建路径上的代码禁用console.log，本地开发环境不拦。这个细节直接决定了这条规则能活多久。
复杂度层是很多团队忽略的部分。我们引入了一个简单的质量分模型：每次MR会先算出本次新增或修改代码的“质量扣分”，超过阈值则阻塞。扣分来源包括超过15的循环复杂度、超过80行的函数体、超过4个的函数参数等。这套模型不评价存量代码，只盯着增量，因为存量代码是历史包袱，你不可能在一次迭代里全清掉，但增量代码是可以控制住的。
2.2 CI流水线的三道闸门：提交、MR、合入前校验
t3code在CI流水线里设了三道闸门，分别部署在代码提交后、创建MR后、合入主干前三个时间点。
第一道闸门是Commit校验，使用Commitlint检查提交信息格式，同时用lint-staged对暂存文件做格式校验和基础静态检查。它的目的是让开发者把问题留在本地，而不是推到远端CDN上让别人给你擦屁股。我建议这道闸门的规则可以适当放宽，只查格式和明显的语法错误，不用跑全量复杂规则，否则开发者会觉得“本地提交一次怎么这么慢”，积极性会受很大打击。
第二道闸门是MR构建校验，这也是t3code最关键的一环。我们配置了GitLab CI管道，每次新的MR都会自动触发一组job：先跑依赖安装和单元测试，再跑增量静态检查，接着跑构建，最后把测试覆盖率结果上传到代码质量平台。每个job的状态都会显示在MR页面下方，任何一个job失败，这个MR就无法merge。
第三道闸门是合入主干前的总校验，它和MR构建的差别在于：MR构建看的是“分支自测”，合入校验看的是“合并后是否仍然健康”。因为主干上可能已经合入了其他人的改动，你的分支在自测时是绿的，合完后未必还是绿的。我们在合入流程里单独跑一次“目标分支合并测试”，如果合并后有测试失败或覆盖率不达标，系统会直接把MR退回去。
这三道闸门的节奏是有讲究的：提交校验最快，几秒内完成；MR构建中等，一两分钟；合入校验最严格，宁可慢一点也要保证主干稳定。我遇到过团队把三道闸门全部做成重型校验，结果一次提交要等三轮几十个job排队，体验差到爆炸，最后大家开始想尽办法绕过CI。这个教训让我后来坚持一点：闸门的“轻”和“重”必须按环节区分开。
2.3 阈值设计背后的计算与取舍
阈值是整个t3code体系里最容易被误判的部分，因为很多团队把阈值拍脑袋定了：复杂度上限10、覆盖率80%之类的数字随手就写了。我不反对这些数字，但阈值一定要基于团队现有的代码分布来做决策，否则要么形同虚设，要么直接block所有人。
我们当时做了一件事：先跑一遍“代码体检”，把全仓库所有函数的复杂度、所有文件的单测覆盖率、所有模块的包体积分布拉出来，然后画了一个分布图，再基于分布图定阈值。如果一个函数复杂度是20，分布图上显示它在95%分位以外，那阈值可以定在15或18，这样大约只有5%的存量代码是超标的，新代码想写超标会被拦下来。阈值的意义不是“消灭所有超标”，而是“阻止新超标”，这个原则很重要。
覆盖率阈值我们定的是全局70%，但加了两个限制：核心业务模块单独算，必须达到80%；单文件覆盖率低于40%的模块必须说明原因并获得架构师审批。这两个限制是为了避免“总覆盖率达标但核心模块裸奔”的假象。覆盖率这件事上我自己的体会是：全局平均分好看一点意思都没有，要拆到模块维度看，否则总会被高覆盖率模块平均掉。
3. 实操过程：从零搭一套可落地的t3code
3.1 初始化工程与依赖版本选择
我先说明一下环境：我们的主仓是前端Monorepo，使用pnpm作为包管理器，代码托管在GitLab上，底层的CI runner跑的是自定义Docker镜像。这套内容虽然写的是我们的字，但整体思路可以平移到任意团队。
第一步是搭骨架。我们新建了一个独立的配置仓库叫t3code-config，所有工具链的配置文件全部放在这个仓库里，业务工程通过npm dependency引入。这样做的原因是我们在多业务线场景下，如果把配置分散到各个业务仓库里，很快就会有人私自改配置，因为配置分散的时候没人知道你改了。集中在一个仓，版本号统一管理，升级配置就是发一次npm包的事。
依赖选型我列一个当时用的参考清单，版本不需要完全一样，但选型思路值得参考：
- 代码格式化：Prettier
- JS/TS静态检查：ESLint + typescript-eslint
- 样式检查：Stylelint
- 提交钩子：Husky + lint-staged
- 提交信息校验：Commitlint
- 单元测试：Vitest + Testing Library
- 代码质量汇总：自研轻量报告脚本（采集json格式的ESLint报告、测试报告）
版本选择有一个坑想特别提醒：ESLint和typescript-eslint的版本必须严格匹配，ESLint升级大版本的时候typescript-eslint不一定立即支持，很多人踩过这个坑，报错一头雾水。我们因为锁定版本省了很多麻烦。
3.2 配置文件编写的关键点
配置文件的编写是整个项目中最容易“看起来在动，实际没效果”的部分。我拆几个文件说一下关键配置。
Prettier的配置非常简单，但有几个点要指定清楚：单引号、无分号、尾逗号、行宽100。还有一个容易被忽略的点，必须在配置里声明endOfLine: "auto"，否则跨平台协作时会出现整个文件被判定为格式不通过的情况。Windows和Linux的换行符差异会让格式化结果永远对不上，这个坑我们是实打实踩过的。
ESLint的配置相对复杂，核心是overrides和plugins的合理使用。我们用了typescript-eslint/recommended作为基底，再通过自定义规则覆盖业务限制。这里我给一个关键提醒：不要在基础配置里写太多业务规则，业务规则一定要放到overrides里按目录或按文件类型指定。比如某个目录是运行时不打包的脚本，那console.log规则就得对它放行；某个目录是测试用mock，那any类型限制也得适当放宽。如果全部挤在全局配置里，后面一定会出现大量的inline disable注释，那基本等于规则失效。
Commitlint配置我们启用了@commitlint/config-conventional，要求提交信息必须符合“类型(作用域): 描述”的格式，比如feat(core): add user login。一开始团队确实有很多人不习惯，嫌这嫌那，但坚持了两周之后，大家发现看Git Log和历史记录检索的效率提升非常明显，也就没人再抱怨了。
lint-staged的配置看起来就几行，但这里有个性能优化技巧：给不同文件类型分配不同的检查器。*.ts走ESLint，*.vue走ESLint加Stylelint，*.json走Prettier检查，不要什么东西都全量跑一遍。我们刚上t3code的第一个月看到本地提交平均耗时从原来的十几秒降到了三秒左右，全靠这个分类优化。
3.3 CI流水线接入步骤
CI流水线我们用的是GitLab CI，以.gitlab-ci.yml为核心。我整理一下主流程的阶段定义，方便理解pupline是怎么串起来的。
流程分了四个阶段：install、check、test、build。install阶段负责安装依赖并做缓存；check阶段并行跑格式校验、静态检查、提交信息校验；test阶段跑单元测试并上传覆盖率报告；build阶段做一次生产构建验证。所有阶段都跑完且通过，代码才能合并。
一个重要的配置细节是为CI禁用本地钩子的交互式部分。比如Husky在CI环境下可能会尝试弹交互式修复界面，导致流水线卡死，我们在CI环境变量里专门设置一个标识，跳过所有交互逻辑，只做非交互的校验。
还有一点是缓存策略。我们在CI里同时开了两层缓存：pnpm的store缓存和node_modules的缓存。后来数据统计显示，启用缓存后单次流水线平均运行时间从4分多钟降到了1分半钟，这个投入非常值得做。尤其是Monorepo场景下依赖动辄上千个包，不缓存的话一次install就是地狱体验。
3.4 存量仓库的灰度推进策略
t3code落地最难的不是写配置，而是让存量仓库从“零约束”过渡到“全量校验”的过程。我们的策略是“灰度放量、先试后全”。整个推进分了三步走：
第一步是种子团队试点。从业务线里挑两条规模适中、工程师对代码质量接受度较高的团队先接入，跑两周，解决掉所有流程摩擦。这两周我们不要求所有存量问题清零，只要求所有新增代码符合新规范，同时把仓库里报错数量从几千条降到几百条。
第二步是全量启用但分阶段卡阈值。所有业务线都接入t3code，但前两个月CI只报警不阻塞，开发者在MR里能看到检查结果，但不影响合入。这两个月里，我们一边收集各类误报、配置不合理的case，一边按照实际情况微调规则。等到严重误报率降到极低的状态，才进入下一步。
第三步是正式开启阻塞。这之后所有不合格的MR一律退回，没有任何特批通道。如果确实有紧急hotfix需要临时放宽，必须走邮件审批流程，由架构师和技术负责人两个人共同确认。实际运行证明，真正走的审批没几次，多数的“紧急”其实是之前不够重视。
灰度推进的核心是别让规则的一刀切伤到业务交付。代码治理项目最忌讳的就是自上而下强推，然后团队用脚投票、消极抵制。先试点、再报警、再阻塞这个节奏，看起来慢，实际上是最快被接受的路。
4. 实战中的坑与人肉排错手册
4.1 常见问题速查表
这段是整个t3code实践过程里我最有资格写的内容，因为坑是真的多。我整理了一个高频问题速查表，方便团队遇到问题时直接查。
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 本地提交时格式化失败但编辑器看起来正常 | Prettier与editorconfig或编辑器设置冲突 | 关闭编辑器的保存自动格式化，统一以Prettier配置为准 |
| ESLint报错指向与规则无关 | typescript-eslint版本与ESLint主版本不兼容 | 锁定typescript-eslint和ESLint的版本矩阵 |
| lint-staged没跑任何检查 | Husky的钩子未关联或lint-staged配置被忽略 | 检查npx husky install是否执行，检查package.json中lint-staged字段位置 |
| 提交信息校验偶尔通过偶尔失败 | 本地Commitlint版本与CI版本不一致 | 统一使用同一版本，推荐用package manager统一lock |
| 覆盖率达标但核心模块测试缺失 | 全局平均覆盖率掩盖了模块差异 | 按模块拆分覆盖率规则，核心模块单独设阈值 |
| 新开发者提交代码各种报错 | 缺少本地初始化步骤 | 提供一键初始化脚本，自动安装依赖、钩子、基础配置 |
4.2 排查工具与方法
排查代码检查类问题时，我自己有一套固定套路，分享给各位参考。
第一步是缩小复现范围。很多人一看到CI报错就去看整个流水线日志，其实大部分静态检查问题都可以在本地用一条命令复现。先把报错文件复制出来，单独针对这个文件跑ESLint，如果不报错就说明是环境差异，如果报错则是规则配置问题。环境差异最常见的就是版本不一致，通过对比本地的node_modules/.bin里的实际工具版本和CI里安装的版本能快速定位。
第二步是充分利用ESLint的debug模式。运行ESLint时加上--debug参数会输出每个文件的处理细节，哪个插件加载失败、哪条规则对哪个文件生效，全部一目了然。很多“为什么这条规则没生效”的问题，用debug模式一看便知。
第三步是检查CI缓存。别以为CI每次都是全新跑的，如果配了缓存，旧版本的工具可能被cache住，导致行为与本地不一致。我们在一次升级Prettier版本后发现CI还是按旧规则格式化，排查了半天最后发现是CI缓存没有失效，清掉缓存重跑立刻正常。
4.3 血泪教训：那些文档里不会写的事
第一个教训是不要一开始就把所有规则设为error。我们最早把复杂度超限、类型检查问题全部设为error级别，唯一的作用就是让团队在第一个月天天被挫败感轰炸。后来把所有“软规则”统一降级为warning，warning不计入阻塞项，但会在MR页面上做明显的黄色提示，同时纳入月度报告统计。这样既保留了引导性，又不会让人一天到晚被红色报错吓退。
第二个教训是规则合并时要保留来源可追溯。我们曾经重构过一次规则集，把分散在各仓库的几十条自定义规则合并到一个npm包里，结果合并时出现了大量配置冲突，某些规则在旧配置里是“开启”新配置里变成“关闭”，导致部分代码质量问题出现了两周的窗口期。后来我们给每个规则加了元数据注释，标注启用时间、责任人、示例代码，以后合并配置时靠这层注释做冲突排查，效率提升了很多。
第三个教训和人的习惯有关：规则再怎么完善，也替代不了人工评审。有些bad smell是静态检查永远发现不了的，比如一个函数看似参数合理、复杂度达标，但内部逻辑顺序混乱到让人崩溃。t3code的强制检查帮我们把“机械性问题”全部消灭干净，让评审者的注意力真正聚焦在业务逻辑和架构设计上，这才是代码治理最值得追求的效果。
5. t3code带来的真实效能变化
5.1 数据说话：评审时间、缺陷流入、构建速度
t3code上线四个月后，我们在一次效能复盘里拉了一组数据做对比，这几个数让我印象很深。
首先是评审时间。改造前，团队平均每个MR从创建到合入要经历1.8轮往返，平均耗时约10.6小时；改造后，往返轮次降到1.2轮，平均耗时降到5.4小时。这点很好理解，因为机械性问题在CI阶段就被拦截了，评审人不再需要花时间去提“这里格式不对”“这里变量命名不好”这类低级反馈，评审内容集中到业务逻辑上，沟通效率自然提升。
其次是缺陷流入量。我们把线上缺陷按引入阶段打标，发现t3code运行后，因代码规范问题（如无效分支、异常未处理、可疑的隐式类型转换）引发的线上问题占比下降了很多。这块数字虽然很难做到非常精确，但趋势非常明显，质量左移的价值直接体现出来。
第三是构建速度。这里可能会出现一个反直觉的结果，因为加了检查理论上构建会变慢，但实际平均构建时间反而下降了。原因是CI阶段并行化了各类检查任务，同时启用了依赖缓存，再加上很多过去靠人工发现问题导致的“提交-失败-重提”循环被砍掉，整体流水线吞吐量上升。一次流水线平均运行时间从最初的4分多钟降到1分半钟，等检查结果的时间少了，人干活的连贯性也好了不少。
5.2 对团队协作方式的隐性改造
数据之外，t3code对团队协作方式的改变是隐性的，但非常深刻。
过去我们很多协作冲突其实来自“代码风格审判”：两个同事因为缩进、命名、代码组织方式争得面红耳赤。自从Prettier统一接管格式之后，这类争吵几乎绝迹，省下来的精力全部投入到真正的技术讨论里，这是个特别大的隐性收益。
另一个变化是新人上手更快了。过去新同事进组，要花一两周去适应“我们团队的代码风格”，这个说法其实特别虚，因为每个老员工口中的风格都不一样。现在新人有了一份明确的工具链和规则规范，跑一遍初始化命令，提交代码时工具会告诉你哪里不对，不用老员工一条条备注提醒。新人的前几次MR体验从“一直被挑刺”变成“自主修正”，自信建立得更快。
我最喜欢的变化还是评审频率的质变。因为低质量问题被工具拦住了，评审意见里开始出现“这里的事件流设计有隐患”“缓存策略需要考虑到多实例部署”这类真正的架构级讨论。代码评审回归了它本来该有的样子，这是t3code最值得吹的一点。
5.3 下一步计划：从t3code到代码健康度平台
t3code本身跑通了，但我的目标不止于此。当下的体系已经把“新代码不能坏”控制住了，但“老代码怎么逐步变好”还需要更多基础设施支持。所以下一步我们把方向定为代码健康度平台：每次CI跑完自动产出仓库级别的健康度评分卡，包括代码异味密度（每千行代码的warn数量）、模块测试覆盖率、依赖版本新鲜度等维度。
健康度平台相比t3code的静态检查多了一层“趋势感知”。t3code回答的问题是“这次的改动合不合规”，健康度平台回答的问题是“这个模块是不是在越来越差”。我们计划把每个核心模块的健康度评分直接贴在团队周报里，用趋势驱动团队主动还债。
另外，我们还在推进一个“技术债登记”目录，开发者在修改疑难模块代码时，如果有诉求想临时规避某条规则，可以在提交信息里加一个标识（比如t3-waive），自动把这个豁免记录到技术债目录里，并关联变更人。这样技术债不再是模糊的感觉，而是可追踪、可复盘、可安排专项清理的具体项。
最后再分享一个我总结下来的核心心得。t3code能跑成，并不是因为某一个工具选得好、某条规则设计得多巧妙，而是我们把“代码质量是团队共同财产”这件事落进了工程机制里。任何团队做类似项目，我都建议先把控制链路画清楚：哪个环节发现问题、谁负责处理、处理不了会怎样，链路清晰了，工具反而都是水到渠成的选择。如果你也在折腾代码治理，先从最细的一件事做起，比如统一格式化并强制提交钩子搞定，再慢慢加码，一步步来，远比一次搞个宏大架构要靠谱得多。
