typescript-eslint 如何对指定文件禁用类型感知 lint？

typescript-eslint 如何对指定文件禁用类型感知 lint？

【免费下载链接】typescript-eslint:sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-eslint

项目已经启用了类型感知 lint（配置了recommendedTypeChecked、stylisticTypeChecked等 TypeChecked 预设，并开启了parserOptions.projectService），但你只希望对某一部分文件关掉类型感知检查——比如*.js文件、配置文件或生成代码。这类场景在 Typed Linting 排查文档中是明确的官方问题："How do I disable type-checked linting for a file?" 以及 "How can I disable type-aware linting for a set of files?"。完成本文操作后，匹配的文件仍会被 ESLint 检查（非类型感知规则照常生效），只是不再应用任何类型感知规则；其余文件保持类型感知 lint 不变。

适用前提

按 Linting with Type Information 的说明，类型感知 lint 生效需要两个条件，本文假设你的配置已经满足：

1. 预设配置名带TypeChecked（flat config 下为tseslint.configs.recommendedTypeChecked等）；
2. parserOptions已配置projectService: true或project，让 parser 能拿到 TSConfig。

动机也来自文档：类型感知规则会要求 TypeScript 先分析整个项目，比传统 lint 规则更慢；类型感知检查依赖文件被最近的tsconfig.json包含，不在项目内的文件（如仓库脚本、.js文件）还会触发 "not found by the project service" 类报错。当某批文件不想做类型感知检查时，就按下面的方式排除它们。

主路径：用disable-type-checked共享配置

Shared Configurations 文档 中的disable-type-checked是一个 utility 配置，作用是"disable type-aware linting and all type-aware rules available in our project"，官方建议的用法正是：基础配置启用类型感知 lint，再用 overrides 对代码库中的特定子集关闭它。

Flat Config（eslint.config.mjs）

下面是 排查文档 给出的完整示例：基础配置对所有js/ts文件启用类型感知 lint，随后追加一个配置对象，把所有.js文件排除出类型感知检查。把files: ['**/*.js']换成你自己的 glob 即可——这个files匹配就是禁用范围，匹配到哪些文件，哪些文件就不再走类型感知规则。

// @ts-check import js from '@eslint/js'; import { defineConfig } from 'eslint/config'; import tseslint from 'typescript-eslint'; export default defineConfig( { files: ['**/*.{js,ts}'], extends: [ js.configs.recommended, tseslint.configs.recommendedTypeChecked, tseslint.configs.stylisticTypeChecked, ], languageOptions: { parserOptions: { projectService: true, }, }, }, { files: ['**/*.js'], extends: [tseslint.configs.disableTypeChecked], }, );

只想排除单个文件时，把files写成该文件的具体路径（如'eslint.config.mjs'）或精确 glob 即可，用法相同。

Legacy Config（.eslintrc.cjs / .eslintrc.js）

对应写法是overrides，见同一篇排查文档的 Legacy Config 示例：

module.exports = { extends: [ 'eslint:recommended', 'plugin:@typescript-eslint/recommended-type-checked', 'plugin:@typescript-eslint/stylistic-type-checked', ], plugins: ['@typescript-eslint'], parser: '@typescript-eslint/parser', parserOptions: { projectService: true, tsconfigRootDir: __dirname, }, root: true, overrides: [ { files: ['*.js'], extends: ['plugin:@typescript-eslint/disable-type-checked'], }, ], };

替代方案：在 override 中设project: false

排查文档 给出了另一条手动路径：对想排除的文件，把parserOptions.project设为false（Parser 文档 中project一节把project: false和project: null列为 "ways to disable type-aware linting (useful for overrides configs)"）。Legacy config 下写法为：

module.exports = { // ... overrides: [ { files: ['*.js'], parserOptions: { project: false, }, }, ], };

flat config 下，parserOptions位于languageOptions.parserOptions中（与上面主路径示例的结构一致），把project: false放到对应文件的配置对象里即可。两条路径都能禁用类型感知 lint，主路径的disable-type-checked还能同时关闭所有类型感知规则，是文档默认推荐的方式。

如何验证禁用生效

文档给出的验证方式很直接：改完配置后"run the same lint command you ran before"，即重跑你原有的 lint 命令（Parser 文档 中的示例命令形如npx eslint .），然后对照行为是否符合disable-type-checked的定义：

• 被files匹配到的文件：不再出现类型感知规则的报错。文档中提到的典型类型感知规则是no-unsafe-*系列（在类型过期的已知问题一节里作为类型感知规则的报告示例出现），这些规则对匹配文件应不再报告；非类型感知规则（recommended基础部分）照常报告。
• 未被匹配的文件：类型感知规则照常工作，说明禁用范围只作用于指定的filesglob。

如果匹配文件的类型感知报错没有消失，先检查filesglob 是否真的覆盖该文件——这是该方案中唯一的生效条件。

边界与注意事项

• 其他插件的类型感知规则不受此配置影响。Shared Configurations 和排查文档都明确说明：如果你使用了其他插件提供的类型感知规则，需要手动关闭这些规则，或使用那些插件自己提供的禁用配置。disable-type-checked只处理 typescript-eslint 项目内的类型感知规则。
• 该配置不属于 semver 稳定配置。disable-type-checked的启用规则和选项可能在大版本之外变化，升级 typescript-eslint 大版本后建议复查一次行为。
• 与"完全忽略文件"区分开。排查文档 的错误处理决策树中，"不 lint 这个文件"用的是 ESLint 自身的忽略机制（如ignores配置键、.eslintignore）；本文的方案是"继续 lint，但去掉类型感知"。遇到 "not found by the project service" 报错时，按文档的分支选择：文件要 lint 且要类型感知 → 把文件加进最近tsconfig.json的include，或配置projectService.allowDefaultProject；要 lint 但不要类型感知 → 用本文方案；完全不 lint → 用 ESLint 的 ignore 机制。
• 报错型场景的直接入口：当你收到 "… was not found by the project service. Consider either including it in the tsconfig.json or including it in allowDefaultProject" 或 "Having many files run with the default project is known to cause performance issues…" 这类报错，而对应文件你并不想开启类型感知 lint 时，文档指引的就是本节做法。

【免费下载链接】typescript-eslint:sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-eslint