代码质量工具

代码质量工具完全指南

date: 2026-04-24

NOTE

本文档系统讲解 ESLint、Prettier、Husky、lint-staged、commitlint 和 Biome 等代码质量工具的完整配置与实战技巧，涵盖 ESLint 9.x Flat Config、Monorepo 场景、CI/CD 集成等高级主题。

---

技术概述与定位

代码质量工具链的战略价值

在现代前端工程化体系中，代码质量工具链是保障代码健康、提高团队协作效率的关键基础设施。它不仅仅是一堆 linting 规则的集合，更是一套系统性的质量保障体系。从开发者编写第一行代码开始，到代码最终进入生产环境，代码质量工具链在各个环节都发挥着不可替代的作用。

┌─────────────────────────────────────────────────────────────────────┐
│                      代码质量工具链全景图                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐            │
│  │   编码阶段   │    │   提交阶段   │    │   构建阶段   │            │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘            │
│         │                   │                   │                    │
│         ▼                   ▼                   ▼                    │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐            │
│  │  IDE 插件   │    │   Husky     │    │  CI/CD      │            │
│  │  (保存即修) │    │  (Git Hook) │    │  (自动检测) │            │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘            │
│         │                   │                   │                    │
│         └───────────┬───────┴───────────────────┘                    │
│                     ▼                                                │
│              ┌─────────────┐                                         │
│              │  Prettier   │   ← 代码格式化                          │
│              └──────┬──────┘                                         │
│                     │                                                │
│                     ▼                                                │
│              ┌─────────────┐                                         │
│              │   ESLint    │   ← 代码检查                            │
│              └──────┬──────┘                                         │
│                     │                                                │
│                     ▼                                                │
│              ┌─────────────┐                                         │
│              │ TypeScript   │   ← 类型检查                            │
│              └─────────────┘                                         │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

工具职责划分

理解每个工具的职责边界是正确配置工具链的前提。每个工具都有其明确的职责范围，跨越边界使用往往会导致配置复杂度和运行时间的增加。

工具	职责	检测类型	自动修复
Prettier	代码格式化	风格一致性	支持
ESLint	代码检查	代码质量、安全、潜在 Bug	部分支持
TypeScript	类型检查	类型错误	不支持
Husky	Git Hooks	流程控制	不支持
lint-staged	增量检查	只检查暂存文件	依赖下游工具
commitlint	提交规范	提交信息格式	不支持
Biome	格式化+检查	速度和格式	支持

工具链演进历程

代码质量工具链经历了几个重要的发展阶段。最初，ESLint 和 JSHint 分别统治着 JavaScript linting 市场，Prettier 还未诞生，代码风格主要依靠人工 review 来保证。后来，Prettier 的出现彻底改变了格式化领域的格局，它的「固执己见」设计理念反而获得了广泛认可。再后来，ESLint 9.x 引入了 Flat Config，Husky 5.x 重新设计了 Git Hook 集成方式，Biome 作为 Rust 编写的高速工具进入了视野。这个领域的演进从未停止。

---

ESLint 9.x Flat Config

Flat Config 基础

ESLint 9.0 引入了全新的 Flat Config 格式，这是 ESLint 自诞生以来最大的一次架构变革。Flat Config 使用 JavaScript 模块（ESM）格式，不再使用 .eslintrc 系列文件，配置更加简洁和现代化。这种新格式的设计目标是让配置更容易理解、更容易扩展、更好地与现代 JavaScript 工具链集成。

// eslint.config.js
import js from '@eslint/js';
import globals from 'globals';
import tseslint from 'typescript-eslint';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
import prettier from 'eslint-plugin-prettier';
import importPlugin from 'eslint-plugin-import';
 
