TypeScript-ESLint 类型化代码检查疑难解答指南

TypeScript-ESLint 类型化代码检查疑难解答指南

typescript-eslint :sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript 项目地址: https://gitcode.com/gh_mirrors/ty/typescript-eslint

编辑器中的ESLint报告在文件变更后失效

在使用VS Code等编辑器时，可能会遇到一个已知问题：当磁盘上的文件多次更新后，类型化代码检查结果会变得过时。这是因为ESLint没有提供机制让编辑器感知跨文件依赖关系（如类型信息），导致当导入的文件发生变化时，当前文件无法获取最新的类型信息。

常见表现包括：

• 对any类型或错误类型值的不准确no-unsafe-*规则警告
• 其他规则可能产生更隐蔽的错误判断

临时解决方案：当发现类型信息过时时，在VS Code中执行Restart ESLint Server命令（或其他编辑器的等效操作）。

如何为特定文件禁用类型检查

可以通过ESLint的配置对象结合disable-type-checked配置来禁用特定文件或文件类型的类型检查。

禁用所有.js文件的类型检查

扁平配置方式

import tseslint from 'typescript-eslint';

export default tseslint.config(
  // 其他配置...
  {
    files: ['**/*.js'],
    extends: [tseslint.configs.disableTypeChecked],
  }
);

传统配置方式

module.exports = {
  // 其他配置...
  overrides: [
    {
      extends: ['plugin:@typescript-eslint/disable-type-checked'],
      files: ['./**/*.js'],
    },
  ],
};

替代方案：也可以为特定文件设置parserOptions: { project: false }来禁用类型检查。

类型信息不一致问题排查

当规则报告的类型信息与你的预期不符时（如变量被错误地判断为any或非空），建议：

1. 首先在IDE中悬停查看变量类型
2. 如果IDE显示的类型与规则报告一致，说明需要修正类型声明
3. 如果显示不一致，检查以下配置是否一致：
   • TypeScript版本
   • 类型检查编译器选项
   • 项目包含的文件范围

常见案例：当类型声明文件未被包含在项目中时，类型会退化为any，触发no-unsafe-*规则。

项目服务(Project Service)相关问题

parserOptions.projectService是v8版本后推荐的类型检查配置方式，它强制使用与编辑器相同的tsconfig.json文件生成类型信息。

文件未被项目服务找到的解决方案

当遇到"文件未被项目服务找到"错误时：

1. 不想检查该文件：使用ESLint的忽略配置
2. 想检查但不需类型信息：禁用该文件的类型检查
3. 需要完整类型检查：
   • 将文件添加到最近的tsconfig.json的include中
   • 少量文件可使用allowDefaultProject选项
   • 复杂情况可回退到parserOptions.project

注意：

• TSConfig默认不包含.js文件，需要启用allowJs或checkJs
• 项目服务只识别tsconfig.json文件

性能警告处理

当出现"默认项目包含过多文件导致性能问题"警告时，表明有大量文件未包含在tsconfig.json中。建议：

1. 将文件添加到最近的tsconfig.json
2. 或改用parserOptions.project进行更精细的控制

传统项目配置问题

文件未被TSConfig包含的解决方案

当ESLint配置要求为未被TSConfig包含的文件生成类型信息时：

1. 不想检查该文件：使用.eslintignore或ignorePatterns
2. 想检查但不需类型信息：使用disable-type-checked配置
3. 需要完整类型检查：
   • 检查TSConfig的include选项
   • 为特殊文件（如脚本）创建单独的tsconfig.eslint.json

TSConfig自定义配置

虽然不推荐，但可以通过parserOptions.project自定义TSConfig：

// 扁平配置示例
export default tseslint.config({
  languageOptions: {
    parserOptions: {
      project: './tsconfig.eslint.json',
      tsconfigRootDir: import.meta.dirname,
    },
  },
});

注意：在monorepo项目中，有特殊的配置考虑因素。

通过以上方法，可以解决TypeScript-ESLint在类型化代码检查过程中遇到的大部分常见问题，确保类型检查结果准确且与开发环境保持一致。

typescript-eslint :sparkles: Monorepo for all the tooling which enables ESLint to support TypeScript 项目地址: https://gitcode.com/gh_mirrors/ty/typescript-eslint