CLI

使用 prettier 命令在命令行中运行 Prettier。

prettier [options] [file/dir/glob ...]  # 基础命令格式：options为选项，file/dir/glob为文件/目录/通配符路径

要原地格式化文件，请使用 --write 选项（注意：这会覆盖原始文件！）。

实际示例如下：

prettier . --write  # 格式化当前目录及所有子目录中的文件

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

建议始终确保 prettier --write . 仅格式化项目中的目标文件。使用 ignore.md 文件排除无需格式化的内容。

更复杂的示例：

prettier docs package.json "{app,__{tests,mocks}__}/**/*.js" --write --single-quote --trailing-comma all
# 格式化docs目录、package.json文件以及app/__tests__/__mocks__目录中的所有JS文件
# 使用单引号并强制所有逗号结尾

文件匹配模式

当提供路径/模式列表时，Prettier CLI 首先将每个条目视为字面路径处理：

• 若路径指向已存在的文件，则直接处理该文件（不解析为通配模式）
• 若路径指向已存在的目录，则递归查找该目录中支持的文件（根据文件扩展名和 Prettier 及其plugins.md识别的特定文件名）
• 否则使用 https://github.com/mrmlnc/fast-glob#pattern-syntax解析为通配模式

默认忽略 node_modules 目录中的文件，可通过 --with-node-modules 标志禁用此行为。

展开参数时不追踪符号链接。转义 glob 特殊字符的两种语法：
prettier "\[my-dir]/*.js" 或 prettier "[[]my-dir]/*.js"（匹配 [my-dir] 目录中的 JS 文件）。后者更优，因前者在 Windows 中会被反斜杠解析干扰。

--check 检查模式

检查文件是否已格式化时使用 --check（或 -c）标志。该模式会输出易读提示和未格式化文件列表（如有）。

prettier . --check  # 检查当前目录文件格式化状态

所有文件已格式化时的输出：

Checking formatting...
All matched files use Prettier code style!  # 所有文件符合代码规范

存在未格式化文件时的输出：

Checking formatting...
[warn] src/fileA.js
[warn] src/fileB.js
[warn] Code style issues found in 2 files. Run Prettier with --write to fix.
# 发现2个文件存在代码样式问题，使用--write运行修复

第二种情况会返回退出码 1（适用于 CI 管道）。人类可读的状态提示帮助贡献者快速定位问题。建议在仓库中配置precommit.md以最小化 --check 发现的未格式化文件。

若需将未格式化文件列表传输给其他命令，可用 cli.md#--list-different 替代 --check。

退出码说明

--debug-check 调试检查

担忧格式化可能破坏代码正确性时，添加 --debug-check 标志。当检测到代码正确性可能被修改时，Prettier 将输出错误信息（不可与 --write 同时使用）。

--find-config-path 与 --config

重复格式化单个文件时，查找configuration.md会产生性能损耗。可先定位配置文件再复用：

$ prettier --find-config-path path/to/file.js  # 查找配置文件路径
path/to/.prettierrc  # 返回的配置文件路径

通过 --config 指定配置路径：

prettier path/to/file.js --write --config path/to/.prettierrc  # 复用指定配置文件

若配置文件位于非常规位置（如 config/ 目录），也可用此标志指定。无配置文件时用 --no-config 忽略配置。

--ignore-path 忽略文件路径

指定包含忽略模式的文件路径。默认查找 ./.gitignore 和 ./.prettierignore。支持多值。

--list-different 列出差异文件

--list-different（或 -l）标志打印未格式化文件名（存在差异时脚本报错）。等价于 --check 但仅输出文件列表无总结信息。

prettier . --single-quote --list-different  # 列出所有未使用单引号的文件

--no-config 无配置模式

忽略配置文件，使用默认设置。

--config-precedence 配置优先级

定义 CLI 选项与配置文件的优先级关系：

• cli-override（默认）：CLI 选项优先级高于配置文件
• file-override：配置文件优先级高于 CLI 选项
• prefer-file：找到配置文件则忽略 CLI 选项；否则正常使用 CLI 选项

此选项适用于编辑器集成场景：用户使用个人默认配置时仍能兼容项目特定配置。

--no-editorconfig 忽略 EditorConfig

解析配置时不考虑 .editorconfig 文件。详见 api.md。

--with-node-modules 包含 node_modules

默认忽略 node_modules 目录文件，此标志显式包含它们。

--write 写入模式

原地重写所有已处理文件（类似 eslint --fix 工作流）。支持别名 -w。

--log-level 日志级别

修改 CLI 日志级别，可选值：

• error
• warn
• log（默认）
• debug
• silent

--stdin-filepath 标准输入文件路径

为 stdin 输入指定模拟文件路径： abc.css

.name {
  display: none;
}

shell 操作

$ cat abc.css | prettier --stdin-filepath abc.css  # 通过stdin输入并模拟文件路径
.name {
  display: none;
}

--ignore-unknown 忽略未知文件

--ignore-unknown（或 -u）使 Prettier 忽略模式匹配到的未知类型文件。

prettier "**/*" --write --ignore-unknown  # 格式化所有文件但跳过未知类型

--no-error-on-unmatched-pattern 无匹配不报错

未匹配到文件时禁止报错。

--cache 缓存模式

启用后，以下内容将作为缓存键（任一变更时重新格式化文件）：

• Prettier 版本
• 选项配置
• Node.js 版本
• 文件元数据（--cache-strategy metadata 模式）
• 文件内容（--cache-strategy content 模式）

prettier . --write --cache  # 启用缓存格式化

无 --cache 运行时自动清除缓存。缓存文件默认位于 ./node_modules/.cache/prettier/.prettier-cache，可手动执行 rm ./node_modules/.cache/prettier/.prettier-cache 清除。

--cache-location 缓存位置

指定 --cache 的存储路径。默认为 ./node_modules/.cache/prettier/.prettier-cache。

prettier . --write --cache --cache-location=path/to/cache-file  # 自定义缓存文件路径

--cache-strategy 缓存策略

检测文件变更的策略（metadata 或 content）。
通常 metadata（元数据比对）更快；但 content（内容哈希）适用于时间戳变更但内容未变的场景（如 git clone 操作）。默认策略 content。

prettier . --write --cache --cache-strategy metadata  # 使用元数据策略

总结

本文全面介绍了 Prettier CLI 的核心功能与使用细节，主要包含：

1. 基础使用：通过 prettier 命令支持文件/目录/通配符路径处理，原地格式化需配合 --write 标志
2. 配置管理：优先推荐配置文件，提供 --find-config-path 和 --config 实现灵活配置
3. 检查模式：--check 和 --list-different 用于验证格式化状态（CI 集成友好）
4. 文件匹配：智能处理字面路径、目录扫描与 glob 模式，默认忽略 node_modules
5. 高级特性：
   • 缓存机制（--cache）显著提升重复执行性能
   • 跨平台通配符处理需注意引号转义
   • 支持标准输入流与文件模拟（--stdin-filepath）
6. 调试保障：--debug-check 确保代码正确性，多种日志级别辅助排查问题

建议实践中结合 .prettierignore 精确控制范围，通过预提交钩子自动化流程，避免手动频繁执行。