export default tseslint.config(
  // 第一部分：忽略文件配置
  {
    ignores: [
      '**/node_modules/**',
      '**/dist/**',
      '**/build/**',
      '**/.next/**',
      '**/coverage/**',
      '**/*.min.js',
      '**/generated/**',
    ],
  },
 
  // 第二部分：JavaScript 基础配置
  {
    files: ['**/*.{js,mjs,cjs}'],
    extends: [js.configs.recommended],
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
        ...globals.es2021,
      },
    },
    rules: {
      'no-console': 'warn',
      'no-debugger': 'error',
    },
  },
 
  // 第三部分：TypeScript 配置
  {
    files: ['**/*.ts', '**/*.tsx'],
    extends: [tseslint.configs.recommended],
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        ecmaVersion: 'latest',
        sourceType: 'module',
        ecmaFeatures: { jsx: true },
      },
      globals: {
        ...globals.browser,
        ...globals.node,
        ...globals.es2021,
      },
    },
    plugins: {
      '@typescript-eslint': tseslint.plugin,
    },
    rules: {
      '@typescript-eslint/no-unused-vars': [
        'error',
        {
          argsIgnorePattern: '^_',
          varsIgnorePattern: '^_',
          caughtErrorsIgnorePattern: '^_',
        },
      ],
      '@typescript-eslint/no-explicit-any': 'warn',
      '@typescript-eslint/consistent-type-imports': [
        'error',
        { prefer: 'type-imports' },
      ],
      '@typescript-eslint/prefer-optional-chain': 'error',
      '@typescript-eslint/prefer-nullish-coalescing': 'error',
    },
  },
 
  // 第四部分：React 配置
  {
    files: ['**/*.jsx', '**/*.tsx'],
    plugins: {
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    settings: {
      react: { version: 'detect' },
    },
    rules: {
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',
      'react/jsx-uses-react': 'off',
      'react/react-in-jsx-scope': 'off',
      'react/prop-types': 'off',
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true },
      ],
    },
  },
 
  // 第五部分：Import 排序
  {
    plugins: { import: importPlugin },
    rules: {
      'import/order': [
        'error',
        {
          groups: [
            'builtin',
            'external',
            'internal',
            ['parent', 'sibling'],
            'index',
            'object',
            'type',
          ],
          pathGroups: [
            { pattern: '@/**', group: 'internal', position: 'after' },
          ],
          'newlines-between': 'always',
          alphabetize: { order: 'asc', caseInsensitive: true },
        },
      ],
      'import/no-duplicates': ['error', { 'prefer-inline': true }],
    },
  },
 
  // 第六部分：Prettier 集成（必须放在最后）
  {
    plugins: { prettier },
    rules: {
      ...prettier.configs.recommended.rules,
      'prettier/prettier': [
        'error',
        {},
        { usePrettierrc: true },
      ],
    },
  }
);

Flat Config 的设计理念

Flat Config 的设计反映了 ESLint 团队对现代 JavaScript 开发工作流的深刻理解。首先，它采用了基于文件的配置方式，每个配置对象通过 files 属性指定其适用的文件范围，这使得配置更加直观。其次，配置对象可以组合和覆盖，形成了清晰的层次结构。第三，共享配置可以通过 extends 轻松引入，插件可以通过对象形式内联配置。

这种设计带来的实际好处是：大型项目的配置可以分解为多个小配置，每个配置负责特定的文件类型；配置可以按需加载，避免了对所有文件应用不必要的规则；IDE 集成更加精确，因为可以准确知道哪些规则适用于当前文件。

TypeScript 解析器配置

TypeScript 支持是现代 ESLint 配置的重要组成部分。typescript-eslint 是目前最好的 TypeScript ESLint 集成方案，它提供了完整的 TypeScript 语法支持，并且维护了一个丰富的规则集合。

// tsconfig.eslint.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "noEmit": true
  },
  "include": [
    "src/**/*",
    "*.config.js",
    "*.config.mjs"
  ]
}

IMPORTANT

ESLint 的 tsconfig.json 配置应该与项目的 tsconfig.json 分开，因为 ESLint 可能需要包含一些 TypeScript 配置文件本身（如 .eslintrc.js），而项目的 tsconfig.json 通常不包含这些。

