网站导航
> 技术文档 > ESLint9 基础_eslint 9

ESLint9 基础_eslint 9

网友: 技术文档 2025-07-30 21:30:39

一、安装

可以使用如下命令快速安装及配置ESLint

pnpm create @eslint/config@latest# 或者使用特定的共享配置来配置ESLint# use `eslint-config-xo` shared config - npm 7+pnpm create @eslint/config@latest -- --config eslint-config-xo

当运行完以上安装命令后，会询问应该如何使用ESLint，并在文件夹中生成一个eslint.config.js (or eslint.config.mjs)的配置文件

最后在文件或者文件夹上使用ESLint

pnpm dlx eslint yourfile.js

也可以按照如下步骤进行手动安装

1、Install the ESLint packages in your project:

pnpm add --save-dev eslint@latest @eslint/js@latest

2、Add an eslint.config.js file.

3、Add configuration to the eslint.config.js file.

4、Lint code using the ESLint CLI

pnpm dlx eslint project-dir/ file.js

二、核心概念

Core Concepts

规则

Rules

规则是 ESLint 的核心构建块。规则会验证 你的代码是否符合预期，以及如果不符合预期该怎么做。规则还可以包含针对该规则的额外配置项。

配置文件

Configuration Files

ESLint 配置文件是指项目中存储 ESLint 配置的地方。可以包括内置规则、想要强制执行的内容、具有自定义规则的插件、可共享的配置，你希望规则适用于哪些文件等等。

可共享配置

Shareable Configurations

可共享配置是指通过 npm 分享的 ESLint 配置。

插件

Plugins

ESLint 插件是一个包含 ESLint 规则、配置、解析器和环境变量的集合的 npm 模块。

解析器

Parsers

ESLint 解析器将代码转换为 ESLint 可以评估的抽象语法树（AST, abstract syntax tree）。默认情况下，ESLint 使用内置的与标准 JavaScript运行时和版本兼容的 Espree 解析器。

自定义处理器

Custom Processors

ESLint 处理器可以从其他类型的文件中提取 JavaScript 代码，然后让 ESLint 对 JavaScript 代码进行检查。另外，你也可以在用 ESLint 解析 JavaScript 代码之前使用处理器先对其进行处理。

格式化工具

Formatters

ESLint 格式化工具决定了命令行输出的检查结果的样子。

集成

Integrations

ESLint 相关集成生态是使 ESLint 成为如此有用的工具的原因之一。

三、配置 ESLint  

Configure ESLint

 ESLint 中可配置的选项：

  • 全局变量 Globals  - 脚本在执行过程中需要用到的额外全局变量。
  • 规则 Rules  - 启用了哪些规则，它们又是什么级别错误水平
  • 插件 Plugins  - 第三方插件为 ESLint 定义了额外的规则、环境、配置等。

1、配置文件

Configuration File

配置文件格式

Configuration File Format

ESLint 配置文件可以命名为以下任何一种名称：

  • eslint.config.js
  • eslint.config.mjs
  • eslint.config.cjs
  • eslint.config.ts (requires additional setup)
  • eslint.config.mts (requires additional setup)
  • eslint.config.cts (requires additional setup)

