Configuring ESLint

ESLint is designed to be completely configurable, meaning you can turn off every rule and run only with basic syntax validation, or mix and match the bundled rules and your custom rules to make ESLint perfect for your project. There are two primary ways to configure ESLint:

ESlint 被设计为完全可配置的,这意味着你可以关闭每一个规则而只运行基本语法验证,或混合和匹配 ESLint 默认绑定的规则和你的自定义规则,以让 ESLint 更适合你的项目。有两种主要的方式来配置 ESLint:

  1. Configuration Comments - use JavaScript comments to embed configuration information directly into a file.
  2. Configuration Comments - 使用 JavaScript 注释把配置信息直接嵌入到一个代码源文件中。
  3. Configuration Files - use a JavaScript, JSON or YAML file to specify configuration information for an entire directory (other than your home directory) and all of its subdirectories. This can be in the form of an .eslintrc.* file or an eslintConfig field in a package.json file, both of which ESLint will look for and read automatically, or you can specify a configuration file on the command line.
  4. Configuration Files - 使用 JavaScript、JSON 或者 YAML 文件为整个目录(处理你的主目录)和它的子目录指定配置信息。可以配置一个独立的 .eslintrc.* 文件,或者直接在 package.json 文件里的 eslintConfig 字段指定配置,ESLint 会查找和自动读取它们,再者,你可以在命令行运行时指定一个任意的配置文件。

If you have a configuration file in your home directory (generally ~/), ESLint uses it only if ESLint cannot find any other configuration file.

如果你在你的主目录(通常 ~/)有一个配置文件,ESLint 只有在无法找到其他配置文件时才使用它。

There are several pieces of information that can be configured:

有很多信息可以配置:

All of these options give you fine-grained control over how ESLint treats your code.

所有这些选项让你可以细粒度地控制 ESLint 如何对待你的代码。

Specifying Parser Options

ESLint allows you to specify the JavaScript language options you want to support. By default, ESLint expects ECMAScript 5 syntax. You can override that setting to enable support for other ECMAScript versions as well as JSX by using parser options.

ESLint 允许你指定你想要支持的 JavaScript 语言选项。默认情况下,ESLint 支持 ECMAScript 5 语法。你可以覆盖该设置,以启用对 ECMAScript 其它版本和 JSX 的支持。

Please note that supporting JSX syntax is not the same as supporting React. React applies specific semantics to JSX syntax that ESLint doesn’t recognize. We recommend using eslint-plugin-react if you are using React and want React semantics.

请注意,支持 JSX 语法并不等同于支持 React。React 对 ESLint 无法识别的JSX语法应用特定的语义。如果你正在使用 React 并且想要 React 语义支持,我们建议你使用 eslint-plugin-react

By the same token, supporting ES6 syntax is not the same as supporting new ES6 globals (e.g., new types such as Set). For ES6 syntax, use { "parserOptions": { "ecmaVersion": 6 } }; for new ES6 global variables, use { "env": { "es6": true } }. { "env": { "es6": true } } enables ES6 syntax automatically, but { "parserOptions": { "ecmaVersion": 6 } } does not enable ES6 globals automatically.

同样的,支持 ES6 语法并不意味着同时支持新的 ES6 全局变量或类型(比如 Set 等新类型)。对于 ES6 语法,使用 { "parserOptions": { "ecmaVersion": 6 } };对于新的 ES6 全局变量,使用 { "env":{ "es6": true } }. { "env": { "es6": true } } 自动启用es6语法,但 { "parserOptions": { "ecmaVersion": 6 } } 不自动启用es6全局变量。

Parser options are set in your .eslintrc.* file by using the parserOptions property. The available options are:

解析器选项可以在 .eslintrc.* 文件使用 parserOptions 属性设置。可用的选项有:

Here’s an example .eslintrc.json file:

.eslintrc.json 文件示例:

{
    "parserOptions": {
        "ecmaVersion": 6,
        "sourceType": "module",
        "ecmaFeatures": {
            "jsx": true
        }
    },
    "rules": {
        "semi": "error"
    }
}

Setting parser options helps ESLint determine what is a parsing error. All language options are false by default.

设置解析器选项能帮助 ESLint 确定什么是解析错误,所有语言选项默认都是 false

Specifying Parser

By default, ESLint uses Espree as its parser. You can optionally specify that a different parser should be used in your configuration file so long as the parser meets the following requirements:

ESLint 默认使用Espree作为其解析器,你可以在配置文件中指定一个不同的解析器,只要该解析器符合下列要求:

  1. It must be a Node module loadable from the config file where it appears. Usually, this means you should install the parser package separately using npm.
  2. 它必须是一个 Node 模块,可以从它出现的配置文件中加载。通常,这意味着应该使用 npm 单独安装解析器包。
  3. It must conform to the parser interface.
  4. 它必须符合 parser interface

Note that even with these compatibilities, there are no guarantees that an external parser will work correctly with ESLint and ESLint will not fix bugs related to incompatibilities with other parsers.

注意,即使满足这些兼容性要求,也不能保证一个外部解析器可以与 ESLint 正常配合工作,ESLint 也不会修复与其它解析器不兼容的相关 bug。

To indicate the npm module to use as your parser, specify it using the parser option in your .eslintrc file. For example, the following specifies to use Esprima instead of Espree:

为了表明使用该 npm 模块作为你的解析器,你需要在你的 .eslintrc 文件里指定 parser 选项。例如,下面的配置指定了 Esprima 作为解析器:

{
    "parser": "esprima",
    "rules": {
        "semi": "error"
    }
}

The following parsers are compatible with ESLint:

以下解析器与 ESLint 兼容:

Note when using a custom parser, the parserOptions configuration property is still required for ESLint to work properly with features not in ECMAScript 5 by default. Parsers are all passed parserOptions and may or may not use them to determine which features to enable.

注意,在使用自定义解析器时,为了让 ESLint 在处理非 ECMAScript 5 特性时正常工作,配置属性 parserOptions 仍然是必须的。解析器会被传入 parserOptions,但是不一定会使用它们来决定功能特性的开关。

Specifying Processor

Plugins may provide processors. Processors can extract JavaScript code from another kind of files, then lets ESLint lint the JavaScript code. Or processors can convert JavaScript code in preprocessing for some purpose.

插件可以提供处理器。处理器可以从另一种文件中提取 JavaScript 代码,然后让 ESLint 检测 JavaScript 代码。或者处理器可以在预处理中转换 JavaScript 代码。

To specify processors in a configuration file, use the processor key with the concatenated string of a plugin name and a processor name by a slash. For example, the following enables the processor a-processor that the plugin a-plugin provided:

若要在配置文件中指定处理器,请使用 processor 键,并使用由插件名和处理器名组成的串接字符串加上斜杠。例如,下面的选项启用插件 a-plugin 提供的处理器 a-processor

{
    "plugins": ["a-plugin"],
    "processor": "a-plugin/a-processor"
}

To specify processors for a specific kind of files, use the combination of the overrides key and the processor key. For example, the following uses the processor a-plugin/markdown for *.md files.

要为特定类型的文件指定处理器,请使用 overrides 键和 processor 键的组合。例如,下面对 *.md 文件使用处理器 a-plugin/markdown

{
    "plugins": ["a-plugin"],
    "overrides": [
        {
            "files": ["*.md"],
            "processor": "a-plugin/markdown"
        }
    ]
}

Processors may make named code blocks such as 0.js and 1.js. ESLint handles such a named code block as a child file of the original file. You can specify additional configurations for named code blocks in the overrides section of the config. For example, the following disables strict rule for the named code blocks which end with .js in markdown files.

处理器可以生成命名的代码块,如 0.js1.js。ESLint 将这样的命名代码块作为原始文件的子文件处理。你可以在配置的 overrides 部分为已命名的代码块指定附加配置。例如,下面的命令对以 .js 结尾的 markdown 文件中的已命名代码块禁用 strict 规则。

{
    "plugins": ["a-plugin"],
    "overrides": [
        {
            "files": ["*.md"],
            "processor": "a-plugin/markdown"
        },
        {
            "files": ["**/*.md/*.js"],
            "rules": {
                "strict": "off"
            }
        }
    ]
}

ESLint checks the file extension of named code blocks then ignores those if --ext CLI option didn’t include the file extension. Be sure to specify the --ext option if you wanted to lint named code blocks other than *.js.

ESLint 检查指定代码块的文件扩展名,如果 --ext CLI option 不包含文件扩展名,则忽略这些扩展名。如果您想要删除除 *.js 之外的已命名代码块,请确保指定 --ext 选项。

Specifying Environments

An environment defines global variables that are predefined. The available environments are:

一个环境定义了一组预定义的全局变量。可用的环境包括:

These environments are not mutually exclusive, so you can define more than one at a time.

这些环境并不是互斥的,所以你可以同时定义多个。

Environments can be specified inside of a file, in configuration files or using the --env command line flag.

可以在源文件里、在配置文件中或使用 命令行--env 选项来指定环境。

To specify environments using a comment inside of your JavaScript file, use the following format:

要在你的 JavaScript 文件中使用注释来指定环境,格式如下:

/* eslint-env node, mocha */

This enables Node.js and Mocha environments.

该设置启用了 Node.js 和 Mocha 环境。

To specify environments in a configuration file, use the env key and specify which environments you want to enable by setting each to true. For example, the following enables the browser and Node.js environments:

要在配置文件里指定环境,使用 env 关键字指定你想启用的环境,并设置它们为 true。例如,以下示例启用了 browser 和 Node.js 的环境:

{
    "env": {
        "browser": true,
        "node": true
    }
}

Or in a package.json file

或在 package.json 文件中:

{
    "name": "mypackage",
    "version": "0.0.1",
    "eslintConfig": {
        "env": {
            "browser": true,
            "node": true
        }
    }
}

And in YAML:

在 YAML 文件中:

---
  env:
    browser: true
    node: true

If you want to use an environment from a plugin, be sure to specify the plugin name in the plugins array and then use the unprefixed plugin name, followed by a slash, followed by the environment name. For example:

如果你想在一个特定的插件中使用一种环境,确保提前在 plugins 数组里指定了插件名,然后在 env 配置中不带前缀的插件名后跟一个 / ,紧随着环境名。例如:

{
    "plugins": ["example"],
    "env": {
        "example/custom": true
    }
}

Or in a package.json file

或在 package.json 文件中

{
    "name": "mypackage",
    "version": "0.0.1",
    "eslintConfig": {
        "plugins": ["example"],
        "env": {
            "example/custom": true
        }
    }
}

And in YAML:

在 YAML 文件中:

---
  plugins:
    - example
  env:
    example/custom: true

Specifying Globals

