CLI

使用 prettier 命令从命令行运行 Prettier。

¥Use the prettier command to run Prettier from the command line.

prettier [options] [file/dir/glob ...]

注意

要运行本地安装的 Prettier 版本，请在命令前加上 npx 或 yarn（如果你使用 Yarn）前缀，即 npx prettier --help 或 yarn prettier --help。

¥To run your locally installed version of Prettier, prefix the command with npx or yarn (if you use Yarn), i.e. npx prettier --help, or yarn prettier --help.

要就地格式化文件，请使用 --write。（注意：这会覆盖你的文件！）

¥To format a file in-place, use --write. (Note: This overwrites your files!)

在实践中，这可能类似于：

¥In practice, this may look something like:

prettier . --write

该命令格式化当前目录及其子目录中 Prettier 支持的所有文件。

¥This command formats all files supported by Prettier in the current directory and its subdirectories.

建议始终确保 prettier --write . 只格式化你在项目中想要的格式。使用 .prettierignore 文件忽略不应格式化的内容。

¥It’s recommended to always make sure that prettier --write . only formats what you want in your project. Use a .prettierignore file to ignore things that should not be formatted.

一个更复杂的例子：

¥A more complicated example:

prettier docs package.json "{app,__{tests,mocks}__}/**/*.js" --write --single-quote --trailing-comma all

警告

不要忘记 glob 周围的引号！引号确保 Prettier CLI 扩展 glob 而不是你的 shell，这对于跨平台使用很重要。

¥Don’t forget the quotes around the globs! The quotes make sure that Prettier CLI expands the globs rather than your shell, which is important for cross-platform usage.

注意

最好使用 配置文件 来格式化 --single-quote 和 --trailing-comma 等选项，而不是将它们作为 CLI 标志传递。这样 Prettier CLI、编辑器集成 和其他工具都可以知道你使用了哪些选项。

¥It’s better to use a configuration file for formatting options like --single-quote and --trailing-comma instead of passing them as CLI flags. This way the Prettier CLI, editor integrations, and other tooling can all know what options you use.

文件模式

¥File patterns

给定路径/模式列表，Prettier CLI 首先将其中的每个条目视为字面量路径。

¥Given a list of paths/patterns, the Prettier CLI first treats every entry in it as a literal path.

• 如果路径指向现有文件，Prettier CLI 会继续处理该文件并且不会将路径解析为 glob 模式。

  ¥If the path points to an existing file, Prettier CLI proceeds with that file and doesn’t resolve the path as a glob pattern.

• 如果路径指向现有目录，Prettier CLI 会递归地在该目录中查找支持的文件。此解析过程基于 Prettier 及其 插件 与支持的语言相关联的文件扩展名和众所周知的文件名。

  ¥If the path points to an existing directory, Prettier CLI recursively finds supported files in that directory. This resolution process is based on file extensions and well-known file names that Prettier and its plugins associate with supported languages.

• 否则，该条目将使用 来自 fast-glob 模块的通配符语法 解析为 glob 模式。

  ¥Otherwise, the entry is resolved as a glob pattern using the glob syntax from the fast-glob module.

Prettier CLI 将忽略位于 node_modules 目录中的文件。要退出此行为，请使用 --with-node-modules 标志。

¥Prettier CLI will ignore files located in node_modules directory. To opt out from this behavior, use --with-node-modules flag.

Prettier CLI 在扩展参数时不会遵循符号链接。

¥Prettier CLI will not follow symbolic links when expanding arguments.

要转义 glob 中的特殊字符，可以使用以下两种转义语法之一：prettier "\[my-dir]/*.js" 或 prettier "[[]my-dir]/*.js"。两者都匹配名为 [my-dir] 的目录中的所有 JS 文件，但是后一种语法更可取，因为前者在 Windows 上不起作用，反斜杠被视为路径分隔符。

¥To escape special characters in globs, one of the two escaping syntaxes can be used: prettier "\[my-dir]/*.js" or prettier "[[]my-dir]/*.js". Both match all JS files in a directory named [my-dir], however the latter syntax is preferable as the former doesn’t work on Windows, where backslashes are treated as path separators.

--check

当你想检查你的文件是否被格式化时，你可以使用 --check 标志（或 -c）运行 Prettier。这将输出一条人性化的消息和未格式化文件的列表（如果有）。

¥When you want to check if your files are formatted, you can run Prettier with the --check flag (or -c). This will output a human-friendly message and a list of unformatted files, if any.

prettier . --check

如果所有文件都被格式化，则控制台输出：

