eslint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ESLint Agent

Overview

概述

ESLint is a pluggable and configurable linter tool for identifying and reporting on patterns in JavaScript and TypeScript code. This skill enables Claude to help you set up, configure, and effectively use ESLint to maintain code quality across your projects.

ESLint是一款可插拔、可配置的代码检查工具，用于识别和报告JavaScript与TypeScript代码中的模式问题。本技能能让Claude协助你搭建、配置并高效使用ESLint，以维护项目的代码质量。

Quick Start

快速开始

Prerequisites

前置条件

Node.js (^18.18.0, ^20.9.0, or >=21.1.0) with SSL support
Existing
```
package.json
```
file (run
```
npm init
```
if needed)

Node.js (^18.18.0, ^20.9.0, 或 >=21.1.0) 且支持SSL
已存在
```
package.json
```
文件（若没有可运行
```
npm init
```
）

Installation & Setup

安装与配置

Automated Setup (Recommended):

bash

npm init @eslint/config@latest

This interactive setup will ask about your project and create an

eslint.config.js

file.

Manual Setup:

bash

undefined

自动配置（推荐）：

bash

npm init @eslint/config@latest

这个交互式配置流程会询问项目相关信息，并生成

eslint.config.js

文件。

手动配置：

bash

undefined

Install ESLint packages

安装ESLint包

npm install --save-dev eslint@latest @eslint/js@latest

Create configuration file

创建配置文件

touch eslint.config.js

undefined

touch eslint.config.js

undefined

Basic Configuration

基础配置

The new flat config format (ESLint 9.0+) uses

eslint.config.js

javascript

import { defineConfig } from "eslint/config";
import js from "@eslint/js";

export default defineConfig([
  {
    files: ["**/*.js"],
    plugins: { js },
    extends: ["js/recommended"],
    rules: {
      "no-unused-vars": "warn",
      "no-undef": "warn"
    }
  }
]);

ESLint 9.0+ 引入的新扁平化配置格式使用

eslint.config.js

：

javascript

import { defineConfig } from "eslint/config";
import js from "@eslint/js";

export default defineConfig([
  {
    files: ["**/*.js"],
    plugins: { js },
    extends: ["js/recommended"],
    rules: {
      "no-unused-vars": "warn",
      "no-undef": "warn"
    }
  }
]);

Running ESLint

运行ESLint

bash

undefined

bash

undefined

Lint a single file

检查单个文件

npx eslint yourfile.js

Lint a directory

检查目录

npx eslint src/

Lint with auto-fix

检查并自动修复问题

npx eslint src/ --fix

undefined

npx eslint src/ --fix

undefined

Core ESLint Tasks

ESLint核心任务

1. Setting Up ESLint

1. 搭建ESLint

For JavaScript Projects

针对JavaScript项目

bash

npm init @eslint/config@latest

Select options:

How would you like to use ESLint? → To check syntax, find problems, and enforce code style
What type of modules? → JavaScript modules (import/export)
Which framework? → None/React/Vue (as applicable)
Does your project use TypeScript? → No
Where does your code run? → Browser and/or Node
Config file format → JavaScript/JSON/YAML (JavaScript recommended)

bash

npm init @eslint/config@latest

选择以下选项：

你希望如何使用ESLint？→ 检查语法、发现问题并强制执行代码风格
使用哪种模块类型？→ JavaScript模块（import/export）
使用哪种框架？→ 无/React/Vue（根据项目选择）
项目是否使用TypeScript？→ 否
代码运行环境？→ 浏览器 和/或 Node.js
配置文件格式 → JavaScript/JSON/YAML（推荐JavaScript）

For TypeScript Projects

针对TypeScript项目

bash

npm install --save-dev eslint@latest @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript-eslint

Configuration for TypeScript:

javascript

import { defineConfig } from 'eslint/config';
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

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

bash

npm install --save-dev eslint@latest @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript-eslint

TypeScript配置示例：

javascript

import { defineConfig } from 'eslint/config';
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

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

For React + TypeScript

针对React + TypeScript项目

bash

npm install --save-dev \
  eslint \
  @typescript-eslint/parser \
  @typescript-eslint/eslint-plugin \
  eslint-plugin-react \
  eslint-plugin-react-hooks \
  eslint-plugin-jsx-a11y \
  typescript-eslint

bash

npm install --save-dev \
  eslint \
  @typescript-eslint/parser \
  @typescript-eslint/eslint-plugin \
  eslint-plugin-react \
  eslint-plugin-react-hooks \
  eslint-plugin-jsx-a11y \
  typescript-eslint

2. Configuring Rules

2. 配置规则

Rule Severity Levels

规则严重级别