传统 .eslintrc 配置（兼容旧项目）

虽然 Flat Config 是未来方向，但很多项目仍使用传统配置。了解传统配置的格式对于维护旧项目和迁移都有帮助。

{
  "root": true,
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2022,
    "sourceType": "module",
    "ecmaFeatures": { "jsx": true },
    "project": "./tsconfig.json"
  },
  "plugins": [
    "@typescript-eslint",
    "react",
    "react-hooks",
    "import"
  ],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "prettier"
  ],
  "settings": {
    "react": { "version": "detect" }
  },
  "rules": {
    "prettier/prettier": "error",
    "no-console": ["warn", { "allow": ["warn", "error"] }],
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": [
      "error",
      {
        "argsIgnorePattern": "^_",
        "varsIgnorePattern": "^_"
      }
    ],
    "@typescript-eslint/consistent-type-imports": [
      "error",
      { "prefer": "type-imports" }
    ],
    "react/self-closing-comp": ["error", { "component": true, "html": true }],
    "import/order": [
      "error",
      {
        "groups": ["builtin", "external", "internal", ["parent", "sibling"], "index"],
        "newlines-between": "always",
        "alphabetize": { "order": "asc", "caseInsensitive": true }
      }
    ]
  }
}

---

Prettier 配置

核心配置

Prettier 是一个固执己见的代码格式化工具，它消除了团队中关于代码风格的争论。Prettier 的设计哲学是「放弃部分控制权以换取团队效率」，这种设计在实践中被证明是有效的。Prettier 只关注代码格式，不关注代码质量，两者的分离让工具链更加清晰。

// .prettierrc.js
/** @type {import('prettier').Config} */
export default {
  // 打印宽度 - 每行最多多少字符
  printWidth: 100,
 
  // Tab 宽度 - Tab 对应多少空格
  tabWidth: 2,
 
  // 使用空格缩进 - true 表示用空格，false 表示用 Tab
  useTabs: false,
 
  // 行尾分号 - true 会在语句末尾添加分号
  semi: true,
 
  // 单引号 - true 使用单引号包裹字符串
  singleQuote: true,
 
  // 对象引号 - 'as-needed' 只在需要时使用引号
  quoteProps: 'as-needed',
 
  // JSX 单引号
  jsxSingleQuote: false,
 
  // 尾随逗号：'es5'|'all'|'none'
  // 'all' 在所有可能的地方添加尾随逗号，包括函数参数
  trailingComma: 'all',
 
  // 对象周围空格
  bracketSpacing: true,
 
  // 箭头函数括号 - 'avoid' 尽可能省略括号
  arrowParens: 'avoid',
 
  // 跨平台换行符 - 'lf' 是最通用的选择
  endOfLine: 'lf',
 
  // Markdown 处理
  proseWrap: 'preserve',
 
  // CSS 敏感度
  htmlWhitespaceSensitivity: 'css',
 
  // Vue 文件脚本和样式缩进
  vueIndentScriptAndStyle: false,
 
  // 文件覆盖 - 针对特定文件类型的配置
  overrides: [
    {
      files: '*.md',
      options: {
        proseWrap: 'always',
        trailingComma: 'none',
      },
    },
    {
      files: '*.{json,yaml}',
      options: {
        tabWidth: 2,
      },
    },
  ],
};

.prettierignore

就像 .gitignore 告诉 Git 忽略某些文件一样，.prettierignore 告诉 Prettier 忽略某些文件。这是配置中常被忽视但非常重要的部分。

# .prettierignore
# 构建产物
dist/
build/
node_modules/
 
# 测试覆盖率
coverage/
 
# 压缩文件
*.min.js
 
# 环境变量文件
.env
.env.*
 
# lock 文件
pnpm-lock.yaml
package-lock.json
 
# 忽略配置目录
.turbo/
 
# 忽略 CDN 链接
*.html

与 ESLint 集成

