ESLint新Flat Config与typescript-eslint、jsx-a11y插件兼容失败

尝试迁移至ESLint新Flat Config时，typescript-eslint与eslint-plugin-jsx-a11y插件无法正常关联，构建时出现规则未找到错误，比如@typescript-eslint/no-explicit-any、jsx-a11y/control-has-associated-label，所有错误均来自这两个插件。相关配置代码如下：

import path from 'node:path'
import { fileURLToPath } from 'node:url'
import js from '@eslint/js'
import { FlatCompat } from '@eslint/eslintrc'
import globals from 'globals'

import react from 'eslint-plugin-react'
import unicorn from 'eslint-plugin-unicorn'
import eslintConfigPrettier from 'eslint-config-prettier'
import importPlugin from 'eslint-plugin-import'
import jsxA11y from 'eslint-plugin-jsx-a11y'
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'
import eslintPluginUnicorn from 'eslint-plugin-unicorn'
import tseslint from 'typescript-eslint'

const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)
const compat = new FlatCompat({
  baseDirectory: __dirname,
  recommendedConfig: js.configs.recommended,
  allConfig: js.configs.all,
})

export default tseslint.config([
  {
    ignores: ['**/node_modules', '**/*.js'],
  },
  ...compat.extends('airbnb', 'airbnb-typescript', 'airbnb/hooks'),
  importPlugin.flatConfigs.recommended,
  jsxA11y.flatConfigs.recommended,
  reactPlugin.configs.flat.recommended,
  reactPlugin.configs.flat['jsx-runtime'],
  eslintPluginUnicorn.configs['flat/recommended'],
  ...tseslint.configs.recommended,
  {
    plugins: {
      react,
      '@typescript-eslint': tseslint.plugin,
      unicorn,
    },
    languageOptions: {
      ...reactPlugin.configs.flat.recommended.languageOptions,
      globals: {
        ...globals.browser,
        ...globals.es2021,
      },
      parser: tseslint.parser,
      parserOptions: {
        project: true,
      },
    },
    rules: {
      'import/prefer-default-export': 'off',
      'react/jsx-props-no-spreading': 'off',
      'react/require-default-props': 'off',
      'react/react-in-jsx-scope': 'off',
      'react/display-name': 'off',
      'react/no-unstable-nested-components': [
        'error',
        {
          allowAsProps: true,
        },
      ],
      'no-param-reassign': [
        'error',
        {
          props: true,
          ignorePropertyModificationsFor: ['draft'],
        },
      ],
      '@typescript-eslint/array-type': 'error',
      '@typescript-eslint/no-inferrable-types': 'error',
      '@typescript-eslint/no-non-null-assertion': 'error',
      '@typescript-eslint/ban-types': [
        'error',
        {
          types: {
            Node: 'Node is disabled, use HTMLElement',
          },
        },
      ],
      '@typescript-eslint/await-thenable': 'error',
      '@typescript-eslint/no-for-in-array': 'error',
      '@typescript-eslint/no-unnecessary-type-arguments': 'error',
      '@typescript-eslint/no-unnecessary-type-assertion': 'error',

      '@typescript-eslint/consistent-type-assertions': [
        'error',
        {
          assertionStyle: 'as',
        },
      ],
      '@typescript-eslint/prefer-nullish-coalescing': 'error',
      '@typescript-eslint/switch-exhaustiveness-check': 'error',
      '@typescript-eslint/restrict-plus-operands': 'error',
      '@typescript-eslint/prefer-for-of': 'error',
      '@typescript-eslint/no-extra-non-null-assertion': 'error',
      '@typescript-eslint/no-non-null-asserted-optional-chain': 'error',
      '@typescript-eslint/prefer-optional-chain': 'error',
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/require-await': 'error',
      'unicorn/filename-case': [
        'error',
        {
          case: 'kebabCase',
        },
      ],
    },
  },
  eslintConfigPrettier,
  eslintPluginPrettierRecommended,
])

解决方案 #

问题出在这几个地方，对应修复方式如下：

