版本

命令行界面参考

ESLint 命令行界面 (CLI) 允许您从终端执行代码风格检查。CLI 有许多可以传递给配置 ESLint 的选项。

运行 CLI

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

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

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

例如

# Run on two files
npx eslint file1.js file2.js

# Run on multiple files
npx eslint lib/**

请注意,当传递全局模式作为参数时,它将由您的 shell 展开。展开的结果可能因您的 shell 及其配置而异。如果您想使用 node glob 语法,您必须引用您的参数(如果您需要它在 Windows 中运行,则使用双引号),如下所示

npx eslint "lib/**"

如果您正在使用 扁平化配置文件eslint.config.js),您也可以省略文件参数,ESLint 将使用 .。例如,这两行执行相同的操作

npx eslint .
npx eslint

如果您没有使用扁平化配置文件,则在没有文件参数的情况下运行 ESLint 会导致错误。

注意: 您还可以使用其他包管理器,例如 Yarnpnpm 来运行 ESLint。对于 pnpm,使用 pnpm dlx eslint,对于 Yarn,使用 yarn dlx eslint

将多个值传递给选项

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

接受多个值的选项示例

npx eslint --global describe --global it tests/
# OR
npx eslint --global describe,it tests/

选项

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

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

Basic configuration:
  --no-config-lookup              Disable look up for eslint.config.js
  -c, --config path::String       Use this configuration instead of eslint.config.js, eslint.config.mjs, or
                                  eslint.config.cjs
  --inspect-config                Open the config inspector with the current configuration
  --global [String]               Define global variables
  --parser String                 Specify the parser to be used
  --parser-options Object         Specify parser options

Specify Rules and Plugins:
  --plugin [String]               Specify plugins
  --rule Object                   Specify rules

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:
  --no-ignore                     Disable use of ignore files and patterns
  --ignore-pattern [String]       Patterns of files to ignore

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 and eslint-enable directives
  --report-unused-disable-directives-severity String  Chooses severity level for reporting unused eslint-disable and
                                                      eslint-enable directives - either: off, warn, error, 0, 1, or 2

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
  --no-warn-ignored               Suppress warnings when the file list includes ignored files
  --pass-on-no-patterns           Exit with exit code 0 in case no file patterns are passed
  --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
  --stats                         Add statistics to the lint report - default: false
  --flag [String]                 Enable a feature flag

基本配置

--no-eslintrc

仅限 eslintrc 模式。 禁用从 .eslintrc.*package.json 文件中使用配置。对于扁平化配置模式,请改用 --no-config-lookup

  • 参数类型:无参数。
--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 文件的选项。

--inspect-config

仅限扁平化配置模式。 此选项运行 npx @eslint/config-inspector@latest 以启动配置检查器。您可以使用配置检查器更好地了解您的配置在做什么以及它适用于哪些文件。当您使用此标志时,CLI 不会执行代码风格检查。

  • 参数类型:无参数。
--inspect-config 示例
npx eslint --inspect-config

--env

仅限 eslintrc 模式。 此选项启用特定环境。

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

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

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

--ext

仅限 eslintrc 模式。 如果您正在使用扁平化配置(eslint.config.js),请参阅 迁移指南

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

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

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

--ext 示例
# Use only .ts extension
npx eslint . --ext .ts

# Use both .js and .ts
npx eslint . --ext .js --ext .ts

# Also use both .js and .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 示例
# Use TypeScript ESLint parser
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

仅限 eslintrc 模式。 更改解析插件的目录。

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

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

例如

  • 当使用位于当前项目之外的配置文件(使用 --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 配置文件中的规则,并仅运行命令行中指定的规则,请将 --rule 标志与 --no-eslintrc 标志结合使用。

--rule 示例
# Apply single rule
npx eslint --rule 'quotes: [error, double]'
# Apply multiple rules
npx eslint --rule 'guard-for-in: error' --rule 'brace-style: [error, 1tbs]'
# Apply rule from jquery plugin
npx eslint --rule 'jquery/dollar-sign: error'
# Only apply rule from the command line
npx eslint --rule 'quotes: [error, double]' --no-eslintrc

--rulesdir

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

仅限 eslintrc 模式。 此选项允许您指定另一个目录,从中加载规则文件。这允许您在运行时动态加载新的规则。当您拥有不适合捆绑到 ESLint 的自定义规则时,这很有用。

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

请注意,与核心规则和插件规则一样,您仍然需要在配置中启用规则或通过--rule CLI 选项,才能在代码风格检查期间实际运行这些规则。指定带有--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

仅 eslintrc 模式。 此选项允许您指定用作.eslintignore 的文件。

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

注意:--ignore-path 仅在使用已弃用的配置时受支持。如果您想在eslint.config.js 文件中包含来自.gitignore 文件的模式,请参阅包含.gitignore 文件

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

此选项允许您指定要忽略的文件模式。在 eslintrc 模式下,这些模式会添加到.eslintignore 中。

  • 参数类型: 字符串。支持的语法与.eslintignore 文件相同,它们使用与.gitignore 规范相同的模式。您应该引用模式以避免 shell 对 glob 模式进行解释。
  • 多个参数:是
--ignore-pattern 示例
npx eslint --ignore-pattern "/lib/" --ignore-pattern "/src/vendor/*" .

使用 stdin

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

将代码风格检查结果的输出写入指定的文件。

  • 参数类型:字符串。文件路径。
  • 多个参数:否
-o, --output-file 示例
npx eslint -o ./test/test.html

-f, --format

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

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

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

指定后,给定的格式将输出到控制台。如果您想将该输出保存到文件中,您可以像这样在命令行上进行操作

# Saves the output into the `results.json` file.
npx eslint -f json file.js > results.json
-f, --format 示例

使用内置的json 格式化程序

npx eslint --format json file.js

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

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

使用 npm 安装的格式化程序

npm install eslint-formatter-pretty

# Then run one of the following commands
npx eslint -f pretty file.js
# or alternatively
npx eslint -f eslint-formatter-pretty file.js

--color--no-color

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

  • 参数类型:无参数。

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

--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-disableeslint-enable 注释,来防止将来的错误意外被抑制。

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

--report-unused-disable-directives-severity

--report-unused-disable-directives相同,但允许您指定报告的错误的严重级别(errorwarnoff)。这两个选项中只能使用一个。

  • 参数类型: 字符串。以下值之一
    1. off(或0
    2. warn(或1
    3. error(或2
  • 多个参数:否
  • 默认值: 默认情况下,使用linterOptions.reportUnusedDisableDirectives 配置设置(默认值为"warn")。
--report-unused-disable-directives-severity 示例
npx eslint --report-unused-disable-directives-severity warn file.js

缓存

--cache

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

  • 参数类型:无参数。

如果您使用--cache 运行 ESLint,然后在没有--cache 的情况下运行 ESLint,则.eslintcache 文件将被删除。这是必需的,因为代码风格检查的结果可能会发生变化,并使.eslintcache 无效。如果您想控制何时删除缓存文件,则使用--cache-location 指定缓存文件的备用位置。

自动修复的文件不会被放入缓存中。后续的代码风格检查不会触发自动修复,将会将其放入缓存中。

--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 不会执行代码风格检查。

  • 参数类型:无参数。

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

--init 示例
npx eslint --init

--env-info

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

  • 参数类型:无参数。

ESLint 团队可能会要求提供这些信息来帮助解决错误。使用此标志时,CLI 不会执行代码检查。

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

--no-warn-ignored

仅限扁平化配置模式。 此选项会抑制在显式传递被忽略的文件名时出现的 File ignored by defaultFile ignored because of a matching ignore pattern 警告。当与 --max-warnings 0 配合使用时,它很有用,因为它可以防止因上述警告而导致退出代码 1。

  • 参数类型:无参数。
--no-warn-ignored 示例
npx eslint --no-warn-ignored --max-warnings 0 ignored-file.js

--pass-on-no-patterns

此选项允许 ESLint 在没有传递文件或目录模式时退出并返回代码 0。如果没有此选项,ESLint 会假设您想使用 . 作为模式。(在传统 eslintrc 模式下运行时,ESLint 会退出并返回代码 1。)

  • 参数类型:无参数。
--pass-on-no-patterns 示例
npx eslint --pass-on-no-patterns

--debug

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

  • 参数类型:无参数。

当您遇到问题并且难以查明原因时,此信息非常有用。ESLint 团队可能会要求提供这些调试信息来帮助解决错误。

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

-h, --help

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

  • 参数类型:无参数。
-h, --help 示例
npx eslint --help

-v, --version

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

  • 参数类型:无参数。
-v, --version 示例
npx eslint --version

--print-config

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

  • 参数类型:字符串。文件路径。
  • 多个参数:否
--print-config 示例
npx eslint --print-config file.js

--stats

此选项将一系列详细的性能统计信息(参见 统计信息类型)添加到 result 对象中,这些对象被传递给格式化程序(参见 统计信息 CLI 使用方法)。

  • 参数类型:无参数。

此选项旨在与显示统计信息的自定义格式化程序一起使用。它也可以与内置的 json 格式化程序一起使用。

--stats 示例
npx eslint --stats --format json file.js

--flag

此选项为 ESLint 启用一个或多个功能标志。

  • 参数类型:字符串。一个功能标识符。
  • 多个参数:是
--flag 示例
npx eslint --flag x_feature file.js

退出代码

在检查文件时,ESLint 会使用以下退出代码之一退出

  • 0:代码检查成功,且没有代码检查错误。如果 --max-warnings 标志设置为 n,则代码检查警告的数量最多为 n
  • 1:代码检查成功,但至少存在一个代码检查错误,或者代码检查警告的数量超过了 --max-warnings 选项允许的数量。
  • 2:由于配置问题或内部错误,代码检查失败。
更改语言