版本

配置文件（已弃用）

您可以将 ESLint 项目配置放在配置文件中。您可以包含内置规则、如何执行这些规则、带有自定义规则的插件、可共享的配置、您希望规则应用于哪些文件等等。

配置文件格式

ESLint 支持多种格式的配置文件

  • JavaScript - 使用 .eslintrc.js 并导出包含您配置的对象。
  • JavaScript (ESM) - 当在 JavaScript 包中运行 ESLint 时，并且其 package.json 中指定了 "type":"module"，则使用 .eslintrc.cjs。请注意，ESLint 目前不支持 ESM 配置。
  • YAML - 使用 .eslintrc.yaml 或 .eslintrc.yml 定义配置结构。
  • JSON - 使用 .eslintrc.json 定义配置结构。ESLint 的 JSON 文件也允许使用 JavaScript 风格的注释。
  • package.json - 在您的 package.json 文件中创建一个 eslintConfig 属性，并在其中定义您的配置。

如果在同一目录中有多个配置文件，ESLint 只使用一个。优先级顺序如下

  1. .eslintrc.js
  2. .eslintrc.cjs
  3. .eslintrc.yaml
  4. .eslintrc.yml
  5. .eslintrc.json
  6. package.json

使用配置文件

有两种方法可以使用配置文件。

第一种方法是通过 .eslintrc.* 和 package.json 文件使用配置文件。ESLint 会自动在要 lint 的文件的目录中查找它们，并在连续的父目录中一直向上查找，直到文件系统的根目录 (/)、当前用户的家目录 (~/)，或者当指定 root: true 时。有关此内容的更多详细信息，请参阅下面的 级联和层次结构。当您希望为项目的不同部分使用不同的配置，或者希望其他人能够直接使用 ESLint 而无需记住传递配置文件时，配置文件非常有用。

第二种方法是将文件保存到您想要的任何位置，并使用 --config 选项将其位置传递给 CLI，例如

eslint -c myconfig.json myfiletotest.js

如果您使用一个配置文件，并且希望 ESLint 忽略任何 .eslintrc.* 文件，请确保与 --config 标志一起使用 --no-eslintrc。

这是一个使用 typescript-eslint 解析器支持 TypeScript 语法的 JSON 配置文件示例

{
    "root": true,
    "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended"
    ],
    "parser": "@typescript-eslint/parser",
    "parserOptions": { "project": ["./tsconfig.json"] },
    "plugins": [
        "@typescript-eslint"
    ],
    "rules": {
        "@typescript-eslint/strict-boolean-expressions": [
            2,
            {
                "allowString" : false,
                "allowNumber" : false
            }
        ]
    },
    "ignorePatterns": ["src/**/*.test.ts", "src/frontend/generated/*"]
}

配置文件中的注释

JSON 和 YAML 配置文件格式都支持注释 (package.json 文件不应包含注释)。您可以对 JSON 文件使用 JavaScript 风格的注释，对 YAML 文件使用 YAML 风格的注释。ESLint 会安全地忽略配置文件中的注释。这使您的配置文件更易于阅读。

对于 JavaScript 风格的注释

{
    "env": {
        "browser": true
    },
    "rules": {
        // Override our default settings just for this directory
        "eqeqeq": "warn",
        "strict": "off"
    }
}

对于 YAML 风格的注释

env:
    browser: true
rules:
    # Override default settings
    eqeqeq: warn
    strict: off

添加共享设置

ESLint 支持将共享设置添加到配置文件中。插件使用 settings 指定应在其所有规则之间共享的信息。您可以将 settings 对象添加到 ESLint 配置文件中，它将被提供给每个执行的规则。如果您正在添加自定义规则并希望它们能够访问相同的信息并易于配置，这可能很有用。

在 JSON 中

{
    "settings": {
        "sharedData": "Hello"
    }
}

在 YAML 中

---
  settings:
    sharedData: "Hello"

级联和层次结构

当使用 .eslintrc.* 和 package.json 文件进行配置时，您可以利用配置级联。假设您的项目具有以下结构

your-project
├── .eslintrc.json
├── lib
│ └── source.js
└─┬ tests
  ├── .eslintrc.json
  └── test.js

配置级联基于要 lint 的文件的位置。如果在与要 lint 的文件相同的目录中存在 .eslintrc 文件，则该配置优先。然后，ESLint 会向上搜索目录结构，合并沿途找到的任何 .eslintrc 文件，直到到达具有 root: true 的 .eslintrc 文件或根目录。