¥Console output if all files are formatted:

Checking formatting...
All matched files use Prettier code style!

如果某些文件需要重新格式化，则控制台输出：

¥Console output if some of the files require re-formatting:

Checking formatting...
[warn] src/fileA.js
[warn] src/fileB.js
[warn] Code style issues found in 2 files. Run Prettier with --write to fix.

在第二种情况下，该命令将返回退出代码 1，这在 CI 管道中很有用。人性化的状态消息帮助项目贡献者对可能出现的问题做出反应。为了尽量减少 prettier --check 找到未格式化文件的次数，你可能有兴趣在你的存储库中配置 预提交钩子。应用这种做法将最大限度地减少 CI 由于代码格式问题而失败的次数。

¥The command will return exit code 1 in the second case, which is helpful inside the CI pipelines. Human-friendly status messages help project contributors react on possible problems. To minimise the number of times prettier --check finds unformatted files, you may be interested in configuring a pre-commit hook in your repo. Applying this practice will minimise the number of times the CI fails because of code formatting problems.

如果你需要将未格式化文件列表通过管道传递给另一个命令，你可以使用 --list-different 标志而不是 --check。

¥If you need to pipe the list of unformatted files to another command, you can use --list-different flag instead of --check.

退出代码

¥Exit codes

代码	信息
0	一切格式正确
1	有些东西格式不正确
2	Prettier 出了点问题

--debug-check

如果你担心 Prettier 会更改代码的正确性，请将 --debug-check 添加到命令中。如果 Prettier 检测到代码正确性可能已更改，这将导致 Prettier 打印一条错误消息。请注意，--write 不能与 --debug-check 一起使用。

¥If you're worried that Prettier will change the correctness of your code, add --debug-check to the command. This will cause Prettier to print an error message if it detects that code correctness might have changed. Note that --write cannot be used with --debug-check.

--find-config-path 和 --config

¥--find-config-path and --config

如果你重复使用 prettier 格式化单个文件，当 Prettier 尝试查找 配置文件 时，你将产生少量性能成本。为了跳过这个，你可以要求 Prettier 找到配置文件一次，并在以后重新使用它。

¥If you are repeatedly formatting individual files with prettier, you will incur a small performance cost when Prettier attempts to look up a configuration file. In order to skip this, you may ask Prettier to find the config file once, and re-use it later on.

$ prettier --find-config-path path/to/file.js
path/to/.prettierrc

这将为你提供配置文件的路径，你可以将其传递给 --config：

¥This will provide you with a path to the configuration file, which you can pass to --config:

prettier path/to/file.js --write --config path/to/.prettierrc

如果你的配置文件位于 Prettier 找不到的地方，例如 config/ 目录，你也可以使用 --config。

¥You can also use --config if your configuration file lives somewhere where Prettier cannot find it, such as a config/ directory.

如果你没有配置文件，或者如果它存在就想忽略它，你可以传递 --no-config 代替。

¥If you don’t have a configuration file, or want to ignore it if it does exist, you can pass --no-config instead.

--ignore-path

包含描述要忽略的文件的模式的文件的路径。默认情况下，Prettier 会查找 ./.gitignore 和 ./.prettierignore。接受多个值。

¥Path to a file containing patterns that describe files to ignore. By default, Prettier looks for ./.gitignore and ./.prettierignore.\ Multiple values are accepted.

--list-different

另一个有用的标志是 --list-different（或 -l），它打印不同于 Prettier 格式的文件的文件名。如果存在差异，脚本就会出错，这在 CI 场景中很有用。

¥Another useful flag is --list-different (or -l) which prints the filenames of files that are different from Prettier formatting. If there are differences the script errors out, which is useful in a CI scenario.

prettier . --single-quote --list-different

你还可以使用 --check 标志，它的工作方式与 --list-different 相同，但也会将人性化的摘要消息打印到标准输出。

¥You can also use --check flag, which works the same way as --list-different, but also prints a human-friendly summary message to stdout.

--no-config

不要寻找配置文件。将使用默认设置。

¥Do not look for a configuration file. The default settings will be used.

--config-precedence

定义应如何结合 CLI 选项评估配置文件。

¥Defines how config file should be evaluated in combination of CLI options.

cli 覆盖（默认）

¥cli-override (default)

CLI 选项优先于配置文件

¥CLI options take precedence over config file

file-override

配置文件优先于 CLI 选项

¥Config file take precedence over CLI options

prefer-file

