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 项目。

安装开发依赖

在项目根目录执行:

bash
npm install --save-dev eslint @eslint/js typescript-eslint globals eslint-plugin-react-hooks prettier eslint-config-prettier

预期输出:

text
added <COUNT> packages
audited <COUNT> packages

实际包数量和安全审计结果可能不同;若审计发现问题,应根据依赖树判断升级方案,不要直接忽略。

配置 ESLint

创建 eslint.config.js。最后加载 eslint-config-prettier,用于关闭与 Prettier 冲突的格式规则。

js
// 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:

json
{
  "semi": true,
  "singleQuote": false,
  "trailingComma": "all",
  "printWidth": 80
}

在 package.json 的 scripts 中加入:

json
{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

配置生效后,执行检查:

bash
npm run lint
npm run format:check

预期输出:

text
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;依赖警告通常反映副作用设计问题,应先调整逻辑或稳定依赖。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 ESLint 与格式化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通