• 变量名写错：导入eslint-plugin-react时命名为react，但后续代码误用了reactPlugin，导致React插件配置无法加载，需统一变量名。
• jsx-a11y未注册：jsx-a11y插件没在plugins字段中注册，ESLint无法识别它的规则，必须添加注册。
• 配置顺序冲突：compat.extends加载的Airbnb传统配置与Flat Config混用易引发规则覆盖，建议先加载Flat Config格式的插件推荐配置，再兼容Airbnb配置。
• 重复导入插件：重复导入了eslint-plugin-unicorn，删除冗余导入即可。

修正后的完整配置代码 #

import path from 'node:path'
import { fileURLToPath } from 'node:url'
import js from '@eslint/js'
import { FlatCompat } from '@eslint/eslintrc'
import globals from 'globals'

import react from 'eslint-plugin-react'
import unicorn from 'eslint-plugin-unicorn'
import eslintConfigPrettier from 'eslint-config-prettier'
import importPlugin from 'eslint-plugin-import'
import jsxA11y from 'eslint-plugin-jsx-a11y'
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'
import tseslint from 'typescript-eslint'

const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)
const compat = new FlatCompat({
  baseDirectory: __dirname,
  recommendedConfig: js.configs.recommended,
  allConfig: js.configs.all,
})

export default tseslint.config([
  {
    ignores: ['**/node_modules', '**/*.js'],
  },
  // 优先加载Flat Config格式的插件推荐配置
  react.configs.flat.recommended,
  react.configs.flat['jsx-runtime'],
  jsxA11y.flatConfigs.recommended,
  importPlugin.flatConfigs.recommended,
  unicorn.configs['flat/recommended'],
  ...tseslint.configs.recommended,
  // 兼容Airbnb传统配置（若需保留）
  ...compat.extends('airbnb', 'airbnb-typescript', 'airbnb/hooks'),
  {
    plugins: {
      react,
      '@typescript-eslint': tseslint.plugin,
      unicorn,
      'jsx-a11y': jsxA11y, // 注册jsx-a11y插件
    },
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.es2021,
      },
      parser: tseslint.parser,
      parserOptions: {
        project: true,
        ecmaFeatures: {
          jsx: true,
        },
      },
    },
    rules: {
      'import/prefer-default-export': 'off',
      'react/jsx-props-no-spreading': 'off',
      'react/require-default-props': 'off',
      'react/react-in-jsx-scope': 'off',
      'react/display-name': 'off',
      'react/no-unstable-nested-components': [
        'error',
        {
          allowAsProps: true,
        },
      ],
      'no-param-reassign': [
        'error',
        {
          props: true,
          ignorePropertyModificationsFor: ['draft'],
        },
      ],
      '@typescript-eslint/array-type': 'error',
      '@typescript-eslint/no-inferrable-types': 'error',
      '@typescript-eslint/no-non-null-assertion': 'error',
      '@typescript-eslint/ban-types': [
        'error',
        {
          types: {
            Node: 'Node is disabled, use HTMLElement',
          },
        },
      ],
      '@typescript-eslint/await-thenable': 'error',
      '@typescript-eslint/no-for-in-array': 'error',
      '@typescript-eslint/no-unnecessary-type-arguments': 'error',
      '@typescript-eslint/no-unnecessary-type-assertion': 'error',
      '@typescript-eslint/consistent-type-assertions': [
        'error',
        {
          assertionStyle: 'as',
        },
      ],
      '@typescript-eslint/prefer-nullish-coalescing': 'error',
      '@typescript-eslint/switch-exhaustiveness-check': 'error',
      '@typescript-eslint/restrict-plus-operands': 'error',
      '@typescript-eslint/prefer-for-of': 'error',
      '@typescript-eslint/no-extra-non-null-assertion': 'error',
      '@typescript-eslint/no-non-null-asserted-optional-chain': 'error',
      '@typescript-eslint/prefer-optional-chain': 'error',
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/require-await': 'error',
      'unicorn/filename-case': [
        'error',
        {
          case: 'kebabCase',
        },
      ],
    },
  },
  eslintConfigPrettier,
  eslintPluginPrettierRecommended,
])

额外说明 #

• 调整配置顺序，避免传统配置覆盖Flat Config的规则；
• 移除重复的插件导入，精简代码；
• 在parserOptions中明确开启JSX支持，确保React相关规则正常生效。

内容的提问来源于stack exchange，提问作者abduv