同样，如果根目录中存在一个带有 eslintConfig 字段的 package.json 文件，则其描述的配置将应用于其下方的所有子目录。但是，tests/ 目录中的 .eslintrc 文件描述的配置会覆盖冲突的规范。

your-project
├── package.json
├── lib
│ └── source.js
└─┬ tests
  ├── .eslintrc.json
  └── test.js

如果在同一目录中找到 .eslintrc 和 package.json 文件，则 .eslintrc 优先，并且不使用 package.json 文件。

默认情况下，ESLint 会在所有父文件夹中一直向上搜索到根目录，以查找配置文件。如果您希望所有项目都遵循某种约定，这很有用，但有时会导致意外结果。要将 ESLint 限制到特定项目，请在 .eslintrc.* 文件或 package.json 文件的 eslintConfig 字段中或项目根级别的 .eslintrc.* 文件中放置 "root": true。ESLint 一旦找到具有 "root": true 的配置，就会停止在父文件夹中搜索。

{
    "root": true
}

在 YAML 中

---
  root: true

例如，考虑 projectA，它在 lib/ 目录的 .eslintrc 文件中设置了 "root": true。在这种情况下，在 lint main.js 时，将使用 lib/ 中的配置，但不会使用 projectA/ 中的 .eslintrc 文件。

home
└── user
    └── projectA
        ├── .eslintrc.json  <- Not used
        └── lib
            ├── .eslintrc.json  <- { "root": true }
            └── main.js

完整的配置层次结构（从最高到最低优先级）如下所示

  1. 内联配置
    1. /*eslint-disable*/ 和 /*eslint-enable*/
    2. /*global*/
    3. /*eslint*/
    4. /*eslint-env*/
  2. 命令行选项（或 CLIEngine 等效项）
    1. --global
    2. --rule
    3. --env
    4. -c, --config
  3. 项目级配置
    1. 与要 lint 的文件位于同一目录中的 .eslintrc.* 或 package.json 文件
    2. 继续在祖先目录中搜索 .eslintrc.* 和 package.json 文件，直到根目录或找到具有 "root": true 的配置为止。

请注意，您首选操作系统上的当前用户的主目录 (~/) 在此上下文中也被视为根目录，并且在此处搜索配置文件也会停止。并且，随着从 8.0.0 版本开始 删除对个人配置文件的支持，该目录中存在的配置文件将被忽略。

扩展配置文件

扩展后，配置文件可以继承另一个配置文件的所有特性（包括规则、插件和语言选项），并修改所有选项。因此，如下所述，存在三种配置

  • 基础配置：被扩展的配置。
  • 派生配置：扩展基础配置的配置。
  • 最终实际配置：将派生配置合并到基础配置的结果。

extends 属性值可以是

  • 指定配置的字符串（配置文件的路径、可共享配置的名称、eslint:recommended 或 eslint:all）
  • 字符串数组，其中每个额外的配置扩展前一个配置

ESLint 递归地扩展配置，因此基础配置也可以具有 extends 属性。extends 属性中的相对路径和可共享配置名称是从其出现的配置文件的位置解析的。

可以从配置名称中省略 eslint-config- 前缀。例如，airbnb 将解析为 eslint-config-airbnb。

rules 属性可以执行以下任何操作以扩展（或覆盖）规则集

  • 启用其他规则
  • 更改继承规则的严重性而不更改其选项
    • 基础配置："eqeqeq": ["error", "allow-null"]
    • 派生配置："eqeqeq": "warn"
    • 最终实际配置："eqeqeq": ["warn", "allow-null"]
  • 覆盖基础配置中规则的选项
    • 基础配置："quotes": ["error", "single", "avoid-escape"]
    • 派生配置："quotes": ["error", "single"]
    • 最终实际配置："quotes": ["error", "single"]
  • 覆盖基础配置中作为对象给出的规则的选项
    • 基础配置："max-lines": ["error", { "max": 200, "skipBlankLines": true, "skipComments": true }]
    • 派生配置："max-lines": ["error", { "max": 100 }]
    • 最终实际配置："max-lines": ["error", { "max": 100 }]，其中 skipBlankLines 和 skipComments 默认为 false

使用可共享的配置包

一个 可共享的配置 是一个 npm 包，它导出一个配置对象。确保已在项目根目录中安装了该包，以便 ESLint 可以 require 它。

extends 属性值可以省略包名称的 eslint-config- 前缀。

