React / 系统课时
配置代码质量检查
配置代码质量检查
本课把 TypeScript、ESLint 和 Prettier 组成统一质量门禁:开发者本地与持续集成执行同一条命令,类型错误、框架规则问题或格式偏差都会阻止代码进入后续构建流程。
学习目标
- 配置 Next.js 推荐的 ESLint 扁平规则
- 统一类型检查、Lint 和格式检查命令
- 区分自动修复与必须人工处理的问题
配置 ESLint
Next.js 16 项目应显式使用 ESLint CLI,而不是依赖旧版 next lint。创建根目录 eslint.config.mjs,同时启用 Core Web Vitals 与 TypeScript 规则。
import { defineConfig, globalIgnores } from 'eslint/config'
import nextVitals from 'eslint-config-next/core-web-vitals'
import nextTypeScript from 'eslint-config-next/typescript'
export default defineConfig([
...nextVitals,
...nextTypeScript,
{
rules: {
'no-console': ['warn', { allow: ['warn', 'error'] }],
},
},
globalIgnores([
'.next/**',
'out/**',
'coverage/**',
'next-env.d.ts',
]),
])该配置会检查 React、Hooks、Next.js 和 TypeScript 常见问题。运行 npx eslint . 能扫描项目且不报告配置加载错误,即表示 ESLint 配置生效。
配置 Prettier
安装 prettier 后,创建 .prettierrc.json。Prettier 负责代码排版,ESLint 负责代码质量;项目不要再额外启用与 Prettier 重复的 ESLint 格式规则。
{
"semi": false,
"singleQuote": true,
"trailingComma": "all",
"printWidth": 80
}再创建 .prettierignore,跳过生成目录和依赖。
.next
node_modules
coverage
out格式规则生效后,npx prettier --check . 会检查文件;npx prettier --write . 才会实际改写文件。
统一项目脚本
在 package.json 的 scripts 中加入独立命令和组合命令。以下为片段示例,需要合并进现有 package.json,不能删除项目原有脚本。
{
"scripts": {
"typecheck": "tsc --noEmit",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"format": "prettier --write .",
"format:check": "prettier --check .",
"check": "npm run typecheck && npm run lint && npm run format:check"
}
}check 使用短路执行:类型检查失败后不会继续执行后续步骤,命令最终返回非零退出码,持续集成可以据此阻止合并。
执行质量门禁
在项目根目录运行组合命令。
npm run check预期结果是进程以退出码 0 结束。TypeScript 与 ESLint 在无问题时通常不输出错误,Prettier 会给出检查结果。
Checking formatting...
All matched files use Prettier code style!实际前缀和耗时可能因工具版本不同而变化,但不能出现 TypeScript error、ESLint error 或格式未通过提示。
接入持续集成
持续集成应先安装锁文件中固定的依赖,再执行 npm run check 和生产构建。不要在 CI 中自动运行 lint:fix 或 format 后直接放行,否则仓库里的问题并未真正修复。
name: quality
on:
pull_request:
push:
branches: [main]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run check
- run: npm run build验证方法是创建一个测试分支,故意加入类型错误或未格式化文件,确认流水线失败;修复后重新推送,流水线应通过。
处理典型失败
类型错误通常需要修改类型或业务逻辑,不能用 any 大面积绕过。Lint 自动修复适合导入顺序或简单规则,涉及 Hooks 依赖和服务端边界时应理解原因后人工处理。格式失败则先运行 npm run format,再检查改动是否只包含排版变化。
生产构建不应通过忽略 TypeScript 错误来“临时发布”。一旦质量门禁允许错误进入构建,问题只会延迟到运行时或用户环境暴露。