React / 系统课时
Lint、格式化与提交检查
Lint、格式化与提交检查
本课为 TypeScript 项目建立一条提交前质量链路:ESLint 发现代码问题,Prettier 统一格式,TypeScript 检查类型,lint-staged 只处理暂存文件,Husky 在提交前自动执行校验。
学习目标
- 配置 ESLint、Prettier 与 TypeScript,使职责互不冲突
- 使用 npm 脚本统一执行静态检查和格式验证
- 通过 Husky 与 lint-staged 阻止不合格代码进入仓库
设计质量检查链路
四类工具解决的问题不同:ESLint 检查代码规则,Prettier 只负责排版,tsc --noEmit 验证类型但不生成文件,提交钩子负责在 git commit 前触发这些检查。把职责拆开,才能避免规则重复和结果不一致。

推荐把全量检查放在 npm run quality 中,供本地和 CI 使用;提交钩子只处理暂存文件,避免每次提交都格式化整个项目。类型检查无法只看单个文件,因此仍应在 CI 或提交前执行全量 tsc。
安装依赖并初始化 Husky
在已经存在 package.json 和 tsconfig.json 的 TypeScript 项目中执行:
npm install -D eslint @eslint/js typescript-eslint prettier eslint-config-prettier globals husky lint-staged
npx husky init预期结果
added <N> packages
created .husky/pre-commit<N> 取决于项目原有依赖。husky init 还会准备 prepare 脚本;若项目安装过程跳过了生命周期脚本,需要手动执行一次 npm run prepare。
配置 ESLint 与 Prettier
创建 eslint.config.mjs。最后引入 eslint-config-prettier,用于关闭与 Prettier 冲突的格式规则。
import eslint from "@eslint/js";
import globals from "globals";
import tseslint from "typescript-eslint";
import prettier from "eslint-config-prettier";
export default tseslint.config(
{
ignores: ["dist", "coverage"],
},
eslint.configs.recommended,
...tseslint.configs.recommended,
{
files: ["**/*.{ts,tsx}"],
languageOptions: {
globals: {
...globals.browser,
...globals.node,
},
},
rules: {
"@typescript-eslint/no-unused-vars": [
"error",
{ argsIgnorePattern: "^_" },
],
},
},
prettier,
);创建 .prettierrc.json:
{
"semi": true,
"singleQuote": false,
"trailingComma": "all",
"printWidth": 100
}这两个配置文件不需要控制台输出。验证方法是分别运行 npx eslint . 与 npx prettier . --check;前者不应报告规则错误,后者应提示所有匹配文件符合格式。
统一 npm 脚本与暂存文件规则
下面是 package.json 片段示例,需要合并到现有文件,不能直接覆盖项目原有依赖和脚本。
{
"scripts": {
"lint": "eslint . --max-warnings=0",
"format": "prettier . --write",
"format:check": "prettier . --check",
"typecheck": "tsc --noEmit",
"quality": "npm run lint && npm run format:check && npm run typecheck",
"prepare": "husky"
},
"lint-staged": {
"*.{ts,tsx,js,jsx}": [
"eslint --fix",
"prettier --write"
],
"*.{json,md,yml,yaml,css}": [
"prettier --write"
]
}
}quality 使用串行执行,只要任一步失败,后续命令就不会继续。lint-staged 仅处理已暂存文件,并会把自动修复后的内容重新加入暂存区。
配置提交前校验
把 .husky/pre-commit 的内容改为:
npx lint-staged
npm run typecheck该钩子的生效行为是:先修复暂存文件中的 Lint 与格式问题,再执行全项目类型检查;任一命令返回非零状态码,Git 都会取消本次提交。执行一次全量检查:
npm run quality预期输出
Checking formatting...
All matched files use Prettier code style!
TypeScript completed with exit code 0.ESLint 和 tsc 成功时通常不会输出错误信息,终端还可能包含 npm 自动打印的脚本名称。最终判断标准是进程退出码为 0。
验证提交拦截是否有效
先修改一个 TypeScript 文件,故意加入未使用变量,再执行 git add <PATH> 和 git commit -m "test: verify hook"。其中 <PATH> 替换为实际文件路径。
const unusedValue = 1;
export function add(a: number, b: number): number {
return a + b;
}预期结果
error 'unusedValue' is assigned a value but never used
husky - pre-commit script failed删除未使用变量、重新暂存并提交后,钩子应通过。不要把 --no-verify 当作常规解决方案,因为它会跳过整个提交检查;紧急绕过后也必须由 CI 继续执行 npm run quality。