ESLint 和 Prettier 职责不同但互补，需要正确集成才能发挥最佳效果。集成时最关键的原则是让 ESLint 不检查 Prettier 负责的格式化规则，这通过 eslint-config-prettier 实现。

// eslint.config.js
import prettierConfig from 'eslint-config-prettier';
 
export default [
  // ... 其他配置
 
  // Prettier 配置（必须放在最后）
  {
    plugins: { prettier },
    rules: {
      ...prettierConfig.rules,
      'prettier/prettier': 'error',
    },
  },
];

---

Husky + lint-staged

架构概览

Husky 和 lint-staged 的组合是现代前端项目中实施 pre-commit 检查的标准方案。Husky 负责 Git Hooks 的安装和管理，lint-staged 负责只检查暂存区的文件，避免检查未修改的文件以提高效率。

┌─────────────────────────────────────────────────────────────┐
│                     Git Hooks 完整流程                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  git commit                                                 │
│      │                                                      │
│      ▼                                                      │
│  ┌─────────────────┐                                        │
│  │   pre-commit    │  ← Husky 拦截                          │
│  └────────┬────────┘                                        │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │  lint-staged    │  ← 只检查暂存区文件                     │
│  └────────┬────────┘                                        │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │    Prettier     │  ← 自动格式化                           │
│  └────────┬────────┘                                        │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │     ESLint      │  ← 代码检查                            │
│  └────────┬────────┘                                        │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │  commit-msg     │  ← Husky 拦截                          │
│  └────────┬────────┘                                        │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │  commitlint    │  ← 验证提交信息                         │
│  └────────┬────────┘                                        │
│           │                                                  │
│           ▼                                                  │
│  ┌─────────────────┐                                        │
│  │   commit-msg    │  ← Git 确认提交                        │
│  └─────────────────┘                                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

安装与配置

正确的安装顺序对于 Husky 和 lint-staged 的正常工作至关重要。Husky 6.x 之后的版本采用了全新的配置方式，不再使用 .huskyrc 文件，而是直接在 .husky/ 目录中创建脚本文件。

# 安装
npm install -D husky lint-staged @commitlint/cli @commitlint/config-conventional
 
# 初始化 - 这会创建 .husky/ 目录和 prepare 脚本
npx husky init
 
# 创建 commit-msg hook 用于验证提交信息格式
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'
 
# 创建 pre-commit hook 用于代码检查
echo 'npx lint-staged' > .husky/pre-commit

lint-staged 配置

lint-staged 的配置非常灵活，可以为不同类型的文件指定不同的检查命令。配置通常放在 package.json 中，也可以放在单独的 .lintstagedrc 文件中。

// package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "prettier --write",
      "eslint --fix",
      "tsc --noEmit --pretty false"
    ],
    "*.{json,css,md,html,yml}": [
      "prettier --write"
    ],
    "*.vue": [
      "prettier --write",
      "eslint --fix"
    ],
    "*.md": [
      "prettier --write",
      "markdownlint --fix"
    ]
  }
}

WARNING

lint-staged 的命令顺序很重要。通常先运行格式化（Prettier），再运行检查（ESLint），因为 Prettier 可能会修复一些格式问题，这些修复应该被自动保存后再进行代码检查。

commitlint 配置

commitlint 确保提交信息符合约定的格式。Conventional Commits 格式已成为前端社区的事实标准，它定义了提交信息的结构化格式，便于自动化版本管理和 changelog 生成。

// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',     // 新功能
        'fix',      // Bug 修复
        'docs',     // 文档变更
        'style',    // 代码格式（不影响功能）
        'refactor', // 重构
        'perf',     // 性能优化
        'test',     // 测试
        'build',    // 构建系统或依赖变更
        'ci',       // CI 配置变更
        'chore',    // 其他变更
        'revert',   // 回滚
      ],
    ],
    'header-min-length': [2, 'always', 10],
    'header-max-length': [2, 'always', 100],
    'subject-empty': [2, 'never'],
    'type-empty': [2, 'never'],
  },
};

---

Biome：ESLint + Prettier 的替代者

