typescript-eslint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

typescript-eslint - Quick Reference

typescript-eslint - 快速参考

When to Use This Skill

何时使用此技能

Configure ESLint for TypeScript projects
Type-aware rules for TypeScript
Migration from TSLint

为TypeScript项目配置ESLint
TypeScript的类型感知规则
从TSLint迁移

When NOT to Use This Skill

何时不使用此技能

Full ESLint 9 setup - Use
```
eslint-biome
```
skill for complete configuration
Biome linter - Use
```
eslint-biome
```
skill for Biome setup
Code quality principles - Use
```
quality-common
```
for SOLID/Clean Code
Java/Kotlin - Use
```
sonarqube
```
skill for JVM languages

Deep Knowledge: Use
mcp__documentation__fetch_docs
with technology:
typescript-eslint
for comprehensive documentation.

完整ESLint 9配置 - 完整配置请使用
```
eslint-biome
```
技能
Biome linter - Biome配置请使用
```
eslint-biome
```
技能
代码质量原则 - SOLID/整洁代码相关请使用
```
quality-common
```
技能
Java/Kotlin - JVM语言相关请使用
```
sonarqube
```
技能

深度知识：如需获取完整文档，可调用
mcp__documentation__fetch_docs
，指定technology参数为
typescript-eslint
。

Basic Setup

基础配置

bash

npm install -D eslint typescript-eslint

bash

npm install -D eslint typescript-eslint

Flat Config (ESLint 9+)

eslint.config.mjs

javascript

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

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

javascript

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

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

Type-Aware Linting

类型感知Linting

javascript

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,
      },
    },
  },
);

javascript

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,
      },
    },
  },
);

Strict Configuration

严格配置

javascript

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

javascript

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

Common Rules

常见规则

javascript

{
  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',
  }
}

javascript

{
  rules: {
    // 防止未使用变量
    '@typescript-eslint/no-unused-vars': ['error', {
      argsIgnorePattern: '^_'
    }],

    // 要求显式定义返回类型
    '@typescript-eslint/explicit-function-return-type': 'warn',

    // 禁止使用any类型
    '@typescript-eslint/no-explicit-any': 'error',

    // 要求异步函数中使用await
    '@typescript-eslint/require-await': 'error',

    // 禁止浮动Promise
    '@typescript-eslint/no-floating-promises': 'error',

    // 统一类型导入方式
    '@typescript-eslint/consistent-type-imports': 'error',
  }
}

File-Specific Rules

特定文件规则

javascript

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

javascript

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

Anti-Patterns

反模式

Anti-Pattern	Why It's Bad	Correct Approach
Not using type-aware rules	Misses Promise, async issues	Use `recommendedTypeChecked`
Allowing `any` everywhere	Defeats TypeScript purpose	Set `no-explicit-any: error`
No `require-await` rule	Unnecessary async keywords	Enable type-aware async rules
Type checking JS files	JS has no types	Use `disableTypeChecked` for .js
Disabling rules in test files	Tests need quality too	Only disable `no-explicit-any` if needed
Ignoring unused variables	Code smell, unused imports	Use `no-unused-vars` with ignore pattern

反模式	危害	正确做法
不使用类型感知规则	遗漏Promise、异步相关问题	使用 `recommendedTypeChecked`
随处允许使用 `any` 类型	失去TypeScript的类型保护意义	设置 `no-explicit-any: error`
未启用 `require-await` 规则	存在不必要的async关键字	启用类型感知异步相关规则
对JS文件开启类型检查	JS本身没有类型定义	对.js文件使用 `disableTypeChecked`
在测试文件中禁用所有规则	测试代码同样需要保证质量	仅在必要时禁用 `no-explicit-any`
忽略未使用变量	代码异味、存在无用导入	配合忽略规则使用 `no-unused-vars`

Quick Troubleshooting

快速故障排查

Issue	Likely Cause	Solution
Type-aware rules not working	Missing `projectService: true`	Add to languageOptions.parserOptions
Linting very slow	Type checking all files	Limit type rules to `*/.ts` only
"Unsafe" errors everywhere	Strict type checking	Use `strictTypeChecked` or disable specific rules
Promise errors not caught	Missing `no-floating-promises`	Enable in recommendedTypeChecked preset
Unused imports not detected	Wrong rule configuration	Use `@typescript-eslint/no-unused-vars`
Rules conflict with Prettier	Both formatting code	Add `eslint-config-prettier` last

问题	可能原因	解决方案
类型感知规则不生效	缺失 `projectService: true` 配置	在languageOptions.parserOptions中添加该配置
Linting速度极慢	对所有文件都执行类型检查	仅对 `*/.ts` 文件启用类型规则
到处出现“不安全”报错	启用了严格类型检查	使用 `strictTypeChecked` 或禁用特定规则
Promise相关错误未被捕获	未启用 `no-floating-promises` 规则	在recommendedTypeChecked预设中开启该规则
未检测到未使用的导入	规则配置错误	使用 `@typescript-eslint/no-unused-vars` 规则
规则与Prettier冲突	两者同时处理代码格式化	最后添加 `eslint-config-prettier` 配置