命令行接口参考手册

ESLint 命令行界面 (CLI) 允许您从终端执行 linting。 CLI 有多种选项,您可以传递这些选项来配置 ESLint。

运行 CLI

ESLint 需要 Node.js 来安装。 按照 入门指南 中的说明安装 ESLint。

大多数用户使用 npx 在命令行上运行 ESLint,如下所示:

npx eslint [options] [file|dir|glob]*

如:

<a id="run-on-two-files"></a>

# 在两个文件上运行
npx eslint file1.js file2.js

<a id="run-on-multiple-files"></a>

# 在多个文件上运行
npx eslint lib/**

请注意,当传递一个 glob 作为参数时,它会被你的 shell 扩展。 扩展的结果可能因您的 shell 及其配置而异。 如果要使用 node glob 语法,则必须引用参数(如果需要在 Windows 中运行,请使用双引号),如下所示:

npx eslint "lib/**"

**注意:**您还可以使用其他包管理器(例如 Yarnpnpm)来运行 ESLint。 请参阅您的包管理器的文档以了解正确的语法。

将多个值传递给一个选项

接受多个值的选项可以通过重复选项或用逗号分隔的列表来指定(--ignore-pattern 除外,它不允许第二种样式)。

接受多个值的选项示例:

npx eslint --ext .jsx --ext .js lib/
<a id="or"></a>

# 或
npx eslint --ext .jsx,.js lib/

选项

您可以通过运行 npx eslint -h 查看所有 CLI 选项。

eslint [options] file.js [file.js] [dir]

Basic configuration:
  --no-eslintrc                   Disable use of configuration from .eslintrc.*
  -c, --config path::String       Use this configuration, overriding .eslintrc.* config options if present
  --env [String]                  Specify environments
  --ext [String]                  Specify JavaScript file extensions
  --global [String]               Define global variables
  --parser String                 Specify the parser to be used
  --parser-options Object         Specify parser options
  --resolve-plugins-relative-to path::String  A folder where plugins should be resolved from, CWD by default

Specify rules and plugins:
  --plugin [String]               Specify plugins
  --rule Object                   Specify rules
  --rulesdir [path::String]       Load additional rules from this directory. Deprecated: Use rules from plugins

Fix problems:
  --fix                           Automatically fix problems
  --fix-dry-run                   Automatically fix problems without saving the changes to the file system
  --fix-type Array                Specify the types of fixes to apply (directive, problem, suggestion, layout)

Ignore files:
  --ignore-path path::String      Specify path of ignore file
  --no-ignore                     Disable use of ignore files and patterns
  --ignore-pattern [String]       Pattern of files to ignore (in addition to those in .eslintignore)

Use stdin:
  --stdin                         Lint code provided on <STDIN> - default: false
  --stdin-filename String         Specify filename to process STDIN as

Handle warnings:
  --quiet                         Report errors only - default: false
  --max-warnings Int              Number of warnings to trigger nonzero exit code - default: -1

Output:
  -o, --output-file path::String  Specify file to write report to
  -f, --format String             Use a specific output format - default: stylish
  --color, --no-color             Force enabling/disabling of color

Inline configuration comments:
  --no-inline-config              Prevent comments from changing config or rules
  --report-unused-disable-directives  Adds reported errors for unused eslint-disable directives

Caching:
  --cache                         Only check changed files - default: false
  --cache-file path::String       Path to the cache file. Deprecated: use --cache-location - default: .eslintcache
  --cache-location path::String   Path to the cache file or directory
  --cache-strategy String         Strategy to use for detecting changed files in the cache - either: metadata or content - default: metadata

Miscellaneous:
  --init                          Run config initialization wizard - default: false
  --env-info                      Output execution environment information - default: false
  --no-error-on-unmatched-pattern  Prevent errors when pattern is unmatched
  --exit-on-fatal-error           Exit with exit code 2 in case of fatal error - default: false
  --debug                         Output debugging information
  -h, --help                      Show help
  -v, --version                   Output the version number
  --print-config path::String     Print the configuration for the given file

基本配置

--no-eslintrc

禁止使用来自 .eslintrc.*package.json 文件的配置。

  • 参数类型: 没有参数。

--no-eslintrc 示例
npx eslint --no-eslintrc file.js

-c--config

这个选项允许你为 ESLint 指定一个额外的配置文件(更多信息参见 配置 ESLint)。

  • 参数类型: 字符串。 文件路径。
  • 多个参数: 不

-c--config 示例
npx eslint -c ~/my-eslint.json file.js

本例使用 ~/my-eslint.json 的配置文件。

如果 .eslintrc.* 和/或 package.json 文件也用于配置(即未指定 --no-eslintrc),则合并配置。 此配置文件中的选项优先于 .eslintrc.*package.json 文件中的选项。

--env

此选项启用特定环境。

  • 参数类型: 字符串。 可用环境之一。
  • 多个参数: 是的

指定环境 文档中提供了有关每个环境定义的全局变量的详细信息。 此选项仅启用环境。 它不会禁用在其他配置文件中设置的环境。 要指定多个环境,请使用逗号分隔它们,或多次使用该选项。

--env 示例
npx eslint --env browser,node file.js
npx eslint --env browser --env node file.js

--ext

此选项允许您指定 ESLint 在您指定的目录中搜索目标文件时使用的文件扩展名。

  • 参数类型: 字符串。 文件扩展名。
  • 多个参数: 是的
  • 默认值.js 和与配置的 overrides 条目匹配的文件。

--ext 仅在 lint 的模式是目录时使用。 如果您使用 glob 模式或文件名,则 --ext 将被忽略。 例如,npx eslint "lib/*" --ext .js 匹配 lib/ 目录中的所有文件,无论扩展名如何。

--ext 示例
<a id="use-only-ts-extension"></a>

# 仅使用 .ts 扩展名
npx eslint . --ext .ts

<a id="use-both-js-and-ts"></a>

# 同时使用 .js 和 .ts
npx eslint . --ext .js --ext .ts

<a id="also-use-both-js-and-ts"></a>

# 同时使用 .js 和 .ts
npx eslint . --ext .js,.ts

--global

此选项定义全局变量,以便它们不会被 no-undef 规则标记为未定义。

  • 参数类型: 字符串。 全局变量的名称。 默认情况下,假定任何指定的全局变量都是只读的,但将 :true 附加到变量名称可确保 no-undef 也允许写入。
  • 多个参数: 是的

--global 示例
npx eslint --global require,exports:true file.js
npx eslint --global require --global exports:true

--parser

此选项允许您指定 ESLint 使用的解析器。

  • 参数类型: 字符串。 ESLint 使用的解析器。
  • 多个参数: 不
  • 默认值espree

--parser 示例
<a id="use-typescript-eslint-parser"></a>

# 使用 TypeScript ESLint 解析器
npx eslint --parser @typescript-eslint/parser file.ts

--parser-options

此选项允许您指定 ESLint 使用的解析器选项。 可用的解析器选项由正在使用的解析器决定。

  • 参数类型: 以冒号 (:) 分隔的键/值对。
  • 多个参数: 是的

--parser-options 示例
echo '3 ** 4' | npx eslint --stdin --parser-options ecmaVersion:6 # fails with a parsing error
echo '3 ** 4' | npx eslint --stdin --parser-options ecmaVersion:7 # succeeds, yay!

--resolve-plugins-relative-to

更改解析插件的目录。

  • 参数类型: 字符串。 目录路径。
  • 多个参数: 不
  • 默认值: 默认情况下,插件从找到配置文件的目录中解析。

当插件由最终用户以外的人安装时,应使用此选项。 它应该设置为依赖于必要插件的项目的项目目录。

例如:

  • 当使用位于当前项目之外的配置文件(带有 --config 标志)时,如果配置使用本地安装的插件,则应将 --resolve-plugins-relative-to 设置为包含配置文件的目录。
  • 如果一个集成依赖于 ESLint 和一组插件,并且该工具使用预设配置代表用户调用 ESLint,则该工具应将 --resolve-plugins-relative-to 设置为该工具的顶级目录。

--resolve-plugins-relative-to 示例
npx eslint --config ~/personal-eslintrc.js \
--resolve-plugins-relative-to /usr/local/lib/

指定规则和插件

--plugin

此选项指定要加载的插件。

  • 参数类型: 字符串。 插件名称。 您可以选择从插件名称中省略前缀 eslint-plugin-
  • 多个参数: 是的

在使用插件之前,您必须使用 npm 安装它。

--plugin 示例
npx eslint --plugin jquery file.js
npx eslint --plugin eslint-plugin-mocha file.js

--rule

此选项指定要使用的规则。

  • 参数类型: 规则及其配置以 levn 格式指定。
  • 多个参数: 是的

这些规则与配置文件指定的任何规则合并。 如果规则是在插件中定义的,则必须在规则 ID 前加上插件名称和 /

要忽略 .eslintrc 配置文件中的规则并仅运行命令行中指定的规则,请结合使用 --rules 标志和 --no-eslintrc 标志。

--rule 示例
<a id="apply-single-rule"></a>

# 应用单一规则
npx eslint --rule 'quotes: [error, double]'
<a id="apply-multiple-rules"></a>

# 应用多个规则
npx eslint --rule 'guard-for-in: error' --rule 'brace-style: [error, 1tbs]'
<a id="apply-rule-from-jquery-plugin"></a>

# 从 jquery 插件应用规则
npx eslint --rule 'jquery/dollar-sign: error'
<a id="only-apply-rule-from-the-command-line"></a>

# 仅从命令行应用规则
npx eslint --rule 'quotes: [error, double]' --no-eslintrc

--rulesdir

已弃用: 改用插件中的规则。

此选项允许您指定另一个目录来加载规则文件。 这允许您在运行时动态加载新规则。 当您有不适合与 ESLint 捆绑的自定义规则时,这很有用。

  • 参数类型: 字符串。 目录路径。 自定义规则目录中的规则必须遵循与捆绑规则相同的格式才能正常工作。
  • 多个参数: 是的。

请注意,与核心规则和插件规则一样,您仍然需要在配置中或通过 --rule CLI 选项启用规则,以便在 linting 期间实际运行这些规则。 使用 --rulesdir 指定规则目录不会自动启用该目录中的规则。

--rulesdir 示例
npx eslint --rulesdir my-rules/ file.js
npx eslint --rulesdir my-rules/ --rulesdir my-other-rules/ file.js

修复问题

--fix

此选项指示 ESLint 尝试修复尽可能多的问题。 对实际文件本身进行了修复,仅输出剩余的未修复问题。

  • 参数类型: 没有参数。

并非所有问题都可以使用此选项解决,并且该选项在以下情况下不起作用:

  1. 当代码通过管道传输到 ESLint 时,此选项会引发错误。
  2. 此选项对使用处理器的代码没有影响,除非处理器选择允许自动修复。

如果您想修复来自 stdin 的代码,或者想要获得修复而不实际将它们写入文件,请使用 --fix-dry-run 选项。

--fix 示例
npx eslint --fix file.js

--fix-dry-run

此选项与 --fix 具有相同的效果,区别在于修复不会保存到文件系统。 因为默认格式化程序不输出固定代码,所以您必须使用另一个格式化程序(例如 --format json)来获得修复。

  • 参数类型: 没有参数。

这使得在与 --stdin 标志一起使用时可以修复来自 stdin 的代码。

此标志对于需要从命令行自动修复文本而不将其保存到文件系统的集成(例如编辑器插件)很有用。

--fix-dry-run 示例
getSomeText | npx eslint --stdin --fix-dry-run --format json

--fix-type

此选项允许您指定在使用 --fix--fix-dry-run 时应用的修复类型。

  • 参数类型: 字符串。 以下修复类型之一:
    1. problem - 修复代码中的潜在错误
    2. suggestion - 将修复应用于改进它的代码
    3. layout - 应用不改变程序结构 (AST) 的修复
    4. directive - 将修复应用于内联指令,例如 // eslint-disable
  • 多个参数: 是的

如果您正在使用另一个程序来格式化代码,但您仍然希望 ESLint 应用其他类型的修复,则此选项很有用。

--fix-type 示例
npx eslint --fix --fix-type suggestion .
npx eslint --fix --fix-type suggestion --fix-type problem .
npx eslint --fix --fix-type suggestion,layout .

忽略文件

--ignore-path

此选项允许您指定要用作 .eslintignore 的文件。

  • 参数类型: 字符串。 文件路径。
  • 多个参数: 不
  • 默认值: 默认情况下,ESLint 在当前工作目录中查找 .eslintignore

注意: 使用 平面配置 (eslint.config.js) 时不支持 --ignore-path

--ignore-path 示例
npx eslint --ignore-path tmp/.eslintignore file.js
npx eslint --ignore-path .gitignore file.js

--no-ignore

禁止从 .eslintignore 文件、--ignore-path 标志、--ignore-pattern 标志和配置文件中的 ignorePatterns 属性中排除文件。

  • 参数类型: 没有参数。

--no-ignore 示例
npx eslint --no-ignore file.js

--ignore-pattern

此选项允许您指定要忽略的文件模式(除了 .eslintignore 中的那些)。

  • 参数类型: 字符串。 支持的语法与 .eslintignore 文件 相同,它使用与 .gitignore 规范 相同的模式。 您应该引用您的模式以避免对 glob 模式的 shell 解释。
  • 多个参数: 是的

--ignore-pattern 示例
npx eslint --ignore-pattern "/lib/" --ignore-pattern "/src/vendor/*" .

使用标准输入

--stdin

这个选项告诉 ESLint 从 STDIN 而不是从文件中读取和检查源代码。 您可以使用它将代码通过管道传输到 ESLint。

  • 参数类型: 没有参数。

--stdin 示例
cat myfile.js | npx eslint --stdin

--stdin-filename

此选项允许您指定一个文件名来处理 STDIN。

  • 参数类型: 字符串。 文件路径。
  • 多个参数: 不

这在处理来自 STDIN 的文件并且您有依赖于文件名的规则时很有用。

--stdin-filename 示例
cat myfile.js | npx eslint --stdin --stdin-filename myfile.js

处理警告

--quiet

此选项允许您禁用警告报告。 如果启用此选项,则 ESLint 仅报告错误。

  • 参数类型: 没有参数。

--quiet 示例
npx eslint --quiet file.js

--max-warnings

此选项允许您指定警告阈值,如果您的项目中有太多警告级别的规则违规,可用于强制 ESLint 以错误状态退出。

  • 参数类型: 整数。 允许的最大警告数。 要防止此行为,请不要使用此选项或将 -1 指定为参数。
  • 多个参数: 不

通常,如果 ESLint 运行并且没有发现错误(只有警告),它会以成功退出状态退出。 但是,如果指定了 --max-warnings 并且警告总数大于指定的阈值,ESLint 将以错误状态退出。

--max-warnings 示例
npx eslint --max-warnings 10 file.js

输出

-o--output-file

将 linting 结果的输出写入指定文件。

  • 参数类型: 字符串。 文件路径。
  • 多个参数: 不

-o--output-file 示例
npx eslint -o ./test/test.html

-f--format

此选项指定控制台的输出格式。

  • 参数类型: 字符串。 内置格式化器 之一或自定义格式化程序。
  • 多个参数: 不
  • 默认值stylish

如果您使用的是在本地文件中定义的自定义格式化程序,则可以指定自定义格式化程序文件的路径。

使用或不使用 eslint-formatter- 前缀解析 npm 安装的格式化程序。

指定时,将给定格式输出到控制台。 如果您想将该输出保存到文件中,可以在命令行中执行此操作,如下所示:

<a id="saves-the-output-into-the-resultstxt-file"></a>

# 将输出保存到 `results.txt` 文件中。
npx eslint -f compact file.js > results.txt

-f--format 示例

使用内置的 compact 格式化程序:

npx eslint --format compact file.js

使用本地自定义格式化程序:

npx eslint -f ./customformat.js file.js

使用 npm 安装的格式化程序:

npm install eslint-formatter-pretty

<a id="then-run-one-of-the-following-commands"></a>

# 然后运行以下命令之一
npx eslint -f pretty file.js
# or alternatively
npx eslint -f eslint-formatter-pretty file.js

--color--no-color

这些选项强制启用/禁用彩色输出。

  • 参数类型: 没有参数。

您可以使用这些选项来覆盖默认行为,即启用彩色输出,除非未检测到 TTY,例如当管道 eslintcatless 时。

--color--no-color 示例
npx eslint --color file.js | cat
npx eslint --no-color file.js

内联配置注释

--no-inline-config

此选项可防止 /*eslint-disable*//*global foo*/ 等内联注释产生任何影响。

  • 参数类型: 没有参数。