Biome 是什么

Biome 是用 Rust 编写的格式化/检查工具，声称比 ESLint + Prettier 快 35 倍。它同时提供了格式化和 lint 功能，且默认兼容 Prettier 的格式化规则。Biome 的出现代表了代码质量工具领域的一个重要趋势：用更快的语言重写核心工具以获得性能提升。

# 安装 Biome
npm install -D @biomejs/biome
 
# 初始化配置
npx biome init

// biome.json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "correctness": {
        "noUnusedVariables": "warn"
      },
      "style": {
        "noNonNullAssertion": "off"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "always"
    }
  }
}

// package.json
{
  "scripts": {
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "format": "biome format --write ."
  }
}

与 ESLint/Prettier 对比

Biome 的优势在于速度和配置的简洁性，劣势在于规则数量和生态系统。在规则数量方面，ESLint 有数百个规则，而 Biome 目前约有 100 个。但 Biome 的规则覆盖了最常用的场景，且每个规则都经过精心设计。

特性	Biome	ESLint + Prettier
速度	极快（Rust）	较慢（JavaScript）
格式化	内置	Prettier
Lint 规则数	100+	数百+
TypeScript 支持	完整	完整
配置文件	biome.json	.eslintrc + .prettierrc
IDE 集成	原生	需要插件

Biome 的适用场景

Biome 最适合以下场景：对构建速度敏感的大型项目，Biome 的速度优势在大项目中更加明显；新启动的项目，可以从零开始建立 Biome 配置；作为渐进式迁移的中间步骤，可以先用 Biome 替换 Prettier，再逐步迁移 ESLint 规则。

---

CI/CD 集成

GitHub Actions

GitHub Actions 是最常用的 CI/CD 平台之一。将代码质量检查集成到 CI/CD 流程中可以确保每次代码变更都经过自动检查，在问题进入代码库之前就发现它们。

# .github/workflows/lint.yml
name: Lint
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
 
jobs:
  lint:
    name: ESLint & Prettier
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
 
      - run: pnpm install --frozen-lockfile
 
      - name: Run ESLint
        run: pnpm lint
 
      - name: Run Prettier Check
        run: pnpm exec prettier --check .
 
      - name: Run TypeScript Check
        run: pnpm typecheck
 
  test:
    name: Test
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
 
      - run: pnpm install --frozen-lockfile
 
      - name: Run Tests
        run: pnpm test:coverage
 
      - name: Upload Coverage
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

TIP

needs: lint 确保只有在 lint 通过后才运行测试，这是一种优化 CI 资源使用的方式。

GitLab CI

GitLab CI 使用 YAML 格式的配置文件，与 GitHub Actions 有很多相似之处。

# .gitlab-ci.yml
stages:
  - lint
  - test
  - build
 
variables:
  NODE_VERSION: "20"
 
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
 
eslint:
  stage: lint
  image: node:${NODE_VERSION}
  before_script:
    - corepack enable
    - pnpm install --frozen-lockfile
  script:
    - pnpm lint
 
prettier:
  stage: lint
  image: node:${NODE_VERSION}
  before_script:
    - corepack enable
    - pnpm install --frozen-lockfile
  script:
    - pnpm exec prettier --check .
 
test:
  stage: test
  image: node:${NODE_VERSION}
  before_script:
    - corepack enable
    - pnpm install --frozen-lockfile
  script:
    - pnpm test:coverage

---

VSCode 配置

VSCode 是前端开发最流行的 IDE 之一，正确的 VSCode 配置可以让开发者在编写代码时就获得即时的格式化反馈，大大提升开发体验。

// .vscode/settings.json
{
  // 默认格式化工具
  "editor.defaultFormatter": "esbenp.prettier-vscode",
 
  // 保存时格式化
  "editor.formatOnSave": true,
 
  // 保存时修复 ESLint
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
 
  // ESLint 验证的文件类型
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue",
    "html",
    "markdown"
  ],
 
  // 文件排除
  "files.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/.turbo": true
  },
 
  // TypeScript
  "typescript.tsdk": "node_modules/typescript/lib"
}

