TypeScript + React 项目的 ESLint 配置

以下是针对 TypeScript + React 项目的 ESLint 配置示例，包含详细注释和最佳实践：

配置

// .eslintrc.js
module.exports = {
  root: true, // 防止向上查找配置文件
  env: {
    browser: true,
    es2021: true,
    node: true,
    jest: true
  },
  parser: '@typescript-eslint/parser', // TypeScript 解析器
  parserOptions: {
    ecmaVersion: 2021, // 支持 ES2021 语法
    sourceType: 'module', // 使用 ES 模块
    ecmaFeatures: {
      jsx: true // 支持 JSX
    },
    project: './tsconfig.json' // 指定 TypeScript 项目配置文件
  },
  extends: [
    'eslint:recommended', // ESLint 推荐规则
    'plugin:@typescript-eslint/recommended', // TypeScript 推荐规则
    'plugin:react/recommended', // React 推荐规则
    'plugin:react-hooks/recommended', // React Hooks 推荐规则
    'plugin:jsx-a11y/recommended', // 无障碍性推荐规则
    'prettier', // 关闭与 Prettier 冲突的规则
    'prettier/@typescript-eslint', // 关闭 TypeScript 相关冲突规则
    'prettier/react' // 关闭 React 相关冲突规则
  ],
  plugins: ['@typescript-eslint', 'react', 'react-hooks', 'jsx-a11y', 'prettier'],
  settings: {
    react: {
      version: 'detect' // 自动检测 React 版本
    },
    'import/resolver': {
      typescript: {}, // 支持 TypeScript 模块解析
      node: {
        extensions: ['.js', '.jsx', '.ts', '.tsx']
      }
    }
  },
  rules: {
    // 基础规则
    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
    'no-unused-vars': 'off', // 关闭原生规则，使用 TypeScript 版本
    '@typescript-eslint/no-unused-vars': [
      'error',
      { vars: 'all', args: 'after-used', ignoreRestSiblings: true }
    ],
    'no-use-before-define': 'off', // 关闭原生规则，使用 TypeScript 版本
    '@typescript-eslint/no-use-before-define': 'error',
    
    // TypeScript 规则
    '@typescript-eslint/explicit-function-return-type': 'off', // 不强制函数返回类型
    '@typescript-eslint/explicit-module-boundary-types': 'off', // 不强制模块导出类型
    '@typescript-eslint/no-explicit-any': 'warn', // 警告使用 any 类型
    '@typescript-eslint/no-non-null-assertion': 'off', // 允许非空断言
    '@typescript-eslint/no-empty-function': 'off', // 允许空函数
    
    // React 规则
    'react/prop-types': 'off', // 关闭 prop-types 检查（使用 TypeScript 类型）
    'react/react-in-jsx-scope': 'off', // 不需要手动导入 React（React 17+）
    'react/display-name': 'off', // 不强制组件显示名称
    'react/jsx-filename-extension': [
      'error',
      { extensions: ['.jsx', '.tsx'] } // 只在 .jsx 和 .tsx 文件中使用 JSX
    ],
    
    // React Hooks 规则
    'react-hooks/rules-of-hooks': 'error', // 强制 Hook 规则
    'react-hooks/exhaustive-deps': 'warn', // 警告依赖项缺失
    
    // JSX 无障碍性规则
    'jsx-a11y/anchor-is-valid': 'off', // 允许自定义链接组件
    
    // Prettier 规则
    'prettier/prettier': 'error' // 确保代码符合 Prettier 规则
  },
  overrides: [
    {
      files: ['*.ts', '*.tsx'],
      rules: {
        'no-undef': 'off' // 在 TypeScript 文件中关闭 no-undef 规则
      }
    }
  ]
};

安装依赖

npm install --save-dev \
  eslint \
  @typescript-eslint/parser \
  @typescript-eslint/eslint-plugin \
  eslint-plugin-react \
  eslint-plugin-react-hooks \
  eslint-plugin-jsx-a11y \
  eslint-config-prettier \
  eslint-plugin-prettier \
  prettier

使用方法

添加 npm 脚本：

// package.json
{
  "scripts": {
    "lint": "eslint src --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint src --ext .js,.jsx,.ts,.tsx --fix"
  }
}

WebStorm 配置：

• 打开 Settings > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint
• 选择 Automatic ESLint configuration
• 启用 Run eslint --fix on save

忽略文件：

创建 .eslintignore 文件：

node_modules/
dist/
build/
public/
*.local

注意事项

TypeScript 支持：

• 确保 parserOptions.project 指向正确的 tsconfig.json 文件
• 如果项目较大，可能需要配置 parserOptions.extraFileExtensions 支持 .vue 等文件

React 版本：

• 对于 React 17+，可以关闭 react/react-in-jsx-scope 规则
• 如果使用 Class 组件，可能需要调整相关规则

自定义规则：

• 根据团队习惯调整规则，例如：

rules: {
  'react/jsx-props-no-spreading': 'off', // 允许 JSX 属性展开
  'jsx-a11y/label-has-associated-control': 'off', // 自定义标签控件
}

与 Prettier 配合：

• 确保 eslint-config-prettier 在 extends 数组中最后加载
• 建议使用相同的配置文件管理 Prettier 和 ESLint

根据项目需求调整规则，建议在新项目中使用 npx eslint --init 初始化，然后手动合并上述配置。