React / 系统课时
配置 ESLint 与格式化
配置 ESLint 与格式化
代码规范只有在编辑和提交阶段自动执行,才能真正减少低级错误与无意义的格式争论。本课为 React TypeScript 项目配置 ESLint Flat Config 和 Prettier,并通过脚本把检查、修复与格式验证统一起来。
学习目标
- 使用 Flat Config 配置 TypeScript 与 React Hooks 规则
- 明确 ESLint 和 Prettier 的职责边界
- 通过 npm 脚本执行检查、自动修复和格式验证
工具职责与依赖安装
ESLint 负责发现潜在缺陷和不合理写法,例如未使用变量、Hook 依赖遗漏和条件调用 Hook。Prettier 只负责稳定格式,例如缩进、换行、引号和尾逗号。两者应协作,但不要让两个工具同时决定相同的格式规则。
配置前先确认项目能够正常执行 TypeScript 构建,并删除旧的 .eslintrc 配置,避免新旧体系同时生效。下面的方案使用 eslint.config.js,适合采用 ES Module 的 Vite React 项目。
安装开发依赖
在项目根目录执行:
npm install --save-dev eslint @eslint/js typescript-eslint globals eslint-plugin-react-hooks prettier eslint-config-prettier预期输出:
added <COUNT> packages
audited <COUNT> packages实际包数量和安全审计结果可能不同;若审计发现问题,应根据依赖树判断升级方案,不要直接忽略。
配置 ESLint
创建 eslint.config.js。最后加载 eslint-config-prettier,用于关闭与 Prettier 冲突的格式规则。
// eslint.config.js
import js from "@eslint/js";
import prettierConfig from "eslint-config-prettier";
import reactHooks from "eslint-plugin-react-hooks";
import globals from "globals";
import tseslint from "typescript-eslint";
export default tseslint.config(
{ ignores: ["dist", "coverage"] },
js.configs.recommended,
...tseslint.configs.recommended,
{
files: ["**/*.{ts,tsx}"],
languageOptions: {
ecmaVersion: "latest",
globals: globals.browser,
},
plugins: {
"react-hooks": reactHooks,
},
rules: {
// 直接复用插件推荐规则,避免手工漏掉 Hook 约束
...reactHooks.configs.recommended.rules,
"@typescript-eslint/no-unused-vars": [
"error",
{ argsIgnorePattern: "^_" },
],
},
},
prettierConfig,
);该配置会检查 JavaScript、TypeScript 和 TSX 文件,忽略构建产物与覆盖率目录,并启用 React Hooks 推荐规则。若项目包含 Node 配置脚本,可以再为这些文件单独声明 globals.node,不要把 Node 全局变量开放给全部浏览器代码。
格式化、脚本与执行流程
创建 .prettierrc.json:
{
"semi": true,
"singleQuote": false,
"trailingComma": "all",
"printWidth": 80
}在 package.json 的 scripts 中加入:
{
"scripts": {
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"format": "prettier . --write",
"format:check": "prettier . --check"
}
}配置生效后,执行检查:
npm run lint
npm run format:check预期输出:
Checking formatting...
All matched files use Prettier code style!当 ESLint 没有发现问题时通常不会输出错误;若存在问题,命令应以非零状态退出,并显示文件、行号和规则名称。
把检查放到开发流程
编辑器保存时自动格式化可以提升体验,但不能替代命令行检查,因为团队成员的编辑器设置可能不同。提交前至少执行 lint 和 format:check,持续集成中也应运行同样脚本,确保本地与远程标准一致。
lint:fix 和 format 会修改文件,适合开发者主动执行;CI 应使用只读检查命令,避免流水线修改源码后继续构建。对于无法自动修复的规则,要阅读规则含义并修正逻辑,而不是随手禁用。
常见配置问题
若出现“配置文件未找到”,确认命令从项目根目录执行,并检查文件名是否为 eslint.config.js。若配置文件使用 import,项目需要启用 ES Module,或把配置文件改为 .mjs。
不要同时保留大量风格类 ESLint 规则和 Prettier。格式冲突会导致保存后反复变化。也不要全局关闭 react-hooks/exhaustive-deps;依赖警告通常反映副作用设计问题,应先调整逻辑或稳定依赖。