typescript-eslint

typescript-eslint - 快速参考

何时使用此技能

• 为 TypeScript 项目配置 ESLint
• 使用面向类型的 TypeScript 规则
• 从 TSLint 迁移

何时不使用此技能

• 完整的 ESLint 9 配置 - 使用 eslint-biome 技能进行完整配置
• Biome 代码检查器 - 使用 eslint-biome 技能配置 Biome
• 代码质量原则 - 使用 quality-common 学习 SOLID／整洁代码
• Java/Kotlin - 使用 sonarqube 技能处理 JVM 语言

深入了解：使用 mcp__documentation__fetch_docs，并将 technology 设为 typescript-eslint，以获取完整文档。

基本设置

npm install -D eslint typescript-eslint

Flat Config（ESLint 9+）

eslint.config.mjs

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
);

面向类型的代码检查

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

严格配置

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
);

常用规则

{
  rules: {
    // Prevent unused variables
    '@typescript-eslint/no-unused-vars': ['error', {
      argsIgnorePattern: '^_'
    }],

    // Require explicit return types
    '@typescript-eslint/explicit-function-return-type': 'warn',

    // Prevent any usage
    '@typescript-eslint/no-explicit-any': 'error',

    // Require await in async functions
    '@typescript-eslint/require-await': 'error',

    // Prevent floating promises
    '@typescript-eslint/no-floating-promises': 'error',

    // Consistent type imports
    '@typescript-eslint/consistent-type-imports': 'error',
  }
}

针对特定文件的规则

export default tseslint.config(
  // ... base config
  {
    files: ['**/*.test.ts', '**/*.spec.ts'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
  {
    files: ['**/*.js'],
    ...tseslint.configs.disableTypeChecked,
  },
);

反模式

反模式	不良影响	正确做法
不使用面向类型的规则	无法发现 Promise、异步相关问题	使用 recommendedTypeChecked
到处允许 any	违背 TypeScript 的初衷	设置 no-explicit-any: error
没有 require-await 规则	使用不必要的 async 关键字	启用面向类型的异步规则
对 JS 文件进行类型检查	JS 没有类型	对 .js 使用 disableTypeChecked
在测试文件中禁用规则	测试同样需要保证质量	仅在需要时禁用 no-explicit-any
忽略未使用的变量	代码异味、未使用的导入	使用带忽略模式的 no-unused-vars

快速故障排除

问题	可能原因	解决方案
面向类型的规则不起作用	缺少 projectService: true	添加到 languageOptions.parserOptions
代码检查非常慢	对所有文件进行类型检查	仅将类型规则限制在 **/*.ts
到处出现“Unsafe”错误	严格类型检查	使用 strictTypeChecked 或禁用特定规则
未捕获 Promise 错误	缺少 no-floating-promises	在 recommendedTypeChecked 预设中启用
未检测到未使用的导入	规则配置错误	使用 @typescript-eslint/no-unused-vars
规则与 Prettier 冲突	两者都在格式化代码	最后添加 eslint-config-prettier