impeccable这个词最开始只是我某个周五晚上随手起的仓库名本意是给自己那堆越来越散乱的前端工程做一个质量底线的收容所。没想到后来它慢慢长成了一个包含代码规范、自动化检查、CI流水线和团队协作约定在内的完整质量体系甚至被几个同事复制到他们自己的项目里。这篇博文就来拆一拆我是怎么从零搭起这套东西的踩过哪些坑哪些配置值得照抄哪些规则必须按项目实际情况调希望对正在搭工程化基建的同学有实际参考价值。1. 为什么需要一套自己的质量基线1.1 痛点来源项目多了以后问题不是bug而是混乱我手上有六个前端项目三个是老项目两个是中途接手的只有一个是我从零开始的。真正让我崩溃的不是业务bug而是风格的极度分裂A项目用单引号B项目用双引号C项目一半文件用tab一半用空格。Git提交信息有的写fix bug有的写update有的干脆是111。代码里到处是console.log、any类型、eslint-disable的注释。这种混乱的代价很隐蔽每切换一个项目光适应代码风格就要浪费半天code review的时候大家争论的不是业务逻辑而是这里该不该分号新同事入职第一周基本在问这个项目有啥规矩。问题的本质不是某个人的水平而是项目之间缺少一个统一、可执行的质量基线。1.2 什么是质量基线给每一次提交设一道闸质量基线这个概念说白了就是给代码从写出来到上线之间加几道自动化的闸门。每一道闸门只做一件事检查代码是否符合某个标准不通过就不放行。第一道闸保存代码时自动格式化Prettier第二道闸提交代码前做静态检查ESLint、Stylelint、类型检查第三道闸提交信息是否符合规范commitlint第四道闸推送到远程后CI跑全套测试这四道闸合起来就是我说的impeccable工作流。注意这里没有引入任何新的、复杂的框架全部是社区成熟工具的组合。因为我的原则是质量体系本身不应该成为项目的负担它应该像红绿灯一样存在感越低越好。1.3 为什么选择组合工具而不是全家桶做方案选型的时候我考虑过两条路线一是用某个全家桶框架自带的质量能力二是自己组合ESLint、Prettier、husky、commitlint这些独立工具。全家桶的好处是开箱即用配置少但缺点是升级绑定、规则不可控。比如全家桶升级后某个规则突然收紧你只能干瞪眼。而独立工具组合的每一个环节都可以单独替换规则可以精确到哪条规则对哪个文件生效。对于有多个存量项目的团队来说独立工具组合是唯一现实的选择因为你不可能让所有老项目一次性跟着全家桶升级。所以impeccable这套体系的定位就很清晰它不是框架而是一套可插拔的工程化配置集合。2. 总体设计四大支柱撑起质量体系2.1 第一支柱静态检查覆盖代码质量死角静态检查是第一道也是最重要的一道防线。它抓的是那些肉眼容易漏掉、但确实会影响代码质量的问题。在我的体系里静态检查分三层语法层交给eslint配合parser处理未定义变量、重复声明这类基础问题类型层TypeScript的tsc --noEmit处理any、假定的空值、类型不匹配风格层交给prettier处理引号分号缩进这类纯风格问题这三层各干各的绝不能混在一起。很多人喜欢让eslint同时管风格和逻辑结果就是eslint配置里一堆缩进、引号的规则和逻辑规则混在一起改起来极其痛苦。我的做法是风格问题全权交给prettiereslint只保留逻辑类规则遇到和prettier冲突的格式规则一律关掉。这是我在项目里踩过最大的坑换来的教训后面会详细说。2.2 第二支柱提交钩子让问题在源头拦截lint-staged和husky是这套体系的传输带。它们解决的问题是代码检查跑在哪一环最合适。如果只把检查放在CI那么每次发现错误要在几分钟后才能收到反馈改一个分号都要来回推一次成本太高。如果完全靠开发者自觉那基本等于没有。合理的折中是把检查放在git commit之前而且是只检查本次提交涉及的文件lint-staged的工作方式这样既不阻塞正常提交又能保证进入仓库的每一行代码都过过检。husky在这里负责挂钩子lint-staged负责挑出git add的文件并跑对应的检查命令。这个组合已经非常成熟唯一要注意的是版本兼容问题后面问题排查部分我会提到。2.3 第三支柱CI策略保证合入之前必过测本地检查做得再好也不能完全信任本地的环境因为某个开发者的本地依赖可能没更新、可能绕过了钩子。CI是最后一道保险它保证的是合入主分支之前代码在一台干净机器上能通过全部检查。我的CI策略是三个步骤串联安装依赖用lock文件保证依赖版本一致跑lint和类型检查不跑测试因为lint问题不值得占用测试时间跑测试和构建测试输出覆盖率构建通过才算结束这里有个经验CI的步骤要尽量快别把lint、类型检查、测试、构建全混在一个job里。拆成独立的job并行跑整体时间能少一半。后面我贴了完整的配置文件直接抄就可以。2.4 第四支柱统一约定降低协作摩擦技术工具解决的是机器能检查的问题但还有很多机器检查不了的问题需要靠约定来解决。比如分支命名规则、PR描述模板、代码review检查单这些都属于质量基线的软性部分。我把它们整理成一个CONTRIBUTING.md放在仓库根目录并做成PR模板。模板里强制人写清楚这个改动解决什么问题、影响范围是什么、测试怎么做的。这看起来是形式主义但它真的把review质量拉高了一个档次。一个说不清楚影响范围的PR基本说明改动的人自己也没想清楚。3. 核心实现一份可以直接照抄的工程配置3.1 项目结构与版本选型先给出一份我实际在用的目录结构已经简化掉了业务代码部分impeccable-demo/ ├── .github/ │ └── workflows/ │ └── ci.yml ├── .husky/ │ ├── pre-commit │ └── commit-msg ├── .eslintrc.cjs ├── .prettierrc.json ├── .stylelintrc.json ├── commitlint.config.cjs ├── tsconfig.json ├── package.json ├── vitest.config.ts └── src/版本选型我在实操时锁定的是当时相对稳定的版本组合ESLint 8.x typescript-eslint 6.x Prettier 3.x husky 8.x lint-staged 15.x。注意这些大版本之间有兼容性要求比如lint-staged 15要求Node 16以上husky 9和husky 8的初始化命令不一样。如果你要照抄建议先用我这里的版本组合跑通了再考虑升级。3.2 package.json 脚本设计脚本是整个体系的入口。我发现很多项目的问题在于脚本太多了开发不知道该跑哪个。所以我的原则是对外只暴露五个命令其余全部内部化。{ scripts: { dev: vite, lint: npm run lint:eslint npm run lint:style npm run lint:type, test: vitest run, build: tsc -b vite build, prepare: husky } }npm run lint是所有静态检查的总入口包括ESLint、Stylelint、TypeScript类型检查。npm test是单次测试运行。build里加上了tsc -b保证构建前类型是通的。prepare是husky v9的初始化钩子npm install时会自动执行确保新克隆项目的人装上依赖就有了git钩子。3.3 ESLint配置逻辑规则与格式规则分离ESLint是这套体系的灵魂也是最容易配错的部分。我的ESLint配置长这样// .eslintrc.cjs module.exports { root: true, env: { browser: true, es2022: true, node: true }, extends: [ eslint:recommended, plugin:typescript-eslint/recommended, plugin:react-hooks/recommended ], parser: typescript-eslint/parser, plugins: [typescript-eslint], rules: { no-console: [warn, { allow: [warn, error] }], typescript-eslint/no-explicit-any: error, typescript-eslint/no-unused-vars: [error, { argsIgnorePattern: ^_, varsIgnorePattern: ^_ }] }, ignorePatterns: [dist, node_modules, *.config.js] };有几个关键决策点要说清楚我把no-explicit-any设成error而不是warn因为warn在CI里默认不阻塞等于形同虚设。想让规则真正生效就要狠下心设成error。no-console我设成warn并允许warn和error。这是妥协的结果。直接禁掉console不现实因为老项目里console多到改不完但从现在起新代码不允许用console.log这个约束能保证存量不再增长。no-unused-vars一定要配置argsIgnorePattern和varsIgnorePattern。否则你写function foo(_arg)这种占位参数的时候eslint会一直报错最后大家只能被迫写void _arg丑到不行。格式类规则在eslint:recommended里其实没多少但typescript-eslint/recommended里会带一些缩进、引号之类的格式规则。我的做法是在rules里一条一条把它们关掉比如rules: { typescript-eslint/indent: off, typescript-eslint/quotes: off, typescript-eslint/semi: off }3.4 Prettier与Stylelint风格交给专用工具Prettier配置是我见过最容易被过度配置的文件其实核心就几项{ semi: true, singleQuote: true, trailingComma: all, printWidth: 100, tabWidth: 2 }为什么printWidth选100而不是80因为团队里大家用的都是大屏显示器80会逼着人把本来一行能写完的代码拆成三行反而增加阅读负担。但也不建议超过120行太长在diff视图里要横向滚动。Stylelint针对CSS相关文件配置更轻量{ extends: [stylelint-config-standard], rules: { declaration-empty-line-before: null } }declaration-empty-line-before这条规则要求声明之间有空行说实话在写普通CSS时这个规则容易让人烦躁我直接关掉了。这里也体现一个原则任何规则如果团队成员频繁抱怨就优先考虑是不是规则本身不合理而不是强行让人适应。3.5 提交校验husky lint-staged commitlint提交钩子这块我踩的坑最多。一是husky版本升级后初始化方式变了二是lint-staged的配置写法在不同版本间有差异。先说最终配置。.husky/pre-commit文件npx lint-staged.husky/commit-msg文件npx --no -- commitlint --edit $1lint-staged配置直接放在package.json里{ lint-staged: { *.{ts,tsx}: [eslint --fix, prettier --write], *.{css,scss}: [stylelint --fix, prettier --write], *.{json,md,yml}: [prettier --write] } }注意这里有个细节ESLint和Stylelint都加了--fix参数意味着提交时能自动修复的问题直接修复不再阻塞提交。只有修复不了的问题才报错。这个设计很重要它保证了零手动摩擦的体验。eslint --fix跑完代码风格已经统一真正需要你动手解决的问题只占少数。commitlint配置// commitlint.config.cjs module.exports { extends: [commitlint/config-conventional], rules: { type-enum: [2, always, [ feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert ]] } };为什么非要用conventional commit格式主要不是为了生成changelog而是为了后续的版本管理和溯源。当你能用git log --oneline --grep^fix快速筛选出所有线上bug修复时你就知道它的价值了。强制提交信息规范其实是一种风险极低、收益极高的投资。3.6 CI流水线GitHub Actions完整配置这是整个体系里自动化程度最高的部分。我这份配置如果照抄要记得把node版本换成你们项目实际用的name: CI on: push: branches: [main] pull_request: branches: [main] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm run lint test: runs-on: ubuntu-latest needs: lint steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm test build: runs-on: ubuntu-latest needs: test steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm run build因为CI一次是三个job串行跑总时间一般在三到五分钟。我加了needs依赖保证顺序lint过了才跑testtest过了才跑build。有几次ve别搞反lint没过就发build浪费资源不说问题定位还得翻两个job的日志。另外一个细节是npm ci而不是npm install。npm ci会严格按lock文件安装不会改变版本且会删掉node_modules里的多余内容保证CI环境干净同时它比install快很多。4. 落地过程中最值得说的高频实操4.1 lint-staged为什么不生效husky的版本坑这是整个过程中我花时间最长的一次排查。现象是配好husky和lint-staged之后提交代码时钩子完全没有执行代码随便写都能提交成功。排查思路是这样走的先确认.husky/pre-commit执行权限ls -l .husky/pre-commit发现确实没有x权限。husky 8的低版本确实有这个坑克隆到新机器上钩子会失活需要在prepare脚本里加chmod修复。查husky v9之后初始化方式变成husky命令而不是husky install如果项目是从老教程复制来的命令对不上。还有一个不起眼的地方husky的钩子内容里如果用npx lint-staged当项目没有安装lint-staged时会静默失败。我当时看日志发现npx在交互式询问是否安装lint-staged但因为钩子环境是非交互的就卡在那里没反应。最后解决方案是把依赖全部固定版本写入package.json并且把钩子里的命令改为直接调项目内命令# .husky/pre-commit npm exec lint-staged4.2 测试策略覆盖率阈值怎么定才不虚高很多人一上来就定80%、90%的覆盖率阈值结果就是团队开始写一堆测试专门去覆盖那些永远不会被执行的分支覆盖率数字很好看测试质量却很糟糕。我在impeccable里把覆盖率阈值定在行覆盖70%分支覆盖60%并且设了--coverage.enabled和--coverage.thresholds配置。更重要的是我在测试策略里明确规定核心工具函数、通用组件必须有单元测试业务页面组件只做冒烟测试能正常渲染、关键交互可用复杂的业务状态流转用合理的集成测试覆盖关键路径覆盖率是结果不是目标。与其追求一个全绿的覆盖率数字不如保证每一次核心逻辑改动都有测试跟着走。这个约定写进了CONTRIBUTING.md比阈值本身管用。// vitest.config.ts import { defineConfig } from vitest/config; export default defineConfig({ test: { environment: jsdom, coverage: { provider: v8, thresholds: { lines: 70, functions: 65, branches: 60, statements: 70 } } } });4.3 老项目如何渐进式落地而不是推倒重来存量项目不可能一天全部达标。如果强制所有历史代码一次性过lint光修warning就能修出一大堆不该有的改动而且review起来人见人烦。我的渐进策略是分三步第一步先跑通所有的自动格式化让全项目代码风格一致这个可以放心做纯风格变化不改变逻辑第二步把ESLint的错误级别规则全部打开warn级别的规则先不开让团队先消化掉必须处理的错误第三步在CI里加上检查并且对存量问题用.eslintignore或者/* eslint-disable */按文件排除后续每动一个文件就清理一段直到存量清完很多人觉得给文件加eslint-disable是作弊但渐进落地真的需要这种临时豁免机制。关键是豁免要有计划、有时间表而不是永远豁免。我在项目里用了一个脚本每次发版时统计被豁免文件的数量数量不降就不允许发版倒逼团队持续清理。4.4 代码审查里那些工具查不出来的约定工具能拦截格式和低级错误但review时真正要盯的是那些自动检查永远发现不了的问题。我总结出了三个重点状态管理是否被滥用。一个只被两个组件共享的状态完全没有必要引入全局状态管理。我见过太多项目因为这个问题导致状态流失控。组件拆分粒度是否合理。一个文件500行以上还同时管请求、渲染和交互基本可以判定这个组件有病。是否有隐藏的破坏性改动。接口返回字段改了名、某个参数变成必需、删除了一度被依赖的导出这些都是隐性地雷。我建议每个团队把这三条写进PR模板的checklist里。机器检查交给机器人的注意力应该放在这些事情上。5. 这套体系跑了大半年之后的复盘5.1 哪些配置被证明是有效的在六个项目中跑了大概七个月说实话有些预期之内的效果也有一些超出预期。最直观的是code review的争论点完全变了从这里该不该加空格变成这个逻辑能不能换个写法review效率显著提升新同事上手新项目的适应时间从一周缩短到一到两天因为所有项目的代码风格和质量约束是统一的线上bug中由于低级错误未判空、类型错乱、拼写错误导致的比例明显下降这部分要归功于TypeScript和ESLint的组合拦截查找历史改动变得很快git log --grep按提交类型筛选非常顺手5.2 哪些配置其实是过度设计复盘时我也承认有几个环节是过度设计。比如最开始我给每个项目都配了复杂的monorepo结构希望多个包共享同一套质量配置结果实际运行时复杂度远大于收益小组件之间互相版本牵连。后来退回到每个项目独立配置核心配置用模板同步的方式反而稳定得多。另一个过度设计是自定义ESLint插件。刚开始我觉得业务上有些规则很值得固化成插件比如禁止直接用某个API。写了一个后来发现维护成本太高规则稍微不严谨就误报一堆。现在我的倾向是能用no-restricted-imports这类内置配置表达的绝不自造插件。自定义插件的收益要大到能覆盖维护成本才值得做。5.3 团队执行力的关键在无摩擦最后想聊聊这套体系里最容易被忽视但也最重要的原则无摩擦。任何质量工具只要使用成本高大家就会想方设法逃避。我见过有人为了绕过lint-staged直接手动改.git/index这种骚操作说明工具本身设计有问题——它让人产生了对抗心理。impeccable的设计目标是让所有检查尽量自动化、尽量无感能自动修复的绝不让人手动改能在提交前检查的绝不拖到CI能在CI检查的绝不让人开会讨论任何一条规则如果团队里三个人以上反对就当场讨论去留根据我个人的实操体会质量的提升不是靠一次推倒重来的大改造而是靠一个可持续、被大多数人接受的小约束慢慢养成的。这套叫impeccable的东西配置本身并不值钱值钱的是它让团队重新开始讨论什么算是好代码这个问题。如果你的项目也正被代码风格混乱、提交信息乱飞、review低效这些问题困扰不妨先照着上面的配置搭一套最小版本跑上一个月再来调整你会发现团队对质量的态度会悄悄改变。
