1. 内容整体设计与思路拆解1.1 t3code 到底是什么先把这个名字拆开看t3code。t3 在技术圈的常见暗示是 stack 三件套组合——比如 T3 Stack 指的是 Next.js、TypeScript、Tailwind 这套现代前端阵营。但这里我想聊的不是某一家技术栈的复制而是把它理解为一个“三阶代码工程化”的落地代号tier 3 code也就是把代码从设计、实现到上线的整个链路推进到第三个等级——自动化、可观测、可复现的阶段。很多人写项目做到 second tier 就停了也就是“能跑、能过测试、能部署”。但真正的问题是当团队达到三个人以上、代码行数破万、两周一个迭代之后单纯靠“个人素质”保证代码质量是远远不够的。t3code 这个项目本质上是我做的一套前端工程化基础设施目标是让整个团队在不需要频繁开会对齐的情况下也能产出风格统一、结构清晰、可测试、可追踪的代码。我接触过不少团队工具链其实都装了ESLint、Prettier、Husky 都有但大家用的姿势完全不一样有人在代码审查中才被提醒缩进问题有人压根不跑本地检查直接推代码。问题不在工具而是没有把流程串成一条闭环。t3code 想解决的就是这个“有工具但没体系”的痛。这个项目适合谁看如果你是独立开发者希望自己的项目更规范或者你是团队里那个被推出来搞工程化的倒霉蛋又或者你只是想看看一套完整的质量基建是怎么从零搭起来的这篇内容应该都能给你一些能直接抄作业的东西。我不打算把每个工具讲成百科全书而是讲我实际配置过、踩过坑、反复调整后最终跑通的方案。1.2 为什么选这条技术路线而不是现成的脚手架你可能会问现在不是有 create-t3-app 这样的现成脚手架吗直接套一个出来不就行了实话说脚手架确实省事但有一个问题——它默认帮你绑定了某一条技术路线的全家桶。如果团队现在的业务恰好是 React Node 全栈那 T3 Stack 非常顺手。但我的场景不太一样前端代码和个人工具脚本、内部管理系统、甚至临时数据分析脚本混在一个仓库里技术栈有 React 也有 Vue有 TypeScript 也有纯 JavaScript。统一脚手架意味着强行做技术栈绑架这在实际团队中会引发不必要的迁移成本。t3code 的思路反着来不替换技术栈而是在现有技术栈上面叠加一套工程质量层。它的核心原则是三件事统一出口所有检查、格式化、提交拦截都通过一个命令入口完成新同事入职只需要跑一条命令不需要背五六条命令。渐进增强老项目不必一次性改头换面可以先跑检查、再逐渐修正存量问题不要让 lint 一开始就挡住所有人的提交。可见可追溯每一次代码提交、每一次检查结果、每一次构建产物都能被记录和回溯任何问题都能找到是哪个环节引入的。理解了这个底层逻辑再看后面所有的配置和脚本就不会觉得是在堆工具了。整个项目不是我发明的什么新技术而是把一堆成熟工具用一套合理的编排逻辑串了起来让它们各自发挥优点同时尽量避开各自的坑。2. 核心细节解析与实操要点2.1 分层拆解整个质量体系的模块t3code 我不把它看成一个单体工程而是拆成互相独立的模块每一块有自己明确的目标可以单独启用或停用。这个分层设计是整套方案的核心也是和普通脚手架最大的区别。第一层是编码约束层。这一层管的是代码写出来长什么样包含 ESLintJavaScript 检查、Stylelint样式检查、Prettier格式化、EditorConfig编辑器统一和 TypeScript 的严格模式配置。设计目标只有一个让大家写的代码像一个团队写的。第二层是提交质量层。管的是代码进入仓库之前的状态包含 HuskyGit 钩子、lint-staged只检查暂存区文件、Commitlint提交信息规范、以及提交前自动执行测试的脚本。这一层的目标是垃圾代码进不了仓库主分支。第三层是集成校验层。管的是代码合入主分支前后的状态包含 CI 流水线配置、覆盖率收集与阈值校验、构建产物校验、依赖安全检查。这一层的目标是代码合入前必须经过一道机器检查不靠人肉提醒。第四层是运行时观测层。管的是代码上线之后的状态包含日志规范、错误上报的字段约定、性能指标采集以及通过 git 提交和构建记录反查线上代码对应哪个版本的机制。这一层的目标是线上出了问题十分钟内能定位到是哪个提交引入的。你可能注意到了这四层是递进的从“写的时候”到“提交时”到“合入时”再到“上线后”。很多项目的问题在于只做了第一层甚至只做了第一层的一小半然后指望人靠自觉补上后面的部分。这是不现实的。2.2 编码约束层配置文件怎么选参数为什么这样选这一层是大家最熟悉的但也是最容易配得乱七八糟的。说几个我实际踩过的坑和最终的参数选择逻辑。ESLint 的规则集选择我推荐直接用社区维护的类型感知规则集。项目用了 TypeScript 的部分我会配上 plugin:typescript-eslint/recommended-requiring-type-checking。这个规则集的好处是会利用 TS 的类型信息做检查能抓出很多普通 lint 发现不了的问题比如错误使用 Promise、不必要的类型断言、潜在的异步竞态。代价是检查速度变慢因为需要完整解析类型信息。我的解决方法是分场景平时写代码用性能快的规则集提交前和 CI 里用完整带类型检查的规则集。这里有个很多新手会犯的错误为了快把 requiring-type-checking 整个关掉。结果就是代码里一堆隐晦的异步 bug最后靠运行时才发现。我的建议是宁可让 lint 慢两秒也要在关键节点保住类型检查。本地开发可以用缓存和只检查改动文件的方式提速而不是砍掉检查能力。Prettier 和 ESLint 的冲突处理这两个工具职责有重叠早年经常打架。现在社区已经比较成熟用 eslint-config-prettier 把 ESLint 中和格式化相关的规则关掉就行。但有一个细节容易踩坑如果团队里有人用老版的编辑器插件插件之间互相抢格式化权限最终代码风格依然混乱。我的做法是在项目根目录放一个.vscode/settings.json锁定默认格式化器为 Prettier并把 ESLint 的保存自动修复打开。这样即使新同事装了乱七八糟的插件打开项目时也会自动采用团队配置。缩进和分号这种风格问题我建议直接交给 Prettier 处理不需要在 ESLint 里反复讨论。团队讨论风格的时间花在代码逻辑上更有价值。我的配置文件里只保留业务语义相关的规则比如禁止 console.log 直接提交警告而非错误、强制显式返回类型、禁止 any 类型。EditorConfig 这个工具虽然简单但是值得配。因为不同操作系统的换行符、文件编码如果有差异Git 的 diff 会变得非常难看。配上.editorconfig和 Git 的 core.autocrlf 设置之后跨平台开发时文件冲突问题明显减少。2.3 提交质量层用 husky 卡住最后一道门提交质量层是我认为整个方案里收益最高的部分因为它在“成本最低”的时间点拦截问题。代码写完但还没 push 的时候修复的成本是最低的到了 CI 阶段再发现风格错误或缺少换行来回的成本就高了十倍。Husky 的使用看起来简单两个命令装一下然后写 hook 文件就行。但有几个细节值得注意。第一个是版本问题Husky 7 之后的版本改用.husky/目录存放钩子安装方式不同网上一堆教程还停留在老版本。如果你跟着旧教程用npm set-script prepare这种命令可能会在 CI 环境里因为npm install时触发 husky 安装而报错。我的处理方案是在 CI 里设置跳过 husky 安装的环境变量HUSKY0因为 CI 环境本来就不允许直接提交代码钩子没有意义反而可能因路径问题报错。lint-staged 的设计思路是只检查即将提交的文件而不是检查整个项目。这个非常关键尤其是老项目存量代码多、一时半会儿改不完的情况下如果每次提交都 lint 全量代码速度慢且容易把不相关的错误暴露出来。lint-staged 的过滤规则需要考虑文件类型。我配的是 key 是正则、value 是要执行的命令默认先跑 Prettier 格式化再跑 ESLint 修复最后才会执行测试命令。执行顺序上我建议格式化在先检查在后因为格式化本身可能修改文件内容放在前面可以减少一次提交后仍报格式错误的情况。Commitlint 是对提交信息格式的约束。我和团队定的规范是 Conventional Commits 的简化版type 必须是固定枚举如 feat、fix、refactor、docs、testscope 可选正文体现改动原因。提交信息规范最大的价值不是强迫症而是后续生成 changelog 和回溯问题时能自动分类。某次线上问题需要回溯到是哪一天的哪个改动引入时一份规范的提交历史会让工作变得非常轻松。2.4 集成校验层CI 里面到底跑什么CI 是很多人觉得“配了个 yaml 就算完”的地方其实这里有很多策略可以选择。t3code 的 CI 设计我分成了两个阶段Pull Request 阶段和主分支合入阶段。PR 阶段跑的是快速校验集包括 lint、类型检查、单元测试目标是几分钟内给出结论。主分支阶段跑的是完整校验集除了 PR 阶段的内容额外增加覆盖率汇总、依赖安全检查、构建产物生成和产物大小对比。这样设计是为了平衡反馈速度和检查深度PR 阶段让开发者快速迭代主分支阶段做全量兜底。覆盖率阈值的设定值得单独说。我见过团队直接把阈值定到 80% 甚至 90%导致每个人都为了凑分支覆盖率写一些没有业务意义的测试测试代码比业务代码还难维护。我和团队商量后定的是核心模块权限、支付、数据处理覆盖率不得低于 80%外围模块 60% 以上即可。原因很简单核心模块出错的代价远大于外围模块不值得在所有代码上花同等的测试成本。依赖安全检查在业界现在用的比较多的思路是 lockfile 版本比对。很多团队的做法是每周扫描一次但我和团队验证下来这个频率不够生产依赖中一旦出现高危漏洞需要的是小时级感知。目前的方案是合并主分支时自动扫一次遇到高危级别的漏洞直接让 CI 失败。如果暂时没有官方修复版本允许走一个白名单流程但必须配上时间和负责人信息白名单超时自动重新报警。这套流程跑下来依赖安全不再是一个每年检查一两次的合规动作而是一个持续性的质量保障手段。3. 实操过程与核心环节实现3.1 从零跑通 t3code 需要哪几步不用贪多先跑通一个最小闭环提交时检查代码格式 统一提交信息 push 后 CI 自动执行检查和测试。我把整个搭建过程逐步拆开。第一步初始化项目配置。在项目根目录准备好 package.json 之后先装基础依赖。我用的包管理器是 pnpm主要是因为它安装快、磁盘占用小在 CI 里提速效果明显。如果你还在用 npm方案也可以平移只是命令会有少许差异。pnpm add -D eslint typescript-eslint/parser typescript-eslint/eslint-plugin prettier eslint-config-prettier husky lint-staged commitlint/cli commitlint/config-conventional第二步初始化 husky。这一步经常被人忽略掉细节新版 husky 需要手动设置 prepare 脚本并执行husky init来生成.husky/目录。npm pkg set scripts.preparehusky init npm run prepare然后需要手动建立钩子文件npx husky add .husky/pre-commit npx lint-staged npx husky add .husky/commit-msg npx --no -- commitlint --edit $1注意 commit-msg 钩子里的$1它代表 Git 传入的提交信息临时文件路径少了这个参数 commitlint 不知道该读取哪个文件。第三步写 lint-staged 配置。这份配置放在 package.json 中效果一样也可以用独立文件但我更倾向独立 lint-staged.config.js因为配置变多后容易和 package.json 混在一起。项目中 JavaScript 和 TypeScript 混合配置采用两段式过滤规则export default { *.{js,mjs,cjs,ts,tsx}: [prettier --write, eslint --fix, eslint], *.{json,md,css,scss}: [prettier --write], *.spec.{js,ts,tsx}: [prettier --write, eslint --fix], };为什么把同一个 glob 配置两个 ESLint 命令一次eslint --fix可以自动修复基础问题但修复后可能存在二次问题再跑一次纯检查确保值得过。这个技巧虽然笨但实测下来比单独一次修复模式更可靠。第四步写 CI 工作流。我以 GitHub Actions 为例但思路没有任何绑定换成 GitLab CI 或 Jenkins 也成立。最小可用的工作流分成两个 job# .github/workflows/ci.yml name: ci on: push: branches: [main] pull_request: jobs: quality: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 - uses: actions/setup-nodev4 with: node-version: 20 cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm lint - run: pnpm type-check - run: pnpm test -- --coverage - run: pnpm build这个设置做完实际上已经能保证每一条 PR 合入前都经历一遍格式检查、类型检查、单元测试和构建验证。运行链路上它的执行顺序是push 触发钩子 → 本地 lint-staged 做好轻量拦截 → push 成功后 CI 再跑全量检查。两道关卡能筛掉的低级问题非常多。3.2 老项目接入 t3code 时怎么处理存量代码大多数团队不是从零开始用这套方案而是接手已经积累了几个月甚至几年的代码库。存量代码里必然存在大量格式不规范、lint 报错、类型不完善的问题。这种情况下如果直接开启全部检查结果是所有提交都被堵住最后大家偷偷绕过 husky 网关整个方案彻底废掉。我的接入策略分三步走。第一步先跑通格式化。全仓库执行一次 Prettier让代码风格统一。这一步虽然是改动量最大的一次但是机械操作不会引入新 bug。注意这次提交可以单独做一个 commit信息写style: format whole repo with prettier方便后续回溯。第二步启用 lint 但不作为提交拦截条件只作为提醒。ESLint 的规则全部设为 warn或者设置--max-warnings-1之外的宽松模式提交能过但在编辑器里能看到问题。接下来一个迭代周期里每个开发者在改到相关文件时顺手修复这个文件里的 lint 问题不额外集中安排时间处理。这个方法叫“打地鼠式修复”效果比专门安排一次重构大扫除好得多因为重构集中做容易造成大面积冲突和回归而分散做则风险可控。第三步再收紧规则。等代码库里的 warn 数量明显降下来、团队对规则产生认同感之后把选择的关键规则从 warn 升为 error并作为 lint-staged 的拦截条件。这个过程一定要跟团队说清楚给一个过渡期一到两周过渡期后再正式生效。硬切换是引发反弹和对抗最直接的原因。3.3 t3code 跑了两周之后我加的关键指标当流程稳定之后需要量化这套基建的效果否则领导问“搞这个有什么用”时只能回一句“代码质量变好了”这种不可量化的话。t3code 里我建立了三个朴素但有效的指标。第一个指标是提交通过率。计算方式是进入代码审查环节的 PR 数量 / 总创建的 PR 数量。这个指标的快速恶化意味着开发者在 push 后发现问题不得不撤回或反复修。通过率达到 90% 以上说明本地拦截没有过度苛刻CI 问题反馈也足够及时。第二个指标是 lint 错误密度。仓库里单位千行代码的平均 lint error 数量在接入前的数据对比接入后的数据能很直观地看出是否有改善。我要说明的是这个指标用 ESLint 的输出报告就能自动生成。第三个指标是问题回滚率。代码上线后需要 hotfix 回滚的比率也可以换成紧急修复提交的频次。当提交信息规范运行两个月以上时紧急修复会自动带上 fix(urgent) 这样的标记用脚本统计这些标记的次数可以客观看到减少趋势。这三个指标都不复杂但足够展示出工程化基建的具体效果。它们是我向团队同步进展的“成绩单”在争取更多时间投入工程化建设时也是有说服力的材料。4. 常见问题与排查技巧实录4.1 我实际踩过的那些坑和对应解法工具链这套东西光看文档和真正跑起来是两码事。我把自己真实踩过的坑整理成下面的速查表里面每个条目都是实际遇到过不是理论上可能遇到的问题。问题现象根本原因解法与排查步骤本地 lint 不报错CI 里报错本地没装 lockfile 对应版本或 CI 与本地 lint 规则不一致统一在 CI 使用--frozen-lockfile重新安装依赖本地删除 node_modules 后重装确认锁文件生效husky 钩子不执行husky 版本过新或之前旧版本没卸载干净或prepare脚本缺失检查core.hooksPath的值让它指向 .husky重新npm run prepare重建钩子lint-staged 格式化后文件仍然报格式错误Prettier 和 ESLint 的规则冲突或者有该文件后缀不在配置的 glob 里加上 eslint-config-prettier 并确认 extends 最末尾的规则覆盖顺序正确多人系统之间换行符 diff 混乱缺少 EditorConfig或者 autocrlf 策略不一致补.editorconfig统一end_of_line lfGit 配置core.autocrlf合理设置CI 安装依赖阶段偶发失败依赖源不稳定或 pnpm 缓存失效配置依赖镜像开启 CI 缓存并在失败后重试机制覆盖率上报失败导致 CI 卡住测试框架和覆盖率工具的版本兼容性出问题打印覆盖率报告检查负责人配错临时降低阈值确认数据采集是否正常拿 husky 钩子不执行这个坑单独讲一下因为它最隐蔽。很多人遇到“我明明写了钩子但是 push 时不触发”先去检查文件权限、变量名结果真正的问题往往是 husky 的core.hooksPath被其他工具占用了。比如系统里曾经装过旧版 husky或者团队有人用了别的 Git 钩子管理工具它会抢走 hooksPath 的值。可以用git config --get core.hooksPath快速确认实际生效路径再决定是修正路径还是卸载旧工具。4.2 团队推广时最容易遇到的“软问题”工具层面的问题反而是最好解决的真正难的是让团队愿意用、用得开心。第一个常见问题是“有人觉得 lint 规则烦总是在无效地上纲上线”。我的处理方式很明确风格类问题彻底交给 Prettier机器说了算谁也不要争论面向语义的规则在团队例会里过一次有异议的直接现场改配置改完共同遵守。不留模糊空间是消除摩擦的最好方式。第二个问题是“想改配置但不敢改怕动到别人的代码”。我的方法是增加配置变更的透明度。每条规则的修改都要写清楚原因、适用范围、预期影响并在 PR 描述里说明。这样大家看到的是有理有据的演进而不是某个人拍脑袋的变动。第三个问题是“觉得这套流程拖慢速度”。确实跑 lint 和测试会增加提交前的等待时间但这可以通过速度优化来对冲。lint-staged 只查增量文件TypeScript 的增量编译打开之后本地提交回到秒级CI 部分的流水线如果跑得快几分钟内能反馈整体效率不会低于无工程化阶段。还有一个很容易被忽略的点新成员加入时所以要让他们快速上道。t3code 项目里我专门加了一条npm run setup命令它会自动安装依赖、创建 .env 之类的本地文件、打印接下来要做的事和常用命令。新同事的引导文档从这个脚本开始比硬背 Wiki 舒服太多。这里踩过一个大坑默认 git 钩子放在仓库里新机器 clone 下来后钩子不会立刻生效必须手动跑npm run prepare。setup 脚本里我会顺便做这件事。5. 这套方案沉淀下来的经验与可以快速复用的扩展方向5.1 我个人的核心体会好的工程化是流程托底不是人肉背规则这套 t3code 方案落地了三个多月最大的感受是团队讨论代码风格的会议变少了、CI 报错的“废错误”变少了、上线后因为低级失误比如忘记加空值判断、漏了边界条件导致的回归变少了。整个研发协作的“摩擦系数”肉眼可见地降低。我一开始以为把工具链搭好就算完事后来才明白工程化建设的真正核心是设计让团队“不需要靠意志力也能做对”的流程。用钩子在源头堵住问题用 CI 在合入前守住底线用指标在复盘时提供依据这才是一套质量体系的完整形态。这也解释了为什么很多团队工具装了但没用起来——因为只上了第一层的工具后面的流程和闭环没跟上去。5.2 要快速复用这套方案可以直接参考这个检查清单如果你看完后想在自己的项目里试一下我整理了一份可以直接拷走的清单项目根目录必须有.editorconfig统一基本编码和换行。依赖的prepare脚本配置正确husky 钩子能正常生成。.husky/pre-commit执行 lint-staged.husky/commit-msg执行 commitlint。lint-staged 配置覆盖 js/ts 文件同时执行 format、fix、check 三段。commitlint 配置基于 Conventional 规范type 枚举保持精简。CI 流水线至少包含 install、lint、type-check、test、build 五步。覆盖率阈值根据核心/外围模块分层不搞一刀切。老项目接入时采用增量修复策略避免集中大扫除。如果这些条目你检查下来有一项是缺失的补上它需要的也就是半小时到一小时的工作量但对整个项目的长期维护效率会有非常实际的提升。扩展方向上我已经在考虑把 t3code 的这套理念延伸到文档规范和 commit 信息自动生成 changelog 的方向。工具链只是一个起点真正的目标是让工程化里的每一个环节都变成“人不用盯着也能自动跑对”的状态。能做到这一点项目越大节省的时间和避免的混乱就越可观。
