ESLint 9中如何在特定文件的配置覆盖中整合多个外部配置（避免手动合并规则冲突）

阿华AIGC实验室

2026-4-14

我完全懂你这种头疼的感觉——从ESLint 8及以前的overrides+字符串extends切换到ESLint 9的扁平配置，最让人挠头的就是怎么在特定文件组里优雅整合多个外部配置，还不用手动去解决规则冲突。你遇到的对象展开直接覆盖规则的问题，本质是因为普通的对象展开只会做浅合并，同名的嵌套属性（比如rules）会被后面的完全替换，而不是递归合并。

给你几个实用的解决方案，按易用性和官方推荐度排序：

方案一：用ESLint官方的`deepMerge`工具（首推）

ESLint官方专门为扁平配置提供了@eslint/js包的deepMerge方法，它会智能递归合并所有嵌套配置项（规则、插件、设置等），不会直接覆盖，完美解决你的冲突问题。

步骤：

先确保安装了@eslint/js（如果没装，执行npm install @eslint/js --save-dev）
导入deepMerge，把需要合并的配置对象传进去即可

代码示例：

import { deepMerge } from '@eslint/js';
import prettier from 'eslint-config-prettier';
import airbnb from 'eslint-config-airbnb';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';

// 递归合并react的两个配置，保留所有规则
const reactCombinedConfig = deepMerge(
  react.configs.flat['jsx-runtime'],
  reactHooks.configs.recommended
);

export default [
  // 基础全局配置：合并airbnb和prettier（prettier放后面，优先禁用冲突规则）
  deepMerge(airbnb, prettier),
  // JSX文件专属配置：在合并后的react配置基础上添加文件匹配规则
  {
    ...reactCombinedConfig,
    files: ['*.jsx']
  }
];

说明：

deepMerge会自动处理：

合并两个配置的rules对象，同名规则以后面的配置为准（和旧版extends的优先级逻辑一致）
合并plugins、settings、env等嵌套属性
不会丢失任何配置项，比手动合并靠谱多了

方案二：用扁平配置的数组特性拆分配置块

ESLint 9的扁平配置本身就是一个数组，每个数组项都是独立的配置块，ESLint会按顺序自动合并所有配置块。你可以把多个外部配置拆成单独的数组项，再给它们加上相同的files匹配条件。

代码示例：

import prettier from 'eslint-config-prettier';
import airbnb from 'eslint-config-airbnb';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';

export default [
  // 基础全局配置：先加载airbnb，再加载prettier（prettier后加载，禁用冲突规则）
  airbnb,
  prettier,
  // JSX文件专属配置1：react/jsx-runtime规则
  {
    ...react.configs.flat['jsx-runtime'],
    files: ['*.jsx']
  },
  // JSX文件专属配置2：react-hooks推荐规则（后加载，同名规则会覆盖前者）
  {
    ...reactHooks.configs.recommended,
    files: ['*.jsx']
  }
];

说明：

这种方法不需要额外工具，逻辑非常直观：

每个配置块独立，ESLint会自动合并所有匹配当前文件的配置块
数组顺序决定优先级：后面的配置块规则会覆盖前面的，和旧版extends的数组顺序逻辑一致
适合配置块之间冲突较少的场景，调试起来也更方便

方案三：手动合并嵌套属性（适合精细控制的场景）

如果你需要精确控制哪些配置项被合并、哪些被覆盖，可以手动递归合并嵌套属性，比如单独合并rules、plugins、settings等。

代码示例：

import prettier from 'eslint-config-prettier';
import airbnb from 'eslint-config-airbnb';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';

// 提取需要合并的两个react配置
const reactJsxConfig = react.configs.flat['jsx-runtime'];
const reactHooksConfig = reactHooks.configs.recommended;

export default [
  // 基础配置用官方deepMerge省事儿
  deepMerge(airbnb, prettier),
  // JSX文件专属配置：手动合并所有嵌套项
  {
    files: ['*.jsx'],
    // 合并规则：react-hooks规则优先覆盖同名规则
    rules: {
      ...reactJsxConfig.rules,
      ...reactHooksConfig.rules
    },
    // 合并插件
    plugins: {
      ...reactJsxConfig.plugins,
      ...reactHooksConfig.plugins
    },
    // 合并设置
    settings: {
      ...reactJsxConfig.settings,
      ...reactHooksConfig.settings
    }
  }
];

说明：

这种方法最灵活，但也最繁琐，适合你需要精确控制某些规则优先级的场景。不过一般不推荐，因为很容易漏掉env、globals等嵌套配置项，不如官方的deepMerge省心。

几个关键注意事项：

配置顺序至关重要：不管用哪种方法，ESLint都会按配置块的顺序应用规则，后面的配置会覆盖前面的。比如prettier一定要放在airbnb后面，因为prettier需要禁用那些和格式化冲突的ESLint规则。
确保外部配置支持扁平格式：大部分主流ESLint配置（比如airbnb、prettier、react）现在都支持扁平格式的导出，但如果遇到旧的配置，可以用eslint-flat-config-utils包的convertLegacyConfig工具把旧的extends格式转成扁平配置。

备注：内容来源于stack exchange，提问作者trysis