命令行界面参考
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 会导致错误。
注意: 您还可以使用其他包管理器,例如 Yarn 或 pnpm 来运行 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 尝试尽可能多地修复问题。这些修复是针对实际文件本身进行的,只有剩下的未修复问题才会被输出。
- 参数类型:无参数。
并非所有问题都可以使用此选项修复,并且此选项在以下情况下不起作用
- 当代码被管道传输到 ESLint 时,此选项会抛出错误。
- 此选项对使用处理器的代码没有影响,除非处理器选择允许自动修复。
如果您想修复来自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
时指定要应用的修复类型。
- 参数类型: 字符串。以下修复类型之一
problem
- 修复代码中的潜在错误suggestion
- 对代码应用修复以改进代码layout
- 应用不改变程序结构(AST)的修复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,例如当通过cat
或less
将eslint
管道传输时。
--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
和eslint-enable
注释,来防止将来的错误意外被抑制。
--report-unused-disable-directives
示例
npx eslint --report-unused-disable-directives file.js
--report-unused-disable-directives-severity
与--report-unused-disable-directives
相同,但允许您指定报告的错误的严重级别(error
、warn
、off
)。这两个选项中只能使用一个。
- 参数类型: 字符串。以下值之一
off
(或0
)warn
(或1
)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
用于检测更改文件的缓存策略。
- 参数类型: 字符串。以下值之一
metadata
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 default
和 File 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
:由于配置问题或内部错误,代码检查失败。