它应放置在您的项目的根目录下，并导出一个配置对象数组。以下是一个示例：

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{rules: {semi: \"error\",\"prefer-const\": \"error\",},},]);

在这个示例中，使用了 defineConfig() 辅助函数来定义一个仅包含一个配置对象的配置数组。该配置对象启用了两条规则：semi 和 prefer-const。这些规则会应用于使用此配置文件的 ESLint 处理的所有文件。

配置对象

Configuration Objects

每个配置对象都包含了 ESLint 执行一组文件所需的所有信息。每个配置对象由以下这些属性组成：

  • name
    • 名称 —— 用于配置对象的名称。此名称在错误消息和配置检查器中使用，以便帮助识别正在使用的具体配置对象。（命名规范）
  • files
    • 文件 —— 一个包含通配符模式的数组，用于指示配置对象应应用于的文件。若未指定，则该配置对象将适用于任何其他配置对象所匹配的所有文件。
  • ignores
    • 忽略 —— 一个包含通配符模式的数组，用于指示配置对象不应应用于的文件。如果未指定，则配置对象将应用于由“files”匹配的所有文件。如果在配置对象中使用“ignores”但没有其他任何键，则这些模式将作为全局忽略项，并应用于每个配置对象。
  • extends
    • 继承 —— 一个包含字符串、配置对象或的数组包含额外配置信息的配置数组应用。
  • languageOptions
    • 语言选项 —— 一个包含与 JavaScript 编译规则配置相关设置的对象。
      • ecmaVersion
      • sourceType
      • globals
      • parser
      • parserOptions
  • linterOptions
    • 检查选项 —— 一个包含与代码检查流程相关设置的对象。
  • processor
    • 处理器 —— 一个包含preprocess()和postprocess()方法的对象,可以是一个pluginName/processorName插件或处理器的字符串名称。
  • plugins
    • 插件 —— 一个包含插件名称和插件对象的键值对对象。
  • rules
    • 规则 —— 包含配置的规则。
  • settings
    • 设置 —— 一个包含键值对信息的对象，这些键值对可供所有规则使用。
指定文件和忽略选项

Specifying files and ignores

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([// matches all files ending with .js{files: [\"**/*.js\"],rules: {semi: \"error\",},},// matches all files ending with .js except those in __tests{files: [\"**/*.js\"],ignores: [\"__tests/**\"],rules: {\"no-console\": \"error\",},},]);
指定任意扩展名文件

Specifying files with arbitrary extensions

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.ts\", \"**/*.cts\", \"**.*.mts\"],},// ...other config]);
指定未带扩展名的文件

Specifying files without extension

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/!(*.*)\"],},// ...other config]);
指定使用AND运算符的文件

Specifying files with an AND operation

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{files: [[\"src/*\", \"**/.js\"]],},// ...other config]);
排除包含忽略项的文件

Excluding files with ignores

规则仅运用在src文件夹下的文件。

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"src/**/*.js\"],rules: {semi: \"error\",},},]);
全局使用忽略标记的文件

Globally ignoring files with ignores

// eslint.config.jsimport { defineConfig } from \"eslint/config\";// Example of global ignoresexport default defineConfig([ { ignores: [\".config/\", \"dist/\", \"tsconfig.json\"] // acts as global ignores, due to the absence of other properties }, { ... }, // ... other configuration object, inherit global ignores { ... }, // ... other configuration object, inherit global ignores]);// Example of non-global ignoresexport default defineConfig([ { ignores: [\".config/**\", \"dir1/script1.js\"], rules: { ... } // the presence of this property dictates non-global ignores }, { ignores: [\"other-dir/**\", \"dist/script2.js\"], rules: { ... } // the presence of this property dictates non-global ignores },]);
级联配置对象

Cascading Configuration Objects

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.js\"],languageOptions: {globals: {MY_CUSTOM_GLOBAL: \"readonly\",},},},{files: [\"tests/**/*.js\"],languageOptions: {globals: {it: \"readonly\",describe: \"readonly\",},},},]);
配置代码检查器选项

Configuring Linter Options

配置规则

Configuring Rules

在配置对象中添加rules属性用来设置任意数量的规则，该属性包含一个规则配置的对象，该对象名称则为规则的名称，值则为规则的配置。

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([// matches all files because it doesn\'t specify the `files` or `ignores` key{rules: {semi: \"error\",},},]);
配置共享设置

Configuring Shared Settings

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{settings: {sharedData: \"Hello\",},plugins: {customPlugin: {rules: {\"my-rule\": {meta: {// custom rule\'s meta information},create(context) {const sharedData = context.settings.sharedData;return {// code};},},},},},rules: {\"customPlugin/my-rule\": \"error\",},},]);
扩展配置

Extending Configurations

一个配置对象通过extends属性来继承另一个配置对象的数组中所有的特性，同时可以修改这些选项。extends的属性值是一个数组，用于指示从哪些配置中继承属性。

使用插件中的配置

Using Configurations from Plugins

// eslint.config.jsimport examplePlugin from \"eslint-plugin-example\";import { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.js\"],plugins: {example: examplePlugin,},extends: [\"example/recommended\"],},]);
使用预设配置

Using Predefined Configurations

ESLint为JavaScript预定义了两种配置:

  • js/recommended
  • js/all
// eslint.config.jsimport js from \"@eslint/js\";import { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.js\"],plugins: {js,},extends: [\"js/recommended\"],rules: {\"no-unused-vars\": \"warn\",},},]);
使用一个可共享配置包

Using a Shareable Configuration Package

// eslint.config.jsimport exampleConfig from \"eslint-config-example\";import { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.js\"],extends: [exampleConfig],rules: {\"no-unused-vars\": \"warn\",},},]);
配置命名规范

Configuration Naming Conventions

name 属性是可选的，建议为每个配置对象都设置name属性。

配置文件解析

Configuration File Resolution

        When ESLint is run on the command line, it first checks the current working directory for eslint.config.js. If that file is found, then the search stops, otherwise it checks for eslint.config.mjs. If that file is found, then the search stops, otherwise it checks for eslint.config.cjs. If none of the files are found, it checks the parent directory for each file. This search continues until either a config file is found or the root directory is reached.

        You can prevent this search for eslint.config.js by using the -c or --config option on the command line to specify an alternate configuration file, 

当在命令行运行ESLint时，首先检查当前工作目录下是否有eslint.config.js、eslint.config.mjs、eslint.config.cjs文件，如果没有找到，则检查父目录是否有，直到找到为止。

TypeScript配置文件

TypeScript Configuration Files

配置文件优先级

Configuration File Precedence

  1. eslint.config.js
  2. eslint.config.mjs
  3. eslint.config.cjs
  4. eslint.config.ts
  5. eslint.config.mts
  6. eslint.config.cts

2、配置语言选项

Configure Language Options

指定JavaScript选项

Specifying JavaScript Options

  • ecmaVersion(default: \"latest\")
  • sourceType (default: \"module\") 
    • module
    • commonjs
    • script
// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{languageOptions: {ecmaVersion: 5,sourceType: \"script\",},},]);
指定解析器选项

Specifying Parser Options

languageOptions.parserOptions 

  • allowReserved
  • ecmaFeatures
    • globalReturn
    • impliedStrict
    • jsx
// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{languageOptions: {parserOptions: {ecmaFeatures: {jsx: true,},},},},]);
指定全局

Specifying Globals

使用配置注释

Using configuration comments

/* global var1:writable, var2:writable */
使用配置文件

Using configuration files

languageOptions.globals

  • writable
  • readonly
// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{languageOptions: {globals: {var1: \"writable\",var2: \"readonly\",},},},]);
预定义全局变量

Predefined global variables

// eslint.config.jsimport globals from \"globals\";import { defineConfig } from \"eslint/config\";export default defineConfig([{languageOptions: {globals: {...globals.browser,...globals.jest,},},},]);

3、配置规则

Configure Rules

规则严重性

Rule Severities

  • \"off\" 或 0 - 关闭规则
  • \"warn\" 或 1 - 启用并视作警告（不影响退出）
  • \"error\" 或 2 - 启用并视作错误（触发时退出代码为 1）
使用配置注释

Using configuration comments

/* eslint eqeqeq: \"off\", curly: \"error\" */
配置注释描述

Configuration Comment Descriptions

/* eslint eqeqeq: \"off\", curly: \"error\" * -------- * This will not work due to the line above starting with a \'*\' character. */
Report unused eslint inline config comments
// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{linterOptions: {reportUnusedInlineConfigs: \"error\",},},]);
使用配置文件

Using Configuration Files

在配置文件中定义规则使用rules属性来进行配置

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{rules: {eqeqeq: \"off\",\"no-unused-vars\": \"error\",\"prefer-const\": [\"error\", { ignoreReadBeforeAssign: true }],},},]);
插件规则

Rules from Plugins

// eslint.config.jsimport example from \"eslint-plugin-example\";import { defineConfig } from \"eslint/config\";export default defineConfig([{plugins: {example,},rules: {\"example/rule1\": \"warn\",},},]);
禁用规则

Disabling Rules

使用注释配置

Using configuration comments

/* eslint-disable no-alert, no-console */alert(\"foo\");console.log(\"bar\");/* eslint-enable no-alert, no-console */
注释描述

Comment descriptions

// eslint-disable-next-line no-console -- Here\'s a description about why this configuration is necessary.console.log(\"hello\");/* eslint-disable-next-line no-console -- * Here\'s a very long description about why this configuration is necessary * along with some additional information **/console.log(\"hello\");
使用配置文件

Using configuration files

// eslint.config.jsimport { defineConfig } from \"eslint/config\";export default defineConfig([{rules: {\"no-unused-expressions\": \"error\",},},{files: [\"*-test.js\", \"*.spec.js\"],rules: {\"no-unused-expressions\": \"off\",},},]);

4、配置插件

Configure Plugins

配置插件

Configure Plugins

在配置文件中配置插件需采用plugins 键，里面是一个插件对象。

// eslint.config.jsimport example from \"eslint-plugin-example\";import { defineConfig } from \"eslint/config\";export default defineConfig([{plugins: {example,},rules: {\"example/rule1\": \"warn\",},},]);
配置本地插件

Configure a Local Plugin

// eslint.config.jsimport local from \"./my-local-plugin.js\";import { defineConfig } from \"eslint/config\";export default defineConfig([{plugins: {local,},rules: {\"local/rule1\": \"warn\",},},]);
配置虚拟插件

Configure a Virtual Plugin

使用插件规则

Use Plugin Rules

// eslint.config.jsimport jsdoc from \"eslint-plugin-jsdoc\";import { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.js\"],plugins: {jsdoc: jsdoc,},rules: {\"jsdoc/require-description\": \"error\",\"jsdoc/check-values\": \"error\",},},]);
指定处理器

Specify a Processor

插件可以提供处理器。处理器能够从其他类型的文件中提取 JavaScript 代码，然后让 ESLint 对这些 JavaScript 代码进行检查。此外，处理器还可以在预处理过程中对 JavaScript 代码进行转换。

// eslint.config.jsimport markdown from \"@eslint/markdown\";import { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.md\"],plugins: {markdown,},processor: \"markdown/markdown\",},]);
指定一种语言

Specify a Language

// eslint.config.jsimport json from \"@eslint/json\";import { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.json\"],plugins: {json,},language: \"json/jsonc\",},]);

5、配置解析器

Configure a Parser

配置一个自定义解析器

Configure a Custom Parser

// eslint.config.jsimport babelParser from \"@babel/eslint-parser\";import { defineConfig } from \"eslint/config\";export default defineConfig([{files: [\"**/*.js\", \"**/*.mjs\"],languageOptions: {parser: babelParser,},},]);
配置解析器选项

Configure Parser Options

// eslint.config.jsimport babelParser from \"@babel/eslint-parser\";import { defineConfig } from \"eslint/config\";export default defineConfig([{languageOptions: {parser: babelParser,parserOptions: {requireConfigFile: false,babelOptions: {babelrc: false,configFile: false,presets: [\"@babel/preset-env\"],},},},},]);

6、组合配置

Combine Configs

在很多情况下，您不会从头开始编写 ESLint 配置文件，而是会将预定义且可共享的配置与您自己的自定义设置相结合，来为您的项目创建配置文件。

应用一个配置对象

Apply a Config Object

// eslint.config.jsimport js from \"@eslint/js\";import { defineConfig } from \"eslint/config\";export default defineConfig([js.configs.recommended,{rules: {\"no-unused-vars\": \"warn\",},},]);
应用一个配置数组

Apply a Config Array

// eslint.config.jsimport exampleConfigs from \"eslint-config-example\";import { defineConfig } from \"eslint/config\";export default defineConfig([// insert array directlyexampleConfigs,// your modifications{rules: {\"no-unused-vars\": \"warn\",},},]);

7、忽略文件

Ignore Files

忽略文件有两种方式：

  • 通过在eslint.config.js文件中进行配置；
  • 通过在命令行中使用 --ignore-pattern
忽略文件

Ignoring Files

// eslint.config.jsimport { defineConfig, globalIgnores } from \"eslint/config\";export default defineConfig([globalIgnores([\".config/*\"])]);
pnpm dlx eslint . --ignore-pattern \'.config/*\'
忽略目录

Ignoring Directories

// eslint.config.jsimport { defineConfig, globalIgnores } from \"eslint/config\";export default defineConfig([globalIgnores([\".config/\"])]);
不忽略文件和文件夹

Unignoring Files and Directories

// eslint.config.jsimport { defineConfig, globalIgnores } from \"eslint/config\";export default defineConfig([globalIgnores([\"!node_modules/\", // unignore `node_modules/` directory\"node_modules/*\", // ignore its content\"!node_modules/mylibrary/\", // unignore `node_modules/mylibrary` directory]),]);
全局忽略配置名称

Name the Global Ignores Config

// eslint.config.jsimport { defineConfig, globalIgnores } from \"eslint/config\";export default defineConfig([globalIgnores([\"build/**/*\"], \"Ignore Build Directory\"),]);

8、调试你的配置

Debug Your Configuration

以调试模式运行命令行界面

Run the CLI in Debug Mode

使用带有--debug 标识的命令行调试

pnpm dlx eslint --debug file.js
打印文件的计算配置信息

Print a File’s Calculated Configuration

pnpm dlx eslint --print-config file.js
使用配置检查器

Use the Config Inspector

pnpm dlx eslint --inspect-config
网络标签：

相关问题