如果找到配置文件，将评估它并忽略其他 CLI 选项。如果未找到配置文件，CLI 选项将正常评估。

¥If a config file is found will evaluate it and ignore other CLI options. If no config file is found, CLI options will evaluate as normal.

此选项增加了对编辑器集成的支持，用户可以在其中定义默认配置但希望尊重项目特定配置。

¥This option adds support to editor integrations where users define their default configuration but want to respect project specific configuration.

--no-editorconfig

解析配置时不要考虑 .editorconfig。有关详细信息，请参见 prettier.resolveConfig docs。

¥Don’t take .editorconfig into account when parsing configuration. See the prettier.resolveConfig docs for details.

--with-node-modules

Prettier CLI 将忽略位于 node_modules 目录中的文件。要退出此行为，请使用 --with-node-modules 标志。

¥Prettier CLI will ignore files located in node_modules directory. To opt out from this behavior, use --with-node-modules flag.

--write

这将重写所有已处理的文件。这与 eslint --fix 工作流程相当。你也可以使用 -w 别名。

¥This rewrites all processed files in place. This is comparable to the eslint --fix workflow. You can also use -w alias.

--log-level

更改 CLI 的日志记录级别。有效选项是：

¥Change the level of logging for the CLI. Valid options are:

• error

• warn

• log（默认）

  ¥log (default)

• debug

• silent

--stdin-filepath

Prettier CLI 将像标准输入一样对待的文件路径。例如：

¥A path to the file that the Prettier CLI will treat like stdin. For example:

abc.css

.name {
  display: none;
}

壳

¥shell

$ cat abc.css | prettier --stdin-filepath abc.css
.name {
  display: none;
}

--ignore-unknown

使用 --ignore-unknown（或 -u），prettier 将忽略与模式匹配的未知文件。

¥With --ignore-unknown (or -u), prettier will ignore unknown files matched by patterns.

prettier "**/*" --write --ignore-unknown

--no-error-on-unmatched-pattern

当模式不匹配时防止错误。

¥Prevent errors when pattern is unmatched.

--cache

如果启用此选项，则以下值将用作缓存键，并且仅当其中一个值发生更改时才会格式化文件。

¥If this option is enabled, the following values are used as cache keys and the file is formatted only if one of them is changed.

• Prettier 版本

  ¥Prettier version

• 选项

  ¥Options

• Node.js 版本

  ¥Node.js version

• （如果 --cache-strategy 是 metadata）文件元数据，例如时间戳

  ¥(if --cache-strategy is metadata) file metadata, such as timestamps

• （如果 --cache-strategy 是 content）文件的内容

  ¥(if --cache-strategy is content) content of the file

prettier . --write --cache

在没有 --cache 的情况下运行 Prettier 将删除缓存。

¥Running Prettier without --cache will delete the cache.

另外，由于缓存文件存储在 ./node_modules/.cache/prettier/.prettier-cache 中，所以你可以使用 rm ./node_modules/.cache/prettier/.prettier-cache 手动删除它。

¥Also, since the cache file is stored in ./node_modules/.cache/prettier/.prettier-cache, so you can use rm ./node_modules/.cache/prettier/.prettier-cache to remove it manually.

警告

插件版本和实现不用作缓存键。我们建议你在更新插件时删除缓存。

¥Plugins version and implementation are not used as cache keys. We recommend that you delete the cache when updating plugins.

--cache-location

--cache 标志使用的缓存文件位置的路径。如果你不显式指定 --cache-location，Prettier 会将缓存文件保存在 ./node_modules/.cache/prettier/.prettier-cache。

¥Path to the cache file location used by --cache flag. If you don't explicit --cache-location, Prettier saves cache file at ./node_modules/.cache/prettier/.prettier-cache.

如果传递文件路径，则该文件将用作缓存文件。

¥If a file path is passed, that file is used as the cache file.

prettier . --write --cache --cache-location=path/to/cache-file

--cache-strategy

用于检测已更改文件的缓存策略。可以是 metadata 或 content。

¥Strategy for the cache to use for detecting changed files. Can be either metadata or content.

一般来说，metadata 更快。但是，content 对于在不更改文件内容的情况下更新时间戳很有用。例如，在 git clone 等 git 操作期间可能会发生这种情况，因为它不跟踪文件修改时间。

¥In general, metadata is faster. However, content is useful for updating the timestamp without changing the file content. This can happen, for example, during git operations such as git clone, because it does not track file modification times.

如果未指定策略，将使用 content。

¥If no strategy is specified, content will be used.

prettier . --write --cache --cache-strategy metadata