```
"off"
```
or
```
0
```
- Disable the rule
```
"warn"
```
or
```
1
```
- Warning (doesn't affect exit code)
```
"error"
```
or
```
2
```
- Error (exit code will be 1)

```
"off"
```
或
```
0
```
- 禁用规则
```
"warn"
```
或
```
1
```
- 警告（不影响退出码）
```
"error"
```
或
```
2
```
- 错误（退出码为1）

Common Rule Configurations

常用规则配置

Basic Rules:

javascript

export default defineConfig([
  {
    rules: {
      // Enforce semicolons
      "semi": ["error", "always"],

      // Enforce const where possible
      "prefer-const": "error",

      // Warn on unused variables
      "no-unused-vars": "warn",

      // No console.log in production
      "no-console": ["error", { allow: ["warn", "error"] }],

      // Enforce consistent quotes
      "quotes": ["error", "single"],

      // Require === instead of ==
      "eqeqeq": ["error", "always"]
    }
  }
]);

TypeScript-Specific Rules:

javascript

export default defineConfig([
  {
    files: ["**/*.ts", "**/*.tsx"],
    rules: {
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/explicit-function-return-type": ["error", {
        allowExpressions: true
      }],
      "@typescript-eslint/naming-convention": ["error", {
        selector: "interface",
        format: ["PascalCase"],
        custom: {
          regex: "^I[A-Z]",
          match: false
        }
      }]
    }
  }
]);

基础规则：

javascript

export default defineConfig([
  {
    rules: {
      // 强制使用分号
      "semi": ["error", "always"],

      // 尽可能使用const
      "prefer-const": "error",

      // 未使用变量警告
      "no-unused-vars": "warn",

      // 生产环境禁止console.log
      "no-console": ["error", { allow: ["warn", "error"] }],

      // 强制一致的引号风格
      "quotes": ["error", "single"],

      // 要求使用===而非==
      "eqeqeq": ["error", "always"]
    }
  }
]);

TypeScript专属规则：

javascript

export default defineConfig([
  {
    files: ["**/*.ts", "**/*.tsx"],
    rules: {
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/explicit-function-return-type": ["error", {
        allowExpressions: true
      }],
      "@typescript-eslint/naming-convention": ["error", {
        selector: "interface",
        format: ["PascalCase"],
        custom: {
          regex: "^I[A-Z]",
          match: false
        }
      }]
    }
  }
]);

Configuration Comments

配置注释

Disable rules inline:

javascript

/* eslint-disable no-console */
console.log('This is allowed');
/* eslint-enable no-console */

// Disable for single line
console.log('Debug'); // eslint-disable-line no-console

// Disable next line
// eslint-disable-next-line no-console
console.log('Debug');

// Disable specific rules
alert('foo'); // eslint-disable-line no-alert, no-undef

Best Practices for Inline Disables:

Use sparingly with clear justification

Document the reason:

javascript

// eslint-disable-next-line no-console -- Debugging production issue #1234
console.log('User data:', userData);

Prefer configuration file changes over inline disables
Create follow-up tasks for temporary disables

在代码中禁用规则：

javascript

/* eslint-disable no-console */
console.log('This is allowed');
/* eslint-enable no-console */

// 禁用单行规则
console.log('Debug'); // eslint-disable-line no-console

// 禁用下一行规则
// eslint-disable-next-line no-console
console.log('Debug');

// 禁用特定规则
alert('foo'); // eslint-disable-line no-alert, no-undef

内联禁用的最佳实践：

谨慎使用并附上明确理由

记录原因：

javascript

// eslint-disable-next-line no-console -- 调试生产环境问题 #1234
console.log('User data:', userData);

优先修改配置文件而非内联禁用
为临时禁用创建后续处理任务

3. File Patterns and Ignores

3. 文件模式与忽略规则

Specifying Files to Lint

指定要检查的文件

javascript

export default defineConfig([
  {
    // Only lint TypeScript files in src/
    files: ["src/**/*.ts", "src/**/*.tsx"],

    // Ignore test files for certain rules
    ignores: ["**/*.test.ts", "**/*.spec.ts"]
  }
]);

javascript

export default defineConfig([
  {
    // 仅检查src/目录下的TypeScript文件
    files: ["src/**/*.ts", "src/**/*.tsx"],

    // 忽略测试文件的某些规则
    ignores: ["**/*.test.ts", "**/*.spec.ts"]
  }
]);

Global Ignores

全局忽略

javascript