这允许您设置 ESLint 配置,而无需文件修改它。 所有内联配置注释都将被忽略,例如:

  • /*eslint-disable*/
  • /*eslint-enable*/
  • /*global*/
  • /*eslint*/
  • /*eslint-env*/
  • // eslint-disable-line
  • // eslint-disable-next-line

--no-inline-config 示例
npx eslint --no-inline-config file.js

--report-unused-disable-directives

此选项会导致 ESLint 报告指令注释,如 // eslint-disable-line 无论如何不会在该行上报告错误。

  • 参数类型: 没有参数。

通过清理不再适用的旧 eslint-disable 注释,这有助于防止未来的错误被意外抑制。

--report-unused-disable-directives 示例
npx eslint --report-unused-disable-directives file.js

缓存

--cache

存储有关已处理文件的信息,以便仅对更改的文件进行操作。 启用此选项可以通过确保仅检查更改的文件来显着提高 ESLint 的运行时性能。 缓存默认存储在 .eslintcache 中。

  • 参数类型: 没有参数。

如果你用 --cache 运行 ESLint,然后在没有 --cache 的情况下运行 ESLint,.eslintcache 文件将被删除。 这是必要的,因为 lint 的结果可能会更改并使 .eslintcache 无效。 如果要控制何时删除缓存文件,请使用 --cache-location 指定缓存文件的备用位置。