The no-undef rule will warn on variables that are accessed but not defined within the same file. If you are using global variables inside of a file then it’s worthwhile to define those globals so that ESLint will not warn about their usage. You can define global variables either using comments inside of a file or in the configuration file.

当访问当前源文件内未定义的变量时,no-undef 规则将发出警告。如果你想在一个源文件里使用全局变量,推荐你在 ESLint 中定义这些全局变量,这样 ESLint 就不会发出警告了。你可以使用注释或在配置文件中定义全局变量。

To specify globals using a comment inside of your JavaScript file, use the following format:

要在你的 JavaScript 文件中,用注释指定全局变量,格式如下:

/* global var1, var2 */

This defines two global variables, var1 and var2. If you want to optionally specify that these global variables can be written to (rather than only being read), then you can set each with a "writable" flag:

这定义了两个全局变量,var1var2。如果你想选择性地指定这些全局变量可以被写入(而不是只被读取),那么你可以用一个 "writable" 的标志来设置它们:

/* global var1:writable, var2:writable */

To configure global variables inside of a configuration file, set the globals configuration property to an object containing keys named for each of the global variables you want to use. For each global variable key, set the corresponding value equal to "writable" to allow the variable to be overwritten or "readonly" to disallow overwriting. For example:

要在配置文件中配置全局变量,请将 globals 配置属性设置为一个对象,该对象包含以你希望使用的每个全局变量。对于每个全局变量键,将对应的值设置为 "writable" 以允许重写变量,或 "readonly" 不允许重写变量。例如:

{
    "globals": {
        "var1": "writable",
        "var2": "readonly"
    }
}

And in YAML:

在 YAML 中:

---
  globals:
    var1: writable
    var2: readonly

These examples allow var1 to be overwritten in your code, but disallow it for var2.

在这些例子中 var1 允许被重写,var2 不允许被重写。

Globals can be disabled with the string "off". For example, in an environment where most ES2015 globals are available but Promise is unavailable, you might use this config:

可以使用字符串 "off" 禁用全局变量。例如,在大多数 ES2015 全局变量可用但 Promise 不可用的环境中,你可以使用以下配置:

{
    "env": {
        "es6": true
    },
    "globals": {
        "Promise": "off"
    }
}

For historical reasons, the boolean value false and the string value "readable" are equivalent to "readonly". Similarly, the boolean value true and the string value "writeable" are equivalent to "writable". However, the use of older values is deprecated.

由于历史原因,布尔值 false 和字符串值 "readable" 等价于 "readonly"。类似地,布尔值 true 和字符串值 "writeable" 等价于 "writable"。但是,不建议使用旧值。

Note: Enable the no-global-assign rule to disallow modifications to read-only global variables in your code.

注意:要启用no-global-assign规则来禁止对只读的全局变量进行修改。

Configuring Plugins

ESLint supports the use of third-party plugins. Before using the plugin, you have to install it using npm.

ESLint 支持使用第三方插件。在使用插件之前,你必须使用 npm 安装它。

To configure plugins inside of a configuration file, use the plugins key, which contains a list of plugin names. The eslint-plugin- prefix can be omitted from the plugin name.

在配置文件里配置插件时,可以使用 plugins 关键字来存放插件名字的列表。插件名称可以省略 eslint-plugin- 前缀。

{
    "plugins": [
        "plugin1",
        "eslint-plugin-plugin2"
    ]
}

And in YAML:

在 YAML 中:

---
  plugins:
    - plugin1
    - eslint-plugin-plugin2

Note: Plugins are resolved relative to the current working directory of the ESLint process. In other words, ESLint will load the same plugin as a user would obtain by running require('eslint-plugin-pluginname') in a Node REPL from their project root.

注意:插件是相对于 ESLint 进程的当前工作目录解析的。换句话说,ESLint 将加载与用户通过从项目 Node 交互解释器运行 ('eslint-plugin-pluginname') 获得的相同的插件。

Configuring Rules

ESLint comes with a large number of rules. You can modify which rules your project uses either using configuration comments or configuration files. To change a rule setting, you must set the rule ID equal to one of these values:

ESLint 附带有大量的规则。你可以使用注释或配置文件修改你项目中要使用的规则。要改变一个规则设置,你必须将规则 ID 设置为下列值之一:

Using Configuration Comments

To configure rules inside of a file using configuration comments, use a comment in the following format:

为了在文件注释里配置规则,使用以下格式的注释:

/* eslint eqeqeq: "off", curly: "error" */

In this example, eqeqeq is turned off and curly is turned on as an error. You can also use the numeric equivalent for the rule severity:

在这个例子里,eqeqeq 规则被关闭,curly 规则被打开,定义为错误级别。你也可以使用对应的数字定义规则严重程度:

/* eslint eqeqeq: 0, curly: 2 */

This example is the same as the last example, only it uses the numeric codes instead of the string values. The eqeqeq rule is off and the curly rule is set to be an error.

这个例子和上个例子是一样的,只不过它是用的数字而不是字符串。eqeqeq 规则是关闭的,curly 规则被设置为错误级别。

If a rule has additional options, you can specify them using array literal syntax, such as:

如果一个规则有额外的选项,你可以使用数组字面量指定它们,比如:

/* eslint quotes: ["error", "double"], curly: 2 */

This comment specifies the “double” option for the quotes rule. The first item in the array is always the rule severity (number or string).

