如何用Flat配置调用ESLint 9.x？迁移后CLI调用异常求助

一、确认配置文件基础规范 #

• 确保eslint.config.js放在项目根目录（与package.json同级），文件名无拼写错误（必须是.js后缀，若使用ES模块或CommonJS，需对应改为.mjs或.cjs）。
• 配置文件必须导出数组格式的配置（ESLint 9不再支持单对象配置），基础示例：

  import globals from "globals";
  import tseslint from "typescript-eslint";
  
  export default [
    {
      files: ["src/**/*.ts"],
      ignores: ["**/*.d.ts"], // 可选：排除类型声明文件
      languageOptions: {
        globals: globals.node,
        parser: tseslint.parser,
        parserOptions: { project: "./tsconfig.json" }
      },
      plugins: { "@typescript-eslint": tseslint.plugin },
      rules: {
        "@typescript-eslint/no-unused-vars": "error"
      }
    }
  ];
  

二、正确的CLI调用命令 #

ESLint 9的CLI逻辑与8.x有差异，针对你的场景，有效命令如下：

• 直接指定目标TS文件（注意不同终端的引号规则）：

  # Linux/macOS终端
  eslint 'src/**/*.ts'
  # Windows命令行/PowerShell
  eslint "src/**/*.ts"
  

• 扫描整个项目（会自动匹配配置中的files规则）：

  eslint .
  

• 若配置文件不在根目录，必须用--config指定路径：

  eslint src/**/*.ts --config ./configs/eslint.config.js
  

三、修复files/ignores不生效问题 #

• files和ignores必须是配置数组内具体配置对象的属性，不能作为顶级项：
  ❌ 错误写法：

  export default [
    files: ["src/**/*.ts"], // 错误：顶级不能直接写属性
    { rules: {} }
  ];
  

  ✅ 正确写法：

  export default [
    {
      files: ["src/**/*.ts"],
      ignores: ["src/**/*.test.ts"], // 仅对当前配置块生效的忽略规则
      // 其他配置项...
    }
  ];
  

• 不要将eslint.config.js加入ignores，否则ESLint无法读取配置文件，直接导致加载失败。
• CLI命令中避免重复添加--ignore-pattern，否则会覆盖配置文件内的ignores规则。

四、排查配置加载故障 #

• 启用调试日志，查看ESLint加载配置的详细过程：

  eslint src/**/*.ts --debug
  

  日志会显示ESLint尝试加载的配置文件路径、匹配的文件列表等信息，快速定位问题。
• 确保依赖版本兼容：ESLint 9要求typescript-eslint版本≥7.x，执行以下命令更新依赖：

  npm install eslint@latest @typescript-eslint/eslint-plugin@latest @typescript-eslint/parser@latest typescript@latest --save-dev
  

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