自动修复的文件不会放在缓存中。 不触发自动修复的后续 linting 会将其放入缓存中。

--cache 示例
npx eslint --cache file.js

--cache-file

已弃用: 请改用 --cache-location

缓存文件的路径。 如果没有使用指定的 .eslintcache。 该文件在执行 eslint 命令的目录中创建。

--cache-location

指定缓存位置的路径。 可以是文件或目录。

  • 参数类型: 字符串。 文件或目录的路径。 如果指定了目录,则会在指定文件夹内创建缓存文件。 该文件的名称基于当前工作目录的哈希值,例如: .cache_hashOfCWD
  • 多个参数: 不
  • 默认值: 如果未指定位置,则使用 .eslintcache。 该文件在执行 eslint 命令的目录中创建。

如果缓存目录不存在,请确保在 *nix 系统上添加尾随 / 或在 Windows 上添加 \。 否则,该路径被假定为一个文件。

--cache-location 示例
npx eslint "src/**/*.js" --cache --cache-location "/Users/user/.eslintcache/"

--cache-strategy

用于检测更改文件的缓存策略。

  • 参数类型: 字符串。 以下值之一:
    1. metadata
    2. content
  • 多个参数: 不
  • 默认值metadata

content 策略在文件的修改时间发生变化但内容没有变化的情况下很有用。 例如,这可能发生在像 git clone 这样的 git 操作期间,因为 git 不跟踪文件修改时间。