这条注释为规则 quotes 指定了 “double”选项。数组的第一项总是规则的严重程度(数字或字符串)。

Using Configuration Files

To configure rules inside of a configuration file, use the rules key along with an error level and any options you want to use. For example:

还可以使用 rules 连同错误级别和任何你想使用的选项,在配置文件中进行规则配置。例如:

{
    "rules": {
        "eqeqeq": "off",
        "curly": "error",
        "quotes": ["error", "double"]
    }
}

And in YAML:

在 YAML 中:

---
rules:
  eqeqeq: off
  curly: error
  quotes:
    - error
    - double

To configure a rule which is defined within a plugin you have to prefix the rule ID with the plugin name and a /. For example:

配置定义在插件中的一个规则的时候,你必须使用 插件名/规则ID 的形式。比如:

{
    "plugins": [
        "plugin1"
    ],
    "rules": {
        "eqeqeq": "off",
        "curly": "error",
        "quotes": ["error", "double"],
        "plugin1/rule1": "error"
    }
}

And in YAML:

在 YAML 中:

---
plugins:
  - plugin1
rules:
  eqeqeq: 0
  curly: error
  quotes:
    - error
    - "double"
  plugin1/rule1: error

In these configuration files, the rule plugin1/rule1 comes from the plugin named plugin1. You can also use this format with configuration comments, such as:

在这些配置文件中,规则 plugin1/rule1 表示来自插件 plugin1rule1 规则。你也可以使用这种格式的注释配置,比如:

/* eslint "plugin1/rule1": "error" */

Note: When specifying rules from plugins, make sure to omit eslint-plugin-. ESLint uses only the unprefixed name internally to locate rules.

注意:当指定来自插件的规则时,确保删除 eslint-plugin- 前缀。ESLint 在内部只使用没有前缀的名称去定位规则。

Disabling Rules with Inline Comments

To temporarily disable rule warnings in your file, use block comments in the following format:

可以在你的文件中使用以下格式的块注释来临时禁止规则出现警告:

/* eslint-disable */

alert('foo');

/* eslint-enable */

You can also disable or enable warnings for specific rules:

你也可以对指定的规则启用或禁用警告:

/* eslint-disable no-alert, no-console */

alert('foo');
console.log('bar');

/* eslint-enable no-alert, no-console */

To disable rule warnings in an entire file, put a /* eslint-disable */ block comment at the top of the file:

如果在整个文件范围内禁止规则出现警告,将 /* eslint-disable */ 块注释放在文件顶部:

/* eslint-disable */

alert('foo');

You can also disable or enable specific rules for an entire file:

你也可以对整个文件启用或禁用警告:

/* eslint-disable no-alert */

// Disables no-alert for the rest of the file
alert('foo');

To disable all rules on a specific line, use a line or block comment in one of the following formats:

可以在你的文件中使用以下格式的行注释或块注释在某一特定的行上禁用所有规则:

alert('foo'); // eslint-disable-line

// eslint-disable-next-line
alert('foo');

/* eslint-disable-next-line */
alert('foo');

alert('foo'); /* eslint-disable-line */

To disable a specific rule on a specific line:

在某一特定的行上禁用某个指定的规则:

alert('foo'); // eslint-disable-line no-alert

// eslint-disable-next-line no-alert
alert('foo');

alert('foo'); /* eslint-disable-line no-alert */

/* eslint-disable-next-line no-alert */
alert('foo');

To disable multiple rules on a specific line:

在某个特定的行上禁用多个规则:

alert('foo'); // eslint-disable-line no-alert, quotes, semi

// eslint-disable-next-line no-alert, quotes, semi
alert('foo');

alert('foo'); /* eslint-disable-line no-alert, quotes, semi */

/* eslint-disable-next-line no-alert, quotes, semi */
alert('foo');

All of the above methods also work for plugin rules. For example, to disable eslint-plugin-example’s rule-name rule, combine the plugin’s name (example) and the rule’s name (rule-name) into example/rule-name:

上面的所有方法同样适用于插件规则。例如,禁止 eslint-plugin-examplerule-name 规则,把插件名(example)和规则名(rule-name)结合为 example/rule-name

foo(); // eslint-disable-line example/rule-name
foo(); /* eslint-disable-line example/rule-name */

Note: Comments that disable warnings for a portion of a file tell ESLint not to report rule violations for the disabled code. ESLint still parses the entire file, however, so disabled code still needs to be syntactically valid JavaScript.

注意:为文件的某部分禁用警告的注释,告诉 ESLint 不要对禁用的代码报告规则的冲突。ESLint 仍解析整个文件,然而,禁用的代码仍需要是有效的 JavaScript 语法。

Disabling Rules Only for a Group of Files

To disable rules inside of a configuration file for a group of files, use the overrides key along with a files key. For example:

若要禁用一组文件的配置文件中的规则,请使用 overridesfiles。例如:

{
  "rules": {...},
  "overrides": [
    {
      "files": ["*-test.js","*.spec.js"],
      "rules": {
        "no-unused-expressions": "off"
      }
    }
  ]
}

Adding Shared Settings

ESLint supports adding shared settings into configuration file. You can add settings object to ESLint configuration file and it will be supplied to every rule that will be executed. This may be useful if you are adding custom rules and want them to have access to the same information and be easily configurable.

ESLint 支持在配置文件添加共享设置。你可以添加 settings 对象到配置文件,它将提供给每一个将被执行的规则。如果你想添加的自定义规则而且使它们可以访问到相同的信息,这将会很有用,并且很容易配置。