npm init @eslint/config 命令可以创建一个配置，以便您可以扩展流行的风格指南（例如，eslint-config-standard）。

YAML 格式配置文件示例

extends: standard
rules:
  comma-dangle:
    - error
    - always
  no-empty: warn

使用 eslint:recommended

在 extends 属性中使用 "eslint:recommended" 会启用核心规则的一个子集，这些规则会报告常见问题（这些规则在 规则页面 上用复选标记（推荐）标识）。

这是一个扩展 eslint:recommended 并覆盖一些已设置配置选项的示例。

JavaScript 格式的配置文件示例

module.exports = {
    "extends": "eslint:recommended",
    "rules": {
        // enable additional rules
        "indent": ["error", 4],
        "linebreak-style": ["error", "unix"],
        "quotes": ["error", "double"],
        "semi": ["error", "always"],

        // override configuration set by extending "eslint:recommended"
        "no-empty": "warn",
        "no-cond-assign": ["error", "always"],

        // disable rules from base configurations
         "for-direction": "off",
    }
}

使用插件中的配置

一个 插件 是一个 npm 包，可以为 ESLint 添加各种扩展。插件可以执行许多功能，包括但不限于添加新规则和导出 可共享的配置。确保该包已安装在 ESLint 可以 require 它的目录中。

plugins 属性值 可以省略包名称的 eslint-plugin- 前缀。

extends 属性值可以由以下部分组成：

  • 插件
  • 包名称（可以省略前缀，例如，react 是 eslint-plugin-react 的简写）
  • /
  • 配置名称（例如，recommended）

JSON 格式的配置文件示例

{
    "plugins": [
        "react"
    ],
    "extends": [
        "eslint:recommended",
        "plugin:react/recommended"
    ],
    "rules": {
       "react/no-set-state": "off"
    }
}

使用配置文件

extends 属性值可以是到基础 配置文件 的绝对路径或相对路径。ESLint 会相对于使用它的配置文件解析到基础配置文件的相对路径。

JSON 格式的配置文件示例

{
    "extends": [
        "./node_modules/coding-standard/eslintDefaults.js",
        "./node_modules/coding-standard/.eslintrc-es6",
        "./node_modules/coding-standard/.eslintrc-jsx"
    ],
    "rules": {
        "eqeqeq": "warn"
    }
}

使用 "eslint:all"

extends 属性值可以是 "eslint:all"，以启用当前安装的 ESLint 版本中的所有核心规则。核心规则集可能会在 ESLint 的任何次要或主要版本中发生更改。

重要：此配置不建议用于生产环境，因为它会随着 ESLint 的每个次要和主要版本而更改。使用需谨慎。

您可能会启用所有核心规则作为探索规则和选项的快捷方式，以便在您决定项目的配置时使用，尤其是在您很少覆盖选项或禁用规则的情况下。规则的默认选项并非 ESLint 的推荐（例如，quotes 规则的默认选项并不意味着双引号比单引号更好）。

如果您的配置扩展了 eslint:all，在您升级到更新的 ESLint 主要或次要版本后，请在使用 命令行 上的 --fix 选项之前查看报告的问题，以便您知道新的可修复规则是否会对代码进行更改。

JavaScript 格式的配置文件示例

module.exports = {
    "extends": "eslint:all",
    "rules": {
        // override default options
        "comma-dangle": ["error", "always"],
        "indent": ["error", 2],
        "no-cond-assign": ["error", "always"],

        // disable now, but enable in the future
        "one-var": "off", // ["error", "never"]

        // disable
        "init-declarations": "off",
        "no-console": "off",
        "no-inline-comments": "off",
    }
}

基于通配符模式的配置

v4.1.0+。有时需要更细粒度的控制配置，例如，如果同一目录中文件的配置必须不同。在这种情况下，您可以在 overrides 键下提供仅适用于与特定 glob 模式匹配的文件的配置，使用与您在命令行上传递相同的格式（例如，app/**/*.test.js）。

覆盖中的 Glob 模式使用 minimatch 语法。

覆盖是如何工作的？

可以通过使用 overrides 键在您的配置中基于文件 glob 模式覆盖设置。使用 overrides 键的示例如下所示

在您的 .eslintrc.json 中

{
  "rules": {
    "quotes": ["error", "double"]
  },

  "overrides": [
    {
      "files": ["bin/*.js", "lib/*.js"],
      "excludedFiles": "*.test.js",
      "rules": {
        "quotes": ["error", "single"]
      }
    }
  ]
}

