命令行接口参考手册
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/**"
**注意:**您还可以使用其他包管理器(例如 Yarn 或 pnpm)来运行 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 尝试修复尽可能多的问题。 对实际文件本身进行了修复,仅输出剩余的未修复问题。
- 参数类型: 没有参数。
并非所有问题都可以使用此选项解决,并且该选项在以下情况下不起作用:
- 当代码通过管道传输到 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
此选项允许您指定要用作 .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
此选项指定控制台的输出格式。
如果您使用的是在本地文件中定义的自定义格式化程序,则可以指定自定义格式化程序文件的路径。
使用或不使用 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,例如当管道 eslint
到 cat
或 less
时。
--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
用于检测更改文件的缓存策略。
- 参数类型: 字符串。 以下值之一:
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 不会执行 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
: 由于配置问题或内部错误,检查不成功。