export default defineConfig([
  {
    ignores: [
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/.next/**",
      "**/coverage/**"
    ]
  },
  // ... rest of config
]);

javascript

export default defineConfig([
  {
    ignores: [
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/.next/**",
      "**/coverage/**"
    ]
  },
  // ... 其余配置
]);

4. Using Shared Configurations

4. 使用共享配置

ESLint supports extending from popular configurations:

javascript

import { defineConfig } from "eslint/config";
import js from "@eslint/js";
import globals from "globals";

export default defineConfig([
  js.configs.recommended, // ESLint recommended rules
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
      }
    }
  }
]);

Popular Shared Configs:

```
eslint:recommended
```
- ESLint's recommended rules
```
@typescript-eslint/recommended
```
- TypeScript recommended
```
@typescript-eslint/strict
```
- Stricter TypeScript rules
```
plugin:react/recommended
```
- React best practices
```
plugin:react-hooks/recommended
```
- React Hooks rules

ESLint支持扩展流行的共享配置：

javascript

import { defineConfig } from "eslint/config";
import js from "@eslint/js";
import globals from "globals";

export default defineConfig([
  js.configs.recommended, // ESLint推荐规则
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
      }
    }
  }
]);

热门共享配置：

```
eslint:recommended
```
- ESLint官方推荐规则
```
@typescript-eslint/recommended
```
- TypeScript推荐规则
```
@typescript-eslint/strict
```
- 更严格的TypeScript规则
```
plugin:react/recommended
```
- React最佳实践规则
```
plugin:react-hooks/recommended
```
- React Hooks规则

5. Auto-Fixing Issues

5. 自动修复问题

ESLint can automatically fix many issues:

bash

undefined

ESLint可自动修复许多问题：

bash

undefined

Fix all auto-fixable issues

修复所有可自动修复的问题

npx eslint src/ --fix

Show what would be fixed (dry run)

预览修复内容（试运行）

npx eslint src/ --fix-dry-run


**Auto-fixable rules include:**

- Formatting issues (spacing, semicolons, quotes)
- Simple code transformations (prefer-const, arrow functions)
- Import sorting

**Non-fixable issues** require manual intervention:

- Logic errors (no-unused-vars with actual usage)
- Complex refactoring needs

npx eslint src/ --fix-dry-run


**可自动修复的规则包括：**

- 格式问题（空格、分号、引号）
- 简单代码转换（优先使用const、箭头函数）
- 导入语句排序

**不可自动修复的问题**需要手动处理：

- 逻辑错误（实际使用了的变量却被标记为未使用）
- 复杂重构需求

Common Project Scenarios

常见项目场景

React + TypeScript Project

React + TypeScript项目

Complete Configuration:

javascript

import { defineConfig } from 'eslint/config';
import js from '@eslint/js';
import globals from 'globals';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
import tseslint from 'typescript-eslint';

export default defineConfig([
  { ignores: ['dist'] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
      parserOptions: {
        project: './tsconfig.json'
      }
    },
    plugins: {
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true }
      ],
      '@typescript-eslint/no-unused-vars': ['error', {
        argsIgnorePattern: '^_',
        varsIgnorePattern: '^_'
      }]
    }
  }
]);

完整配置：

javascript

import { defineConfig } from 'eslint/config';
import js from '@eslint/js';
import globals from 'globals';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
import tseslint from 'typescript-eslint';

export default defineConfig([
  { ignores: ['dist'] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
      parserOptions: {
        project: './tsconfig.json'
      }
    },
    plugins: {
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true }
      ],
      '@typescript-eslint/no-unused-vars': ['error', {
        argsIgnorePattern: '^_',
        varsIgnorePattern: '^_'
      }]
    }
  }
]);

Node.js + TypeScript Project

Node.js + TypeScript项目

javascript

import { defineConfig } from 'eslint/config';
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import globals from 'globals';

export default defineConfig([
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.ts'],
    languageOptions: {
      globals: globals.node
    },
    rules: {
      '@typescript-eslint/no-explicit-any': 'warn',
      'no-console': 'off' // Console is fine in Node.js
    }
  }
]);

javascript

import { defineConfig } from 'eslint/config';
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import globals from 'globals';

export default defineConfig([
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.ts'],
    languageOptions: {
      globals: globals.node
    },
    rules: {
      '@typescript-eslint/no-explicit-any': 'warn',
      'no-console': 'off' // Node.js中允许使用console
    }
  }
]);

Monorepo Configuration

单体仓库（Monorepo）配置

javascript

export default defineConfig([
  // Global ignores
  { ignores: ['**/dist/**', '**/build/**'] },

  // Frontend package
  {
    files: ['packages/frontend/**/*.{ts,tsx}'],
    languageOptions: {
      globals: globals.browser
    },
    // Frontend-specific rules
  },

  // Backend package
  {
    files: ['packages/backend/**/*.ts'],
    languageOptions: {
      globals: globals.node
    },
    // Backend-specific rules
  }
]);

javascript

export default defineConfig([
  // 全局忽略
  { ignores: ['**/dist/**', '**/build/**'] },

  // 前端包
  {
    files: ['packages/frontend/**/*.{ts,tsx}'],
    languageOptions: {
      globals: globals.browser
    },
    // 前端专属规则
  },

  // 后端包
  {
    files: ['packages/backend/**/*.ts'],
    languageOptions: {
      globals: globals.node
    },
    // 后端专属规则
  }
]);

Integration with Development Tools

与开发工具集成

VS Code Integration

VS Code集成

Install Extension:

ESLint extension by Microsoft (dbaeumer.vscode-eslint)

Workspace Settings (
.vscode/settings.json
):

json

{
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}

安装扩展：

Microsoft官方ESLint扩展（dbaeumer.vscode-eslint）

工作区设置（
.vscode/settings.json
）：

json

{
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}

CI/CD Integration

CI/CD集成

GitHub Actions:

yaml

name: ESLint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npx eslint .

Pre-commit Hook (with Husky):

bash

npm install --save-dev husky lint-staged

GitHub Actions：

yaml

name: ESLint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npx eslint .

提交前钩子（使用Husky）：

bash

npm install --save-dev husky lint-staged

Add to package.json

添加到package.json

{ "lint-staged": { "*.{js,jsx,ts,tsx}": ["eslint --fix", "git add"] } }

undefined

{ "lint-staged": { "*.{js,jsx,ts,tsx}": ["eslint --fix", "git add"] } }

undefined

Package.json Scripts

Package.json脚本

json

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "lint:staged": "lint-staged"
  }
}

