Eslint从8.x迁移至9.x后遭遇Parsing error: "parserOptions.project"错误

云原生阿岚

2026-4-14

我太懂这种ESLint迁移后踩坑的烦躁了！你遇到的这个报错其实是ESLint 9.x和@typescript-eslint配合时的常见适配问题，咱们先把问题摆清楚，再给你几个能快速解决的办法：

首先，你运行npx eslint时碰到的具体错误是：

0:0  error  Parsing error: "parserOptions.project" has been provided for @typescript-eslint/parser.
The file was not found in any of the provided project(s): eslint.config.cjs

这个错误的核心原因很明确：当你给@typescript-eslint/parser开启了parserOptions.project（也就是让它基于你的tsconfig做类型感知的代码检查），它会要求所有被ESLint扫描到的文件，都必须在tsconfig的编译范围内。而ESLint 9.x默认会把自己的配置文件eslint.config.cjs也纳入扫描列表，但这个文件显然不在你原本的tsconfig的include规则里，所以就触发了这个解析错误。

下面是几个针对性的解决办法，按推荐程度排序：

方法一：在ESLint扁平配置里直接忽略该文件
ESLint 9.x改用了扁平配置格式，原来的.eslintignore对配置文件本身的扫描规则可能不生效了。你可以直接在eslint.config.cjs的最顶部加入忽略规则，把自身排除在扫描范围外：
```
export default [
  // 忽略规则要放在最前面，确保优先生效
  { ignores: ["./eslint.config.cjs"] },
  // 你的其他ESLint配置项（比如TS文件的解析规则、插件、自定义规则等）
];
```

方法二：给配置文件单独关闭project检查
如果不想忽略这个文件，你可以针对eslint.config.cjs单独配置，不让@typescript-eslint/parser对它启用project校验：

export default [
  // 全局的TS/TSX文件配置
  {
    files: ["**/*.ts", "**/*.tsx"],
    parser: "@typescript-eslint/parser",
    parserOptions: {
      project: "./tsconfig.json"
    },
    plugins: ["@typescript-eslint"],
    rules: {
      // 你的自定义规则配置
    }
  },
  // 单独处理ESLint配置文件
  {
    files: ["./eslint.config.cjs"],
    parserOptions: {
      project: null // 关闭该文件的project类型检查
    }
  }
];

方法三：临时调整tsconfig的include规则（不推荐）
你之前尝试修改tsconfig但没效果，可能是配置方式有问题。不过这个方法其实不推荐，因为eslint.config.cjs本身不需要被TypeScript编译，属于临时凑活的方案：
```
{
  "compilerOptions": {
    // 你的原有编译配置
  },
  "include": [
    "src/**/*",
    "eslint.config.cjs"
  ]
}
```

最后还要提醒你：ESLint 9.x的扁平配置和8.x的旧配置格式（比如.eslintrc.js）差异很大，如果你是从旧配置迁移过来的，一定要确保所有配置都转换成了扁平数组的格式，残留的旧配置逻辑也可能导致这类奇怪的报错。

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