In JSON:

在 JSON 中:

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

And in YAML:

在 YAML 中:

---
  settings:
    sharedData: "Hello"

Using Configuration Files

There are two ways to use configuration files.

有两种方式使用配置文件。

The first way to use configuration files is via .eslintrc.* and package.json files. ESLint will automatically look for them in the directory of the file to be linted, and in successive parent directories all the way up to the root directory of the filesystem (unless root: true is specified). This option is useful when you want different configurations for different parts of a project or when you want others to be able to use ESLint directly without needing to remember to pass in the configuration file.

使用配置文件的第一种方式是通过 .eslintrc.*package.json 文件。ESLint 将自动在要检测的文件目录里寻找它们,紧接着是父级目录,一直到文件系统的根目录(除非指定 root: true)。当你想对一个项目的不同部分的使用不同配置,或当你希望别人能够直接使用 ESLint,而无需记住要在配置文件中传递什么,这种方式就很有用。

The second is to save the file wherever you would like and pass its location to the CLI using the -c option, such as:

第二种方式是使用 -c 选项传递命令行将文件保持到你喜欢的地方。

eslint -c myconfig.json myfiletotest.js

If you are using one configuration file and want ESLint to ignore any .eslintrc.* files, make sure to use --no-eslintrc along with the -c flag.

如果你使用一个配置文件,想要 ESLint 忽略任何 .eslintrc.* 文件,请确保使用 --no-eslintrc 的同时,加上 -c 标记。

In each case, the settings in the configuration file override default settings.

每种情况,配置文件都会覆盖默认设置。

Configuration File Formats

ESLint supports configuration files in several formats:

ESLint 支持几种格式的配置文件:

If there are multiple configuration files in the same directory, ESLint will only use one. The priority order is:

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

  1. .eslintrc.js
  2. .eslintrc.js
  3. .eslintrc.yaml
  4. .eslintrc.yaml
  5. .eslintrc.yml
  6. .eslintrc.yml
  7. .eslintrc.json
  8. .eslintrc.json
  9. .eslintrc
  10. .eslintrc
  11. package.json
  12. package.json

Configuration Cascading and Hierarchy

When using .eslintrc.* and package.json files for configuration, you can take advantage of configuration cascading. For instance, suppose you have the following structure:

当使用 .eslintrc.*package.json文件的配置时,你可以利用层叠配置。例如,假如你有以下结构:

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

The configuration cascade works by using the closest .eslintrc file to the file being linted as the highest priority, then any configuration files in the parent directory, and so on. When you run ESLint on this project, all files in lib/ will use the .eslintrc file at the root of the project as their configuration. When ESLint traverses into the tests/ directory, it will then use your-project/tests/.eslintrc in addition to your-project/.eslintrc. So your-project/tests/test.js is linted based on the combination of the two .eslintrc files in its directory hierarchy, with the closest one taking priority. In this way, you can have project-level ESLint settings and also have directory-specific overrides.

层叠配置使用离要检测的文件最近的 .eslintrc文件作为最高优先级,然后才是父目录里的配置文件,等等。当你在这个项目中允许 ESLint 时,lib/ 下面的所有文件将使用项目根目录里的 .eslintrc 文件作为它的配置文件。当 ESLint 遍历到 test/ 目录,your-project/.eslintrc 之外,它还会用到 your-project/tests/.eslintrc。所以 your-project/tests/test.js 是基于它的目录层次结构中的两个.eslintrc 文件的组合,并且离的最近的一个优先。通过这种方式,你可以有项目级 ESLint 设置,也有覆盖特定目录的 ESLint 设置。

In the same way, if there is a package.json file in the root directory with an eslintConfig field, the configuration it describes will apply to all subdirectories beneath it, but the configuration described by the .eslintrc file in the tests directory will override it where there are conflicting specifications.

同样的,如果在根目录的 package.json 文件中有一个 eslintConfig 字段,其中的配置将使用于所有子目录,但是当 tests 目录下的 .eslintrc 文件中的规则与之发生冲突时,就会覆盖它。

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

If there is an .eslintrc and a package.json file found in the same directory, .eslintrc will take a priority and package.json file will not be used.

如果同一目录下 .eslintrcpackage.json 同时存在,.eslintrc 优先级高会被使用,package.json 文件将不会被使用。

Note: If you have a personal configuration file in your home directory (~/.eslintrc), it will only be used if no other configuration files are found. Since a personal configuration would apply to everything inside of a user’s directory, including third-party code, this could cause problems when running ESLint.

注意:如果在你的主目录下有一个自定义的配置文件 (~/.eslintrc) ,如果没有其它配置文件时它才会被使用。因为个人配置将适用于用户目录下的所有目录和文件,包括第三方的代码,当 ESLint 运行时可能会导致问题。

By default, ESLint will look for configuration files in all parent folders up to the root directory. This can be useful if you want all of your projects to follow a certain convention, but can sometimes lead to unexpected results. To limit ESLint to a specific project, place "root": true inside the eslintConfig field of the package.json file or in the .eslintrc.* file at your project’s root level. ESLint will stop looking in parent folders once it finds a configuration with "root": true.