json

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "lint:staged": "lint-staged"
  }
}

Troubleshooting

故障排除

Common Issues

常见问题

"Cannot find module 'eslint/config'"

Update to ESLint 9.0+:
```
npm install eslint@latest
```

"Parsing error: Cannot find module '@typescript-eslint/parser'"

Install parser:

npm install --save-dev @typescript-eslint/parser

Rules not being applied

Check file patterns match your source files
Verify config file is named correctly (
```
eslint.config.js
```
)
Ensure config is in project root

Slow linting in large projects

Add appropriate ignores for node_modules, dist, build folders
Use
```
--cache
```
flag:
```
npx eslint --cache .
```
Consider using
```
--max-warnings 0
```
to fail on warnings in CI

"Cannot find module 'eslint/config'"

升级到ESLint 9.0+：
```
npm install eslint@latest
```

"Parsing error: Cannot find module '@typescript-eslint/parser'"

安装解析器：

npm install --save-dev @typescript-eslint/parser

规则未生效

检查文件模式是否匹配源代码文件
验证配置文件名是否正确（
```
eslint.config.js
```
）
确保配置文件位于项目根目录

大型项目中检查速度慢

添加合适的忽略规则，排除node_modules、dist、build等文件夹
使用
```
--cache
```
参数：
```
npx eslint --cache .
```
考虑在CI中使用
```
--max-warnings 0
```
参数，使警告导致构建失败

Advanced Topics

进阶主题

Creating Custom Rules

创建自定义规则

For project-specific patterns, see

references/custom_rules.md

如需针对项目特定模式创建规则，请参考

references/custom_rules.md

。

TypeScript Type-Aware Linting

TypeScript类型感知检查

For advanced TypeScript checks requiring type information, see

references/type_aware_linting.md

如需需要类型信息的高级TypeScript检查，请参考

references/type_aware_linting.md

。

Migration from ESLint 8.x

从ESLint 8.x迁移

For projects using the legacy

.eslintrc.*

format, see

references/migration_guide.md

对于使用旧版

.eslintrc.*

格式的项目，请参考

references/migration_guide.md

。

Resources

资源

references/

```
custom_rules.md
```
- Guide to creating custom ESLint rules
```
type_aware_linting.md
```
- TypeScript type-aware linting configuration
```
migration_guide.md
```
- Migrating from ESLint 8.x to 9.x flat config
```
rule_reference.md
```
- Comprehensive rule reference with examples

```
custom_rules.md
```
- 创建自定义ESLint规则指南
```
type_aware_linting.md
```
- TypeScript类型感知检查配置
```
migration_guide.md
```
- 从ESLint 8.x迁移到9.x扁平化配置指南
```
rule_reference.md
```
- 包含示例的全面规则参考

assets/

```
eslint.config.js
```
- Complete example configuration for various project types
```
.eslintignore
```
- Example ignore file patterns

```
eslint.config.js
```
- 适用于各类项目的完整配置示例
```
.eslintignore
```
- 忽略文件模式示例