以下是覆盖在配置文件中的工作方式

  • 这些模式相对于配置文件的目录应用于文件路径。例如，如果您的配置文件路径为 /Users/john/workspace/any-project/.eslintrc.js，并且您要 lint 的文件路径为 /Users/john/workspace/any-project/lib/util.js，则 .eslintrc.js 中提供的模式会针对相对路径 lib/util.js 执行。
  • Glob 模式覆盖优先于同一配置文件中的常规配置。同一配置文件中的多个覆盖按顺序应用。也就是说，配置文件中的最后一个覆盖块始终具有最高优先级。
  • Glob 特定的配置与任何其他 ESLint 配置的工作方式几乎相同。覆盖块可以包含常规配置中有效的任何配置选项，但 root 和 ignorePatterns 除外。
    • Glob 特定的配置可以具有 extends 设置，但扩展配置中的 root 属性会被忽略。扩展配置中的 ignorePatterns 属性仅用于 Glob 特定配置匹配的文件。
    • 嵌套的 overrides 设置仅在父配置和子配置的 glob 模式都匹配时应用。当扩展的配置具有 overrides 设置时，情况也是如此。
  • 可以在单个覆盖块中提供多个 glob 模式。文件必须至少匹配提供的模式之一，配置才能应用。
  • 覆盖块还可以指定要排除的匹配模式。如果文件与任何排除的模式匹配，则配置将不适用。

相对通配符模式

project-root
├── app
│   ├── lib
│   │   ├── foo.js
│   │   ├── fooSpec.js
│   ├── components
│   │   ├── bar.js
│   │   ├── barSpec.js
│   ├── .eslintrc.json
├── server
│   ├── server.js
│   ├── serverSpec.js
├── .eslintrc.json

app/.eslintrc.json 中的配置定义了 glob 模式 **/*Spec.js。此模式相对于 app/.eslintrc.json 的基目录。因此，此模式将匹配 app/lib/fooSpec.js 和 app/components/barSpec.js，但不匹配 server/serverSpec.js。如果您在 project-root 文件夹中的 .eslintrc.json 文件中定义了相同的模式，它将匹配所有三个 *Spec 文件。

如果通过 --config CLI 选项提供了配置，则配置中的 glob 模式相对于当前工作目录而不是给定配置的基目录。例如，如果存在 --config configs/.eslintrc.json，则配置中的 glob 模式相对于 . 而不是 ./configs。

指定要 lint 的目标文件

如果使用 CLI 指定了目录（例如，eslint lib），ESLint 会搜索要 lint 的目录中的目标文件。目标文件是 *.js 或与任何 overrides 条目匹配的文件（但排除任何 files 以 * 结尾的条目）。

如果与目录一起指定了 --ext 命令行选项，则目标文件仅是具有指定文件扩展名的文件，而不管 overrides 条目如何。

个人配置文件（已弃用）

⚠️ 此功能已被弃用。此功能已在 8.0.0 版本中删除。如果您想继续使用个人配置文件，请使用 --config CLI 选项。有关此决定的更多信息，请参阅 RFC 28 和 RFC 32。

~/ 指的是 您首选操作系统上当前用户的 home 目录。这里指的是 ~/.eslintrc.* 文件，它与其他配置文件的处理方式不同。

ESLint 如何找到个人配置文件？

如果 eslint 在项目中找不到任何配置文件，eslint 会加载 ~/.eslintrc.* 文件。

如果 eslint 在项目中找到配置文件，即使 ~/.eslintrc.* 文件位于项目目录的祖先目录中，eslint 也会忽略它。

个人配置文件的行为如何？

~/.eslintrc.* 文件的行为类似于常规配置文件，但有一些例外。

~/.eslintrc.* 文件从用户的 home 目录中的 ~/node_modules/ 加载可共享的配置和自定义解析器——类似于 require()。请注意，它不会加载全局安装的包。

~/.eslintrc.* 文件默认从 $CWD/node_modules 加载插件，以便唯一地识别插件。如果您想在 ~/.eslintrc.* 文件中使用插件，则必须在每个项目中本地安装插件。或者，您可以使用 --resolve-plugins-relative-to CLI 选项 来更改 ESLint 加载插件的位置。

编辑此页面
© OpenJS 基金会和 ESLint 贡献者，www.openjsf.org。内容根据 MIT 许可证 授权。
更改语言