---

常见问题与解决方案

ESLint 和 Prettier 冲突

这是最常见的问题之一。症状是 ESLint 修复后，Prettier 又把格式改回来，周而复始。这是因为 ESLint 和 Prettier 都尝试格式化代码，结果互相覆盖。

症状：ESLint 修复后，Prettier 又把格式改回来。

解决方案：安装 eslint-config-prettier 并确保它在配置最后。

npm install -D eslint-config-prettier

// eslint.config.js
import prettierConfig from 'eslint-config-prettier';
 
export default [
  // ... 其他配置
 
  {
    plugins: { prettier },
    rules: {
      ...prettierConfig.rules,
      'prettier/prettier': 'error',
    },
  },
];

commitlint 阻止合法提交

这是配置不当导致的。常见原因是 Git Hook 脚本路径不正确或 hook 没有执行权限。

症状：使用了正确的格式但仍被阻止。

解决方案：检查 .husky/commit-msg 文件内容是否正确。

cat .husky/commit-msg
# 应该包含: npx --no -- commitlint --edit ${1}
 
# 如果内容正确，检查文件权限
chmod +x .husky/commit-msg

lint-staged 太慢

默认情况下，lint-staged 会对所有暂存文件运行检查。对于大型项目，这可能需要很长时间。使用缓存可以显著加快速度。

解决方案：使用 --cache 选项缓存结果。

{
  "lint-staged": {
    "*.ts": [
      "eslint --cache --fix",
      "tsc --noEmit --incremental"
    ]
  }
}

TypeScript 和 ESLint 配置不一致

当 TypeScript 编译器和 ESLint 对代码的理解不一致时，会导致奇怪的错误。这种情况通常发生在 TypeScript 配置和 ESLint 配置使用不同的 tsconfig.json 时。

解决方案：确保 ESLint 使用项目的主 tsconfig.json。

// eslint.config.js
{
  files: ['**/*.ts', '**/*.tsx'],
  languageOptions: {
    parserOptions: {
      project: './tsconfig.json',
      tsconfigRootDir: process.cwd(),
    },
  },
}

---

工具链最佳实践

推荐配置栈

对于大多数现代前端项目，以下配置栈是经过验证的最佳选择：

小型项目（个人项目或初创项目）：

• Biome 作为唯一的格式化和 lint 工具
• 优点：配置简单，速度极快

中型项目（团队项目）：

• ESLint 9.x Flat Config + Prettier + Husky + lint-staged
• 优点：规则丰富，社区支持好

大型项目（企业级项目）：

• ESLint 9.x Flat Config + Prettier + Husky + lint-staged + commitlint
• 优点：完整的质量保障体系

配置继承策略

在大型项目中，配置继承是一个重要的考量。可以将共享配置提取到单独的包中，供所有项目继承。

packages/
├── eslint-config/     # 共享 ESLint 配置
├── prettier-config/   # 共享 Prettier 配置
└── tsconfig/          # 共享 TypeScript 配置

---

TIP

代码质量工具链推荐栈：ESLint 9.x Flat Config + Prettier + Husky + lint-staged + commitlint。对于追求极致性能的项目，可以考虑 Biome 替代 ESLint + Prettier 的组合。无论选择哪种工具链，关键在于团队一致性和持续执行。一套配置只有在被严格遵守时才能发挥作用。

---

SUMMARY

代码质量工具链是前端工程化的基石。ESLint 负责代码质量检查，Prettier 负责格式化统一，Husky 和 lint-staged 在提交前自动检查，commitlint 规范提交信息。正确配置这套工具链，可以显著提升代码质量、减少代码审查负担、加快 CI/CD 流程。记住，最好的配置是能够适应团队工作流程的配置，持续迭代优化才是关键。工具链的配置不是一劳永逸的，需要根据项目发展和团队反馈不断调整。

---

本文档由 归愚知识系统 自动生成