默认情况下,ESLint 会在所有父级目录里寻找配置文件,一直到根目录。如果你想要你所有项目都遵循一个特定的约定时,这将会很有用,但有时候会导致意想不到的结果。为了将 ESLint 限制到一个特定的项目,在你项目根目录下的 package.json 文件或者 .eslintrc.* 文件里的 eslintConfig 字段下设置 "root": true。ESLint 一旦发现配置文件中有 "root": true,它就会停止在父级目录中寻找。

{
    "root": true
}

And in YAML:

在 YAML 中:

---
  root: true

For example, consider projectA which has "root": true set in the .eslintrc file in the lib/ directory. In this case, while linting main.js, the configurations within lib/ will be used, but the .eslintrc file in projectA/ will not.

例如,projectAlib/ 目录下的 .eslintrc 文件中设置了 "root": true。这种情况下,当检测 main.js 时,lib/ 下的配置将会被使用,projectA/ 下的 .eslintrc 将不会被使用。

home
└── user
    ├── .eslintrc <- Always skipped if other configs present
    └── projectA
        ├── .eslintrc  <- Not used
        └── lib
            ├── .eslintrc  <- { "root": true }
            └── main.js

The complete configuration hierarchy, from highest precedence to lowest precedence, is as follows:

完整的配置层次结构,从最高优先级最低的优先级,如下:

  1. Inline configuration
  2. 行内配置
    1. /*eslint-disable*/ and /*eslint-enable*/
    2. /*eslint-disable*//*eslint-enable*/
    3. /*global*/
    4. /*global*/
    5. /*eslint*/
    6. /*eslint*/
    7. /*eslint-env*/
    8. /*eslint-env*/
  3. Command line options (or CLIEngine equivalents):
  4. 命令行选项(或 CLIEngine 等价物):
    1. --global
    2. --global
    3. --rule
    4. --rule
    5. --env
    6. --env
    7. -c, --config
    8. -c--config
  5. Project-level configuration:
  6. 项目级配置:
    1. .eslintrc.* or package.json file in same directory as linted file
    2. 与要检测的文件在同一目录下的 .eslintrc.*package.json 文件
    3. Continue searching for .eslintrc and package.json files in ancestor directories (parent has highest precedence, then grandparent, etc.), up to and including the root directory or until a config with "root": true is found.
    4. 继续在父级目录寻找 .eslintrcpackage.json文件,直到根目录(包括根目录)或直到发现一个有"root": true的配置。
  7. In the absence of any configuration from (1) through (3), fall back to a personal default configuration in ~/.eslintrc.
  8. 如果不是(1)到(3)中的任何一种情况,退回到 ~/.eslintrc 中自定义的默认配置。

Extending Configuration Files

A configuration file can extend the set of enabled rules from base configurations.

一个配置文件可以被基础配置中的已启用的规则继承。

The extends property value is either:

extends 属性值可以是:

ESLint extends configurations recursively, so a base configuration can also have an extends property. Relative paths and shareable config names in an extends property are resolved from the location of the config file where they appear.

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

The rules property can do any of the following to extend (or override) the set of rules:

rules 属性可以做下面的任何事情以扩展(或覆盖)规则:

Using "eslint:recommended"

An extends property value "eslint:recommended" enables a subset of core rules that report common problems, which have a check mark on the rules page. The recommended subset can change only at major versions of ESLint.

值为 "eslint:recommended"extends 属性启用一系列核心规则,这些规则报告一些常见问题,在 规则页面 中被标记为 。这个推荐的子集只能在 ESLint 主要版本进行更新。

If your configuration extends the recommended rules: after you upgrade to a newer major version of ESLint, review the reported problems before you use the --fix option on the command line, so you know if a new fixable recommended rule will make changes to the code.

如果你的配置集成了推荐的规则:在你升级到 ESLint 新的主版本之后,在你使用命令行--fix 选项之前,检查一下报告的问题,这样你就知道一个新的可修复的推荐的规则将更改代码。

The eslint --init command can create a configuration so you can extend the recommended rules.

eslint --init 命令可以创建一个配置,这样你就可以继承推荐的规则。

Example of a configuration file in JavaScript format:

JavaScript 格式的一个配置文件的例子:

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

        // override default options for rules from base configurations
        "comma-dangle": ["error", "always"],
        "no-cond-assign": ["error", "always"],

        // disable rules from base configurations
        "no-console": "off",
    }
}

Using a shareable configuration package

A sharable configuration is an npm package that exports a configuration object. Make sure the package has been installed to a directory where ESLint can require it.

可共享的配置 是一个 npm 包,它输出一个配置对象。要确保这个包安装在 ESLint 能请求到的目录下。

The extends property value can omit the eslint-config- prefix of the package name.

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

The eslint --init command can create a configuration so you can extend a popular style guide (for example, eslint-config-standard).

eslint --init 命令可以创建一个配置,这样你就可以扩展一个流行的风格指南(比如,eslint-config-standard)。

Example of a configuration file in YAML format:

YAML 格式的一个配置文件的例子:

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

Using the configuration from a plugin

A plugin is an npm package that usually exports rules. Some plugins also export one or more named configurations. Make sure the package has been installed to a directory where ESLint can require it.

插件 是一个 npm 包,通常输出规则。一些插件也可以输出一个或多个命名的 配置。要确保这个包安装在 ESLint 能请求到的目录下。

The plugins property value can omit the eslint-plugin- prefix of the package name.

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

The extends property value can consist of:

extends 属性值可以由以下组成:

Example of a configuration file in JSON format:

JSON 格式的一个配置文件的例子:

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

