配置语言选项

JavaScript 生态系统具有多种运行时、版本、扩展和框架。其中每一个都可以有不同的支持语法和全局变量。ESLint 允许你配置特定于项目中使用的 JavaScript 的语言选项,例如自定义全局变量。你还可以使用插件来扩展 ESLint 以支持你项目的语言选项。

¥The JavaScript ecosystem has a variety of runtimes, versions, extensions, and frameworks. Each of these can have different supported syntax and global variables. ESLint lets you configure language options specific to the JavaScript used in your project, like custom global variables. You can also use plugins to extend ESLint to support your project’s language options.

指定 JavaScript 选项

¥Specifying JavaScript Options

ESLint 允许你指定你想要支持的 JavaScript 语言选项。默认情况下,ESLint 需要最新的第 4 阶段 ECMAScript 语法和 ECMAScript 模块 (ESM) 模式。你可以使用 languageOptions 键并指定以下一个或多个属性来覆盖这些设置:

¥ESLint allows you to specify the JavaScript language options you want to support. By default, ESLint expects the most recent stage 4 ECMAScript syntax and ECMAScript modules (ESM) mode. You can override these settings by using the languageOptions key and specifying one or more of these properties:

  • ecmaVersion(默认:"latest") - 指示正在检查的代码的 ECMAScript 版本,确定语法和可用的全局变量。对于 ECMAScript 3 和 5,分别设置为 35。否则,你可以使用 2015 之间的任何年份来表示。在大多数情况下,我们建议使用默认值 "latest" 以确保你始终使用最新的 ECMAScript 版本。

    ¥ecmaVersion (default: "latest") - Indicates the ECMAScript version of the code being linted, determining both the syntax and the available global variables. Set to 3 or 5 for ECMAScript 3 and 5, respectively. Otherwise, you can use any year between 2015 to present. In most cases, we recommend using the default of "latest" to ensure you’re always using the most recent ECMAScript version.

  • sourceType(默认:"module") - 指示正在使用的 JavaScript 文件的模式。可能的值为:

    ¥sourceType (default: "module") - Indicates the mode of the JavaScript file being used. Possible values are:

    • module - ESM 模块(ecmaVersion35 时无效)。你的代码具有模块作用域并在严格模式下运行。

      ¥module - ESM module (invalid when ecmaVersion is 3 or 5). Your code has a module scope and is run in strict mode.

    • commonjs - CommonJS 模块(如果你的代码使用 require(),则很有用)。你的代码具有顶层函数作用域并在非严格模式下运行。

      ¥commonjs - CommonJS module (useful if your code uses require()). Your code has a top-level function scope and runs in non-strict mode.

    • script - 非模块。你的代码具有共享的全局作用域并在非严格模式下运行。

      ¥script - non-module. Your code has a shared global scope and runs in non-strict mode.

以下是你在检查 ECMAScript 5 代码时可能会使用的配置文件示例:

¥Here’s an example configuration file you might use when linting ECMAScript 5 code:

// eslint.config.js
export default [
    {
        languageOptions: {
            ecmaVersion: 5,
            sourceType: "script"
        }
    }
];

指定解析器选项

¥Specifying Parser Options

如果你使用内置的 ESLint 解析器,你还可以通过指定 languageOptions.parserOptions 键来更改 ESLint 解释代码的方式。默认情况下,所有选项均为 false

¥If you are using the built-in ESLint parser, you can additionally change how ESLint interprets your code by specifying the languageOptions.parserOptions key. All options are false by default:

  • allowReserved - 允许使用保留字作为标识符(如果 ecmaVersion3)。

    ¥allowReserved - allow the use of reserved words as identifiers (if ecmaVersion is 3).

  • ecmaFeatures - 一个对象,指示你要使用哪些附加语言功能:

    ¥ecmaFeatures - an object indicating which additional language features you’d like to use:

    • globalReturn - 在全局作用域内允许 return 语句

      ¥globalReturn - allow return statements in the global scope

    • impliedStrict - 启用全局 严格模式(如果 ecmaVersion5 或更大)

      ¥impliedStrict - enable global strict mode (if ecmaVersion is 5 or greater)

    • jsx - 启用 JSX

      ¥jsx - enable JSX

下面是一个在默认解析器中启用 JSX 解析的示例配置文件:

¥Here’s an example configuration file that enables JSX parsing in the default parser:

// eslint.config.js
export default [
    {
        languageOptions: {
            parserOptions: {
                ecmaFeatures: {
                    jsx: true
                }
            }
        }
    }
];

指定全局变量

¥Specifying Globals

ESLint 的一些核心规则依赖于代码在运行时可用的全局变量的知识。由于这些变量在不同环境之间可能会有很大差异,并且在运行时会被修改,因此 ESLint 不会假设你的执行环境中存在哪些全局变量。如果你想使用需要知道哪些全局变量可用的规则,你可以在配置文件中定义全局变量,或者在源代码中使用配置注释。

¥Some of ESLint’s core rules rely on knowledge of the global variables available to your code at runtime. Since these can vary greatly between different environments as well as be modified at runtime, ESLint makes no assumptions about what global variables exist in your execution environment. If you would like to use rules that require knowledge of what global variables are available, you can define global variables in your configuration file or by using configuration comments in your source code.

使用配置注释

¥Using configuration comments

要使用 JavaScript 文件中的注释指定全局变量,请使用以下格式:

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

/* global var1, var2 */

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

¥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:

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

使用配置文件

¥Using configuration files

要在配置文件中配置全局变量,请将 languageOptions.globals 配置属性设置为包含为你要使用的每个全局变量命名的键的对象。对于每个全局变量键,设置相应的值等于 "writable" 以允许变量被覆盖或 "readonly" 不允许覆盖。例如:

¥To configure global variables inside of a configuration file, set the languageOptions.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:

// eslint.config.js
export default [
    {
        languageOptions: {
            globals: {
                var1: "writable",
                var2: "readonly"
            }
        }
    }
];

此配置允许在代码中覆盖 var1,但不允许覆盖 var2

¥This configuration allows var1 to be overwritten in your code, but disallow it for var2.

可以通过将其值设置为 "off" 来禁用全局变量。例如,在大多数全局变量可用但 Promise 不可用的环境中,你可以使用以下配置:

¥Globals can be disabled by setting their value to "off". For example, in an environment where most globals are available but Promise is unavailable, you might use this config:

// eslint.config.js
export default [
    {
        languageOptions: {
            globals: {
                Promise: "off"
            }
        }
    }
];

预定义的全局变量

¥Predefined global variables

除了基于配置的 languageOptions.ecmaVersion 自动启用的 ECMAScript 标准内置全局变量外,ESLint 不提供预定义的全局变量集。你可以使用 globals 包为特定环境额外启用所有全局变量。例如,这里是如何将 console 以及其他浏览器全局变量添加到你的配置中。

¥Apart from the ECMAScript standard built-in globals, which are automatically enabled based on the configured languageOptions.ecmaVersion, ESLint doesn’t provide predefined sets of global variables. You can use the globals package to additionally enable all globals for a specific environment. For example, here is how you can add console, amongst other browser globals, into your configuration.

// eslint.config.js
import globals from "globals";

export default [
    {
        languageOptions: {
            globals: {
                ...globals.browser
            }
        }
    }
];