--cache-strategy 示例
npx eslint "src/**/*.js" --cache --cache-strategy content

其他

--init

此选项运行 npm init @eslint/config 以启动配置初始化向导。 它旨在通过回答几个问题帮助新用户快速创建 .eslintrc 文件。 当您使用此标志时,CLI 不会执行 linting。

  • 参数类型: 没有参数。

生成的配置文件在当前目录中创建。

--init 示例
npx eslint --init

--env-info

此选项输出有关执行环境的信息,包括 Node.js、npm 的版本以及 ESLint 的本地和全局安装。

  • 参数类型: 没有参数。

ESLint 团队可能会要求提供此信息以帮助解决错误。 当您使用此标志时,CLI 不会执行 linting。

--env-info 示例
npx eslint --env-info

--no-error-on-unmatched-pattern

当引用的 glob 模式或 --ext 不匹配时,此选项可防止错误。 当您的 shell 无法匹配 glob 时,这并不能防止错误。

  • 参数类型: 没有参数。

--no-error-on-unmatched-pattern 示例
npx eslint --no-error-on-unmatched-pattern --ext .ts "lib/*"

--exit-on-fatal-error

如果发生一个或多个致命的解析错误,此选项会导致 ESLint 以退出代码 2 退出。 如果没有此选项,ESLint 会将致命的解析错误报告为违反规则。

  • 参数类型: 没有参数。

