Prettier 命令行工具有哪些常用命令和选项?

Prettier 命令行工具有哪些常用命令和选项?

Prettier 的命令行工具是日常开发中格式化代码的核心手段，掌握常用命令和关键选项不仅能提升开发效率，也是前端工程化面试中的高频考点。

核心命令

格式化文件：--write

--write 是最常用的选项，直接修改文件为格式化后的内容：

bash
# 格式化单个文件
npx prettier --write src/index.ts

# 格式化整个项目
npx prettier --write .

面试追问：--write 会先写入临时文件再原子替换原文件，避免写入中断导致文件损坏。

检查格式：--check

--check 只检查文件是否符合 Prettier 格式，不修改文件。文件不合规时退出码为 1，因此广泛用于 CI 流水线：

bash
npx prettier --check "src/**/*.{js,ts}"

# 在 CI 中使用
npx prettier --check . || echo "存在未格式化的文件"

列出差异文件：--list-different

--list-different（简写 -l）只输出格式不一致的文件路径，不输出格式化内容，适合脚本处理：

bash
npx prettier --list-different "src/**/*.js"

与 --check 的区别：--check 会输出详细的人类可读信息，--list-different 只输出文件路径，更便于后续管道处理。

查看差异：--diff

--diff 输出格式化前后的 diff 对比，方便在不修改文件的前提下预览变更：

bash
npx prettier --diff src/app.ts

配置与忽略

指定配置文件：--config

默认 Prettier 会沿目录向上查找 .prettierrc 等配置文件，使用 --config 可指定自定义配置：

bash
npx prettier --config .prettierrc.staging.json --write src/

查找配置路径：--find-config-path

输出给定文件实际使用的配置文件路径，用于排查配置生效问题：

bash
npx prettier --find-config-path src/index.ts
# 输出: /project/.prettierrc

忽略文件：--ignore-path

默认使用 .prettierignore，可通过 --ignore-path 指定自定义忽略文件：

bash
npx prettier --ignore-path .gitignore --write .

将 .gitignore 复用为忽略规则是一个实用技巧。

忽略未知文件类型：--ignore-unknown

格式化整个项目时，遇到 Prettier 不支持的文件类型默认会报错，加上此选项会自动跳过：

bash
npx prettier --write --ignore-unknown .

缓存与性能

启用缓存：--cache

大型项目格式化耗时较长，--cache 通过缓存未变更文件的格式化结果显著提升速度：

bash
npx prettier --write --cache "src/**/*.ts"

缓存位置：--cache-location

指定缓存文件的存储路径：

bash
npx prettier --write --cache --cache-location .prettiercache src/

缓存策略：--cache-strategy

支持两种策略：

• metadata（默认）：根据文件修改时间判断，速度快但不够精确
• content：根据文件内容哈希判断，更精确但稍慢

bash
npx prettier --write --cache --cache-strategy content src/

输出控制

输出到标准输出

不加 --write 时，Prettier 将格式化结果输出到 stdout，不修改原文件：

bash
npx prettier src/index.ts

指定输出目录：--out-dir

将格式化结果写入指定目录而非原文件，适合生成格式化副本：

bash
npx prettier "src/**/*.js" --out-dir formatted/

标准输入：--stdin-filepath

从标准输入读取代码时，Prettier 无法判断文件类型，通过此选项指定虚拟路径：

bash
echo "const x=1" | npx prettier --stdin-filepath index.ts

这在编辑器集成和管道场景中非常关键。

与工程化工具集成

在 package.json 中配置脚本

json
{
  "scripts": {
    "format": "prettier --write "src/**/*.{js,ts,json,css,md}"",
    "format:check": "prettier --check "src/**/*.{js,ts,json,css,md}"",
    "format:all": "prettier --write --ignore-unknown ."
  }
}

配合 lint-staged 只格式化暂存文件

json
{
  "lint-staged": {
    "*.{js,ts,css,md}": "prettier --write"
  }
}

这样配合 husky 的 pre-commit 钩子，每次提交只格式化本次变更的文件，避免全量格式化带来的提交噪音。

在 CI 中强制格式检查

yaml
- name: Check formatting
  run: npx prettier --check .

--check 在文件不合规时返回退出码 1，CI 流水线会因此失败，确保仓库中不会混入未格式化的代码。

调试命令

调试检查：--debug-check

格式化文件并检查格式化是否改变了 AST，用于排查 Prettier 自身的 bug。不能与 --write 同时使用：

bash
npx prettier --debug-check src/index.ts

查看帮助与版本

bash
npx prettier --help
npx prettier --version

Prettier 命令行工具在日常开发中主要用于格式化和检查，在工程化体系中则通过 --check 与 CI 集成、通过 --list-different 与 lint-staged 配合，理解每个命令的应用场景比记住参数更重要。