Using a configuration file

The extends property value can be an absolute or relative path to a base configuration file. ESLint resolves a relative path to a base configuration file relative to the configuration file that uses it.

extends 属性值可以是到基本配置文件的绝对路径,也可以是相对路径。ESLint 解析一个相对于使用它的配置文件的基本配置文件的相对路径。

ESLint resolves a relative path to a base configuration file relative to the configuration file that uses it unless that file is in your home directory or a directory that isn’t an ancestor to the directory in which ESLint is installed (either locally or globally). In those cases, ESLint resolves the relative path to the base file relative to the linted project directory (typically the current working directory).

ESLint 解析基本配置文件的相对路径相对你你使用的配置文件,除非那个文件在你的主目录或非 ESLint 安装目录的父级目录。在这些情况下,ESLint 解析基本配合文件的相对路径相对于被检测的 项目目录(尤其是当前工作目录)。

Example of a configuration file in JSON format:

JSON 格式的一个配置文件的例子:

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

Using "eslint:all"

The extends property value can be "eslint:all" to enable all core rules in the currently installed version of ESLint. The set of core rules can change at any minor or major version of ESLint.

extends 属性值可以是 "eslint:all",启用当前安装的 ESLint 中所有的核心规则。这些规则可以在 ESLint 的任何版本进行更改。

Important: This configuration is not recommended for production use because it changes with every minor and major version of ESLint. Use at your own risk.

重要:这些配置 不推荐在产品中使用,因为它随着 ESLint 版本进行更改。使用的话,请自己承担风险。

If you configure ESLint to automatically enable new rules when you upgrade, ESLint can report new problems when there are no changes to source code, therefore any newer minor version of ESLint can behave as if it has breaking changes.

如果你配置 ESLint 升级时自动地启用新规则,当源码没有任何改变时,ESLint 可以报告新问题,因此任何 ESLint 的新的小版本好像有破坏性的更改。

You might enable all core rules as a shortcut to explore rules and options while you decide on the configuration for a project, especially if you rarely override options or disable rules. The default options for rules are not endorsements by ESLint (for example, the default option for the quotes rule does not mean double quotes are better than single quotes).

当你决定在一个项目上使用的规则和选项,尤其是如果你很少覆盖选项或禁用规则,你可能启用所有核心规则作为一种快捷方式使用。规则的默认选项并不是 ESLint 推荐的(例如,quotes 规则的默认选项并不意味着双引号要比单引号好)。

If your configuration extends all core rules: after you upgrade to a newer major or minor version of ESLint, review the reported problems before you use the --fix option on the command line, so you know if a new fixable rule will make changes to the code.

如果你的配置扩展了所有的核心规则:在你升级到一个新的大或小的 ESLint 版本,在你使用命令行--fix 选项之前,检查一下报告的问题,这样你就知道一个新的可修复的规则将更改代码。

Example of a configuration file in JavaScript format:

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",
    }
}

Configuration Based on Glob Patterns

v4.1.0+. Sometimes a more fine-controlled configuration is necessary, for example if the configuration for files within the same directory has to be different. Therefore you can provide configurations under the overrides key that will only apply to files that match specific glob patterns, using the same format you would pass on the command line (e.g., app/**/*.test.js).

v4.1.0+. 有时,你可能需要更精细的配置,比如,如果同一个目录下的文件需要有不同的配置。因此,你可以在配置中使用 overrides 键,它只适用于匹配特定的 glob 模式的文件,使用你在命令行上传递的格式 (e.g., app/**/*.test.js)。

How it works

Relative glob patterns

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

The config in app/.eslintrc.json defines the glob pattern **/*Spec.js. This pattern is relative to the base directory of app/.eslintrc.json. So, this pattern would match app/lib/fooSpec.js and app/components/barSpec.js but NOT server/serverSpec.js. If you defined the same pattern in the .eslintrc.json file within in the project-root folder, it would match all three of the *Spec files.

app/.eslintrc.json 文件中的配置定义了 **/*Spec.js glob 模式。该模式相对于 app/.eslintrc.json 的基准目录。因此,该模式匹配 app/lib/fooSpec.jsapp/components/barSpec.js,但 不匹配 server/serverSpec.js。如果你在项目根目录的 .eslintrc.json 文件中定义相同的模式,它将匹配所有三个 *Spec 文件。

Example configuration

In your .eslintrc.json:

在你的 .eslintrc.json 文件中:

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

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

Comments in Configuration Files

Both the JSON and YAML configuration file formats support comments (package.json files should not include them). You can use JavaScript-style comments or YAML-style comments in either type of file and ESLint will safely ignore them. This allows your configuration files to be more human-friendly. For example:

JSON 和 YAML 配置文件格式都支持注释 ( package.json 文件不应该包括注释)。你可以在其他类型的文件中使用 JavaScript 风格的注释或使用 YAML 风格的注释,ESLint 会忽略它们。这允许你的配置更加人性化。例如:

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

Specifying File extensions to Lint

Currently the sole method for telling ESLint which file extensions to lint is by specifying a comma separated list of extensions using the --ext command line option. Note this flag only takes effect in conjunction with directories, and will be ignored if used with filenames or glob patterns.

目前,告诉 ESLint 哪个文件扩展名要检测的唯一方法是使用 --ext 命令行选项指定一个逗号分隔的扩展名列表。注意,该标记只在与目录一起使用时有效,如果使用文件名或 glob 模式,它将会被忽略。

