3.4命令行接口实战

3.4 命令行接口实战

基本用法

Prettier 的命令行接口（CLI）是你跟 Prettier 交互的最直接方式。虽然大多数日常使用会通过编辑器集成或 git hooks 来触发格式化，但理解 CLI 仍然很重要——它是调试问题、批量处理、CI 集成的基础。

最基本的用法：指定文件路径和操作模式。

# 格式化指定文件（直接修改文件）
npx prettier --write src/index.js

# 格式化整个目录
npx prettier --write src/

# 检查文件是否已格式化（不修改）
npx prettier --check src/
​

--write 和 --check 是最常用的两个模式。前者直接修改文件，后者只输出检查结果。在日常开发中用 --write，在 CI 中用 --check。

文件匹配

Prettier 接受多种文件路径格式：

# 单个文件
npx prettier --write src/index.js

# 目录（处理目录下所有支持的文件）
npx prettier --write src/

# glob 模式
npx prettier --write "src/**/*.js"
npx prettier --write "src/**/*.{js,ts,jsx,tsx,css,json}"

# 多个路径
npx prettier --write "src/**/*.js" "test/**/*.js"
​

注意 glob 模式需要用引号包裹，否则 shell 会提前展开通配符。

--write 在没有指定文件路径时不会处理任何文件——它需要至少一个文件参数或 glob。如果想格式化当前目录下所有文件，用 . 代替：

npx prettier --write .
​

标准输入和输出

Prettier 可以从标准输入读取代码，把格式化结果输出到标准输出。这在管道操作和脚本中很常用。

# 从 stdin 读取，输出到 stdout
echo 'const x=1' | npx prettier --stdin-filepath foo.js
# 输出: const x = 1;

# 在脚本中使用
cat messy.js | npx prettier --stdin-filepath messy.js > clean.js
​

--stdin-filepath 参数告诉 Prettier "这段代码应该当作什么文件类型处理"。Prettier 根据文件扩展名决定使用哪个解析器——.js 用 Babel，.ts 用 TypeScript 解析器，.css 用 PostCSS。

如果不传 --stdin-filepath，Prettier 默认当 JavaScript 处理。如果你要格式化非 JS 的内容，必须显式指定。

# 格式化 JSON（从 stdin）
echo '{"a":1,"b":2}' | npx prettier --stdin-filepath data.json
# 输出:
# {
#   "a": 1,
#   "b": 2
# }
​

常用 CLI 选项

以下是 CLI 中最常用的选项：

--check 和 --list-different 的区别：前者返回退出码（0 表示全部通过，1 表示存在未格式化的文件），后者输出文件路径列表。两者功能重叠，--check 在 CI 中更常用（直接用退出码判断），--list-different 在需要知道具体哪些文件有问题时更方便。

--check 在 CI 中的使用

CI 流水线中用 Prettier 检查格式一致性的典型方式：

# GitHub Actions 示例
- name: Check formatting
  run: npx prettier --check .
​

# GitLab CI 示例
check_format:
  script:
    - npx prettier --check .
​

如果存在未格式化的文件，prettier --check 会返回退出码 1，CI 任务失败。开发者看到失败信息后，在本机运行 npx prettier --write . 修复，重新提交。

一个更友好的做法是在 CI 中加 --list-different 或 --write 标记来帮助开发者定位问题：

# CI 中同时输出文件列表和退出码
npx prettier --check . || echo "Run: npx prettier --write .  to fix"
​

图 3-4：CI 中的 Prettier 检查循环

--no-config：绕过配置文件

--no-config 让 Prettier 忽略所有配置文件，完全使用默认值。这在调试时有用——当你不确定是配置导致的问题还是 Prettier 自身的行为时，加 --no-config 可以排除配置的干扰。

# 确认默认值下的输出
npx prettier --no-config --write test.js

# 确认特定配置下的输出
npx prettier --config .prettierrc.test --write test.js
​

--ignore-path：自定义忽略文件

默认情况下，Prettier 读取 .prettierignore 作为忽略规则。如果你想把忽略规则放在其他文件里，用 --ignore-path 指定：

npx prettier --ignore-path .gitignore --check .
​

一个常见的用法是直接用 .gitignore 作为 Prettier 的忽略规则（虽然 Prettier 默认也会参考 .gitignore，但 --ignore-path .gitignore 会确保完全一致）。

显式指定解析器

默认情况下 Prettier 按文件扩展名选择解析器，但有些场景需要手动指定：

# 扩展名不在支持列表，但内容其实是 JavaScript
npx prettier --write --parser babel legacy.js

# 同一个内容用不同解析器，结果可能不同
echo "const a=<div/>" | npx prettier --parser babel
echo "const a=<div/>" | npx prettier --parser flow
​

--parser 的可选值包括 babel、typescript、flow、acorn、espree、meriyah、postcss、json、json5、json-stringify、graphql、markdown、html、vue、yaml、mdx 等，插件还可以注册自定义解析器。

在 stdin 模式下，--parser 和 --stdin-filepath 二选一即可：给了 --stdin-filepath，Prettier 按扩展名推断解析器；没给或推断不准，再用 --parser 显式指定。

退出码与脚本集成

Prettier 的退出码是脚本友好设计的核心：

在 shell 脚本里可以直接用退出码做分支：

if npx prettier --check src/ > /dev/null 2>&1; then
  echo "格式正确"
else
  echo "需要格式化"
  npx prettier --write src/
fi
​

注意 --check 把未格式化文件的信息打印到 stderr，所以上面用 2>&1 重定向。CI 里判断失败用退出码 1 就够了，不需要解析输出文本。

npx 版本陷阱

npx prettier 的行为取决于项目里是否安装了本地版本：如果 node_modules 里有 prettier，npx 优先用本地版本；否则 npx 会临时下载最新版。CI 或脚本里依赖 npx 下载最新版是不稳定的——今天通过的检查，明天可能因为 Prettier 升级而失败。

更稳妥的做法是在 package.json 的 scripts 中固定调用：

{
  "scripts": {
    "fmt": "prettier --write .",
    "fmt:check": "prettier --check ."
  }
}
​

这样 npm run fmt 使用的永远是本地锁定的版本。想确认当前版本：npx prettier --version。

性能相关选项

处理大项目时，Prettier 的启动时间会成为瓶颈——每次调用都要加载 Node.js 运行时和所有解析器。如果你需要频繁格式化单个文件（比如在编辑器中保存时触发），这个延迟比较明显。

--no-error-on-unmatched-pattern 可以避免找不到匹配文件时报错，在 CI 脚本中比较有用。

对于大项目的批量格式化，建议用 --write 而不是多次单独调用。一次 prettier --write src/ 比一百次 prettier --write src/file.js 快得多，因为 Prettier 会批量加载解析器和配置，只初始化一次。

实用 CLI 技巧

# 只格式化 git 暂存区中修改的文件（配合 git 命令）
git diff --name-only --cached | xargs npx prettier --write

# 格式化特定类型的文件
find . -name "*.css" | xargs npx prettier --write

# 查看格式化前后的差异（不实际修改文件）
npx prettier --check . 2>&1 | head -20

# 把格式化结果输出到新文件（不影响原文件）
npx prettier src/index.js > /tmp/formatted.js
​

掌握 CLI 的核心价值在于：当你需要在编辑器集成之外的场景中使用 Prettier 时（CI 脚本、Makefile、自定义 git hooks），你知道该怎么调用。大多数日常操作确实通过编辑器或 git hooks 完成，但 CLI 是这些集成的底层实现方式。