--exit-on-fatal-error 示例
npx eslint --exit-on-fatal-error file.js

--debug

此选项将调试信息输出到控制台。 将此标志添加到 ESLint 命令行调用,以便在命令运行时获取额外的调试信息。

  • 参数类型: 没有参数。

当您发现问题并难以确定问题时,此信息很有用。 ESLint 团队可能会要求提供此调试信息以帮助解决错误。

--debug 示例
npx eslint --debug test.js

-h--help

此选项输出帮助菜单,显示所有可用选项。 当它存在时,所有其他选项都将被忽略。 当您使用此标志时,CLI 不会执行 linting。

  • 参数类型: 没有参数。

-h--help 示例
npx eslint --help

-v--version

此选项将当前 ESLint 版本输出到控制台。 当它存在时,所有其他选项都将被忽略。 当您使用此标志时,CLI 不会执行 linting。

  • 参数类型: 没有参数。

-v--version 示例
npx eslint --version

--print-config

此选项输出用于传递的文件的配置。 如果存在,则不会执行检查,并且只有与配置相关的选项有效。 当您使用此标志时,CLI 不会执行 linting。

  • 参数类型: 字符串。 文件路径。
  • 多个参数: 不

--print-config 示例
npx eslint --print-config file.js

退出码

对文件进行 linting 时,ESLint 会使用以下退出代码之一退出:

  • 0: Linting 成功并且没有 linting 错误。 如果 --max-warnings 标志设置为 n,则 linting 警告的数量最多为 n
  • 1: linting 成功并且至少存在一个 linting 错误,或者 linting 警告多于 --max-warnings 选项所允许的数量。
  • 2: 由于配置问题或内部错误,检查不成功。