Ignoring Files and Directories

.eslintignore

You can tell ESLint to ignore specific files and directories by creating an .eslintignore file in your project’s root directory. The .eslintignore file is a plain text file where each line is a glob pattern indicating which paths should be omitted from linting. For example, the following will omit all JavaScript files:

你可以通过在项目根目录创建一个 .eslintignore 文件告诉 ESLint 去忽略特定的文件和目录。.eslintignore 文件是一个纯文本文件,其中的每一行都是一个 glob 模式表明哪些路径应该忽略检测。例如,以下将忽略所有的 JavaScript 文件:

**/*.js

When ESLint is run, it looks in the current working directory to find an .eslintignore file before determining which files to lint. If this file is found, then those preferences are applied when traversing directories. Only one .eslintignore file can be used at a time, so .eslintignore files other than the one in the current working directory will not be used.

当 ESLint 运行时,在确定哪些文件要检测之前,它会在当前工作目录中查找一个 .eslintignore 文件。如果发现了这个文件,当遍历目录时,将会应用这些偏好设置。一次只有一个 .eslintignore 文件会被使用,所以,不是当前工作目录下的 .eslintignore 文件将不会被用到。

Globs are matched using node-ignore, so a number of features are available:

Globs 匹配使用 node-ignore,所以大量可用的特性有:

Of particular note is that like .gitignore files, all paths used as patterns for both .eslintignore and --ignore-pattern must use forward slashes as their path separators.

特别值得注意的是,就像 .gitignore 文件,所有用作 .eslintignore--ignore-pattern 模式的路径必须使用前斜杠作为它们的路径分隔符。

# Valid
/root/src/*.js

# Invalid
\root\src\*.js

Please see .gitignore’s specification for further examples of valid syntax.

请参参阅 .gitignore 规范查看有关有效语法的更多示例。

In addition to any patterns in a .eslintignore file, ESLint always ignores files in /node_modules/* and /bower_components/*.

除了 .eslintignore 文件中的模式,ESLint总是忽略 /node_modules/*/bower_components/* 中的文件。

For example, placing the following .eslintignore file in the current working directory will ignore all of node_modules, bower_components in the project root and anything in the build/ directory except build/index.js:

例如:把下面 .eslintignore 文件放到当前工作目录里,将忽略项目根目录下的 node_modulesbower_components 以及 build/ 目录下除了 build/index.js 的所有文件。

# /node_modules/* and /bower_components/* in the project root are ignored by default

# Ignore built files except build/index.js
build/*
!build/index.js

Important: Note that node_modules directories in, for example, a packages directory in a mono repo are not ignored by default and need to be added to .eslintignore explicitly.

重要:注意代码库的 node_modules 目录,比如,一个 packages 目录,默认情况下不会被忽略,需要手动添加到 .eslintignore

Using an Alternate File

If you’d prefer to use a different file than the .eslintignore in the current working directory, you can specify it on the command line using the --ignore-path option. For example, you can use .jshintignore file because it has the same format:

如果相比于当前工作目录下 .eslintignore 文件,你更想使用一个不同的文件,你可以在命令行使用 --ignore-path 选项指定它。例如,你可以使用 .jshintignore 文件,因为它有相同的格式:

eslint --ignore-path .jshintignore file.js

You can also use your .gitignore file:

你也可以使用你的 .gitignore 文件:

eslint --ignore-path .gitignore file.js

Any file that follows the standard ignore file format can be used. Keep in mind that specifying --ignore-path means that any existing .eslintignore file will not be used. Note that globbing rules in .eslintignore follow those of .gitignore.

任何文件只要满足标准忽略文件格式都可以用。记住,指定 --ignore-path 意味着任何现有的 .eslintignore 文件将不被使用。请注意,.eslintignore 中的匹配规则比 .gitignore 中的更严格。

Using eslintIgnore in package.json

If an .eslintignore file is not found and an alternate file is not specified, ESLint will look in package.json for an eslintIgnore key to check for files to ignore.

如果没有发现 .eslintignore 文件,也没有指定替代文件,ESLint 将在 package.json 文件中查找 eslintIgnore 键,来检查要忽略的文件。

{
  "name": "mypackage",
  "version": "0.0.1",
  "eslintConfig": {
      "env": {
          "browser": true,
          "node": true
      }
  },
  "eslintIgnore": ["hello.js", "world.js"]
}

Ignored File Warnings

When you pass directories to ESLint, files and directories are silently ignored. If you pass a specific file to ESLint, then you will see a warning indicating that the file was skipped. For example, suppose you have an .eslintignore file that looks like this:

当你传递目录给 ESLint,文件和目录是默默被忽略的。如果你传递一个指定的文件给 ESLint,你会看到一个警告,表明该文件被跳过了。例如,假如你有一个像这样的 .eslintignore文件:

foo.js

And then you run:

然后你执行:

eslint foo.js

You’ll see this warning:

你将会看到这个警告:

foo.js
  0:0  warning  File ignored because of your .eslintignore file. Use --no-ignore to override.

✖ 1 problem (0 errors, 1 warning)

This message occurs because ESLint is unsure if you wanted to actually lint the file or not. As the message indicates, you can use --no-ignore to omit using the ignore rules.

这种消息出现是因为 ESLint 不确定你是否想检测文件。正如这个消息表明的那样,你可以使用 --no-ignore 覆盖忽略的规则。