Prettier

← 返回目录 > ← 返回总览

工具	说明
ESLint	JS/TS 代码质量检查，与 Prettier 互补协作
TypeScript-ESLint	TypeScript 专用 ESLint 规则集
Markdownlint	Markdown 格式与风格检查
Shfmt	Shell 脚本格式化

1. 简介

Prettier 是一个"固执己见"（Opinionated）的代码格式化工具。它通过解析源代码为抽象语法树（AST），再由内置的 Doc 布局引擎重新生成格式统一的代码字符串。与传统的正则替换方式不同，Prettier 基于编译器前端技术工作，保证格式化过程不会引入语法错误，也不会破坏模板字符串、JSX 属性、TypeScript 泛型等复杂结构。

主要检查语言：JavaScript、TypeScript、CSS、HTML、JSON、Markdown、YAML 等 20+ 种
主要检查能力：格式化 20+ 种文件类型的代码；涵盖代码格式化
核心检查原理：基于 AST 的格式化引擎，内置 Doc 布局引擎进行排版
检查规则/选项：约 20 项格式化配置选项（如 printWidth、tabWidth、semi、singleQuote、trailingComma 等），遵循"少即是多"的选项哲学，全量选项列表
GitHub 仓库：https://github.com/prettier/prettier（51,990 stars）
开源协议：MIT
最新稳定版本：3.8.4
运行环境要求：Node.js 16+（v3.x 起）；v2.x 支持 Node.js 14+
误报率：无

2. 官方文档

核心文档

文档	链接
官网首页	https://prettier.io
什么是 Prettier	https://prettier.io/docs/
安装指南	https://prettier.io/docs/install
CLI 命令行文档	https://prettier.io/docs/cli
配置文件	https://prettier.io/docs/configuration
所有格式化选项	https://prettier.io/docs/options
忽略代码	https://prettier.io/docs/ignore
Pre-commit Hook	https://prettier.io/docs/precommit
CI 集成	https://prettier.io/docs/ci
编辑器集成	https://prettier.io/docs/editors
与 Linter 集成	https://prettier.io/docs/integrating-with-linters
插件	https://prettier.io/docs/plugins
API 文档	https://prettier.io/docs/api
选项设计哲学	https://prettier.io/docs/option-philosophy
WebStorm 设置	https://prettier.io/docs/webstorm
共享配置	https://prettier.io/docs/sharing-configurations
相关项目	https://prettier.io/docs/related-projects
Prettier vs. Linters	https://prettier.io/docs/comparison

配置选项速查

Prettier 提供的格式化选项详见 Options：

选项	默认值	CLI 参数	说明
`printWidth`	`80`	`--print-width <int>`	行宽限制
`tabWidth`	`2`	`--tab-width <int>`	缩进空格数
`useTabs`	`false`	`--use-tabs`	使用 Tab 缩进
`semi`	`true`	`--no-semi`	语句末尾加分号
`singleQuote`	`false`	`--single-quote`	使用单引号
`quoteProps`	`"as-needed"`	`--quote-props <as-needed\|consistent\|preserve>`	对象属性引号策略
`jsxSingleQuote`	`false`	`--jsx-single-quote`	JSX 中使用单引号
`trailingComma`	`"all"`	`--trailing-comma <all\|es5\|none>`	尾逗号策略
`bracketSpacing`	`true`	`--no-bracket-spacing`	对象括号内空格
`bracketSameLine`	`false`	`--bracket-same-line`	HTML/JSX `>` 是否单独一行
`arrowParens`	`"always"`	`--arrow-parens <always\|avoid>`	箭头函数参数括号
`objectWrap`	`"preserve"`	`--object-wrap <preserve\|collapse>`	对象换行策略（v3.5+）
`endOfLine`	`"lf"`	`--end-of-line <lf\|crlf\|cr\|auto>`	换行符
`htmlWhitespaceSensitivity`	`"css"`	`--html-whitespace-sensitivity <css\|strict\|ignore>`	HTML 空白敏感度
`vueIndentScriptAndStyle`	`false`	`--vue-indent-script-and-style`	Vue 文件 script/style 缩进
`proseWrap`	`"preserve"`	`--prose-wrap <always\|never\|preserve>`	Markdown 散文换行
`embeddedLanguageFormatting`	`"auto"`	`--embedded-language-formatting <auto\|off>`	嵌入语言格式化
`singleAttributePerLine`	`false`	`--single-attribute-per-line`	HTML/Vue/JSX 单属性一行

3. 社区优秀实践

3.1 React（Meta）

仓库：https://github.com/facebook/react
实践特点：React 是最早全面采用 Prettier 的大型开源项目之一。其 package.json 中包含 "prettier": "^3.3.3" 依赖，通过自定义脚本 yarn prettier 仅检查自上次从远程分支 fork 以来变更的文件。CI 中使用 --check 模式确保所有 PR 必须通过格式化检查才能合并。同时使用 eslint-config-prettier 确保 ESLint 与 Prettier 不冲突。

3.2 Next.js（Vercel）

仓库：https://github.com/vercel/next.js
实践特点：Next.js 官方仓库使用 Prettier 3.6.2 作为代码格式化工具，配合 ESLint 进行代码质量检查。项目中配置了 husky 和 lint-staged，在 Git 提交前自动格式化暂存文件。package.json 中包含 "prettier-check": "prettier --check ." 和 "prettier-fix": "prettier --write ." 脚本，CI 中通过 lint 命令统一调用格式化检查。

3.3 Vue.js（vuejs/core）

仓库：https://github.com/vuejs/core
实践特点：Vue.js 核心仓库使用 Prettier 格式化代码，配置文件为 .prettierrc，内容为 {"semi": false, "singleQuote": true, "arrowParens": "avoid"}。作为 Vue 生态的核心项目，其 Prettier 配置对 Vue 单文件组件（SFC）的 <template>、<script>、<style> 三大块均有良好的格式化支持。

3.4 Prettier 自身

仓库：https://github.com/prettier/prettier
实践特点：Prettier 自身仓库使用 Prettier 进行代码格式化，是最直接的实践参考。仓库包含 .prettierrc 配置文件和 .prettierignore 忽略文件，CI 中通过 GitHub Actions 运行格式化检查。

4. 工具配置说明

Prettier 作为格式化工具，其设计哲学是"少即是多"——提供少量但精心设计的选项，让开发者无需纠结于无穷无尽的格式规则。详见 Option Philosophy。

4.1 配置文件说明

Prettier 按以下优先级查找配置文件（从被格式化文件的位置开始向上搜索）。详见 Configuration File。

配置文件	格式	用途
`package.json` 中的 `"prettier"` 键	JSON	内嵌配置，无需额外文件
`.prettierrc`	JSON 或 YAML	通用配置文件
`.prettierrc.json` / `.prettierrc.yml` / `.prettierrc.yaml` / `.prettierrc.json5`	对应格式	显式指定格式的配置文件
`.prettierrc.js` / `prettier.config.js` / `.prettierrc.mjs` / `prettier.config.mjs`	JavaScript (ESM)	动态生成配置
`.prettierrc.cjs` / `prettier.config.cjs` / `.prettierrc.cts` / `prettier.config.cts`	JavaScript (CommonJS)	动态生成配置
`.prettierrc.ts` / `prettier.config.ts` / `.prettierrc.mts` / `prettier.config.mts`	TypeScript	动态生成配置，需 Node.js >= 22.6.0 并启用 `--experimental-strip-types`
`.prettierrc.toml`	TOML	TOML 格式配置
`.editorconfig`	INI	Prettier 自动读取并转换，优先级低于上述显式配置

4.2 配置文件详解

Prettier 配置文件控制格式化选项，并支持按文件类型覆盖。官方推荐的最小配置是空对象 {}，让编辑器和其他工具知道项目使用了 Prettier，所有选项使用默认值。

如果项目中存在 .editorconfig 文件，Prettier 会自动读取并转换为对应配置。Prettier 配置文件（.prettierrc 等）优先级高于 .editorconfig。详见 Configuration File - EditorConfig。

配置项说明：

配置项	类型	说明
`printWidth`	int	单行最大宽度，默认 `80`
`tabWidth`	int	缩进空格数，默认 `2`
`useTabs`	bool	是否使用 Tab 缩进，默认 `false`
`semi`	bool	语句末尾是否加分号，默认 `true`
`singleQuote`	bool	是否使用单引号，默认 `false`
`quoteProps`	string	对象属性引号策略：`as-needed`/`consistent`/`preserve`，默认 `as-needed`
`jsxSingleQuote`	bool	JSX 是否使用单引号，默认 `false`
`trailingComma`	string	尾随逗号：`none`/`es5`/`all`，默认 `all`
`bracketSpacing`	bool	对象字面量花括号内空格，默认 `true`
`bracketSameLine`	bool	多行 HTML/JSX 元素的 `>` 是否放最后一行，默认 `false`
`arrowParens`	string	箭头函数参数括号：`always`/`avoid`，默认 `always`
`requirePragma`	bool	仅格式化含 `@format`/`@prettier` 标记的文件，默认 `false`
`insertPragma`	bool	在文件顶部插入 `@format` 标记，默认 `false`
`proseWrap`	string	Markdown 文本换行：`always`/`never`/`preserve`，默认 `preserve`
`htmlWhitespaceSensitivity`	string	HTML 空白敏感度：`css`/`strict`/`ignore`，默认 `css`
`vueIndentScriptAndStyle`	bool	Vue 文件 `script`/`style` 是否缩进，默认 `false`
`endOfLine`	string	换行符：`lf`/`crlf`/`cr`/`auto`，默认 `lf`
`embeddedLanguageFormatting`	string	嵌入语言格式化：`auto`/`off`，默认 `auto`
`singleAttributePerLine`	bool	HTML/Vue/JSX 单属性单行，默认 `false`
`overrides`	list	按文件类型覆盖配置，每项含 `files`（glob）和 `options`（覆盖项）

配置覆盖（Overrides）示例：

针对不同文件类型或目录使用不同配置：

{
  "semi": true,
  "singleQuote": true,
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "proseWrap": "always",
        "printWidth": 100
      }
    },
    {
      "files": ["*.html", "*.vue"],
      "options": {
        "htmlWhitespaceSensitivity": "css"
      }
    },
    {
      "files": ["*.test.js", "*.spec.ts"],
      "options": {
        "printWidth": 100
      }
    }
  ]
}

推荐配置示例（通用前端项目）：

使用 Prettier 默认配置即可满足大多数项目需求。以下为常见微调：

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 80,
  "tabWidth": 2,
  "endOfLine": "lf"
}

推荐配置示例（Vue 项目）：

参考 vuejs/core 仓库的配置：

{
  "semi": false,
  "singleQuote": true,
  "arrowParens": "avoid"
}

.prettierrc.js（ES Modules）示例：

/** @type {import("prettier").Config} */
const config = {
  semi: true,
  singleQuote: true,
  trailingComma: "all",
  printWidth: 80,
  tabWidth: 2,
  endOfLine: "lf",
};

export default config;

5. 主流集成方式

以下配置均基于 Prettier 3.8.4 最新稳定版本。

5.1 lint-staged + husky（JS/TS 生态推荐 pre-commit 方案）

这是 Prettier 官方推荐的首选 pre-commit 方案，适合需要同时使用 ESLint 等其他工具的场景。详见官方文档 Pre-commit Hook。

# 安装依赖
npm install --save-dev husky lint-staged

# 初始化 husky
npx husky init

# 配置 pre-commit 钩子
echo "npx lint-staged" > .husky/pre-commit

package.json 中配置 lint-staged：

{
  "lint-staged": {
    "**/*": "prettier --write --ignore-unknown"
  }
}

如果同时使用 ESLint，需确保 lint-staged 先运行 ESLint 再运行 Prettier。

增量检查：lint-staged 只对 Git 暂存区的文件运行 Prettier，是最高效的增量检查方案。配合 husky 的 pre-commit 钩子，每次 git commit 时自动格式化暂存文件。

5.2 pretty-quick（轻量级 pre-commit 方案）

适用于仅需 Prettier 格式化的场景。详见官方文档 Pre-commit Hook - pretty-quick。

npm install --save-dev simple-git-hooks pretty-quick

{
  "simple-git-hooks": {
    "pre-commit": "npx pretty-quick --staged"
  }
}

增量检查：pretty-quick --staged 会自动检测暂存区中变更的文件并运行 Prettier，天然实现文件级增量。

5.3 git-format-staged（支持部分暂存文件）

适用于需要支持 git add --patch（部分暂存）的场景。详见官方文档 Pre-commit Hook - git-format-staged。

npm install --save-dev git-format-staged

.husky/pre-commit 内容：

git-format-staged -f 'prettier --ignore-unknown --stdin --stdin-filepath "{}"' .

增量检查：git-format-staged 自动处理暂存区变更文件，支持 git add --patch（部分暂存）场景下的精确增量格式化。

5.4 pre-commit 集成

Prettier 官方仓库（prettier/prettier）不提供 .pre-commit-hooks.yaml 文件。pre-commit 团队曾维护镜像仓库 pre-commit/mirrors-prettier，但因 Prettier 4.0 的插件机制变更已于 2024 年 4 月归档停止维护 $TRAE_REF。

推荐使用 repo: local + language: system 方式集成为 pre-commit local hook，通过 npx prettier 调用项目本地安装的 Prettier，确保版本与项目一致。这样 pre-commit run --all-files 一条命令即可在本地提交前和 CI 中执行相同的格式检查，保证本地与 CI 门禁一致性。

说明：在 JS/TS 生态中，lint-staged + husky 也是主流的提交前方案。pre-commit 框架的 local hook 方式更适合需要统一多语言检查入口的项目（如同时包含 Python、Shell 等非 JS 代码）。

推荐方式：local hook（修复模式）

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: prettier-format
      name: Prettier format
      entry: npx prettier --write
      language: system
      files: \.(js|ts|jsx|tsx|json|css|md)$

npx prettier --write 直接复用项目本地安装的 Prettier（node_modules 中的版本），无需 pre-commit 框架额外管理依赖，版本与 package.json 中声明的一致。格式化工具修改文件后 pre-commit 会终止提交，开发人员需重新 git add 修复后的文件再提交。

备选方式：镜像仓库（仅 Prettier 2.x/3.x，已归档）

如果项目仍使用 Prettier 2.x/3.x 且希望使用镜像仓库方式（已归档但仍可用旧版本），配置示例如下：

repos:
  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: "v3.0.0-alpha.6" # 镜像仓库最后维护版本，建议改用 local hook
    hooks:
      - id: prettier
        types_or:
          [javascript, jsx, ts, tsx, json, yaml, markdown, css, html, vue]

types_or 字段限制只处理指定类型的文件，避免对不支持的文件报错。如需全量检查，可手动运行 pre-commit run prettier --all-files。

与 lint-staged + Husky 方案的差异：lint-staged + Husky 仅对暂存区文件执行格式化（通常是 --write 修复模式），且只在本地提交时触发，CI 中需要另外配置检查命令。而 pre-commit local hook 方式在本地执行 pre-commit run --all-files 与 CI 中执行同一命令，确保本地与 CI 门禁一致，避免"本地通过但 CI 失败"的问题。

Shell 脚本方案（官方文档 Pre-commit Hook - Shell script）：直接在 .git/hooks/pre-commit 中编写脚本，无需额外依赖。

#!/bin/sh
FILES=$(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g')
[ -z "$FILES" ] && exit 0
echo "$FILES" | xargs ./node_modules/.bin/prettier --ignore-unknown --write
echo "$FILES" | xargs git add
exit 0

此方案通过 git diff --cached 获取暂存区变更文件，天然实现文件级增量检查。

5.5 IDE 集成

VS Code

扩展名称：Prettier - Code formatter（扩展 ID：esbenp.prettier-vscode）
安装：在 VS Code 扩展面板搜索 "Prettier" 安装
配置文档：https://github.com/prettier/prettier-vscode

推荐 settings.json 配置：

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.requireConfig": true,
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

prettier.requireConfig 设为 true 可确保 VS Code 只在项目有 Prettier 配置文件时才格式化，避免使用全局默认设置导致不一致。

IntelliJ IDEA / WebStorm / PyCharm / GoLand

JetBrains 系列 IDE 内置 Prettier 支持，无需额外安装插件。详见官方文档 WebStorm Setup。

配置步骤：

确保安装了 Node.js（TypeScript 配置文件需 Node.js >= 22.6.0）
在项目中安装 Prettier：npm install --save-dev --save-exact prettier
打开设置：Settings/Preferences > Languages & Frameworks > JavaScript > Prettier
选择 自动 Prettier 配置（推荐），IDE 会自动检测 node_modules 中的 Prettier 和配置文件
勾选 保存时运行（Run on save）实现保存自动格式化

Vim / Neovim

Prettier 官方文档提供了 Vim Setup 指南。支持以下插件：

vim-prettier（Prettier 专用）
Neoformat（多语言格式化器）
ALE（多语言 Linter/格式化器）
coc-prettier（LSP 方式）

5.6 命令行使用方式

常用命令

# 格式化所有文件（写入模式）
npx prettier --write .

# 检查所有文件（不修改，仅报告）
npx prettier --check .

# 格式化指定目录
npx prettier --write src/

# 格式化指定文件类型
npx prettier --write "src/**/*.{js,ts,jsx,tsx}"

# 使用缓存加速（推荐用于大型项目）
npx prettier --write . --cache

# 忽略未知文件类型
npx prettier --write "**/*" --ignore-unknown

# 从 stdin 读取并格式化
cat src/file.js | npx prettier --stdin-filepath src/file.js

检查模式 vs 修复模式

模式	命令	行为	适用场景
检查模式	`prettier --check .`	不修改文件，仅报告不符合格式的文件。有不符合的文件时返回退出码 1	CI/CD 流水线、pre-commit 检查
修复模式	`prettier --write .`	直接修改文件为格式化后的内容	本地开发、手动修复

常用参数

参数	说明
`--write` / `-w`	格式化并写入文件（修复模式）
`--check` / `-c`	检查格式（不修改文件）
`--list-different` / `-l`	列出需要格式化的文件名
`--cache`	启用缓存，加速重复格式化
`--cache-strategy <metadata\|content>`	缓存策略
`--cache-location <path>`	自定义缓存文件路径
`--ignore-unknown` / `-u`	忽略不支持的文件类型
`--config <path>`	指定配置文件路径
`--no-config`	不使用配置文件
`--ignore-path <path>`	指定 ignore 文件路径（默认 `.prettierignore`）
`--find-config-path <path>`	查找指定文件的配置文件路径
`--with-node-modules`	不忽略 node_modules 目录
`--no-error-on-unmatched-pattern`	glob 无匹配时不报错
`--log-level <error\|warn\|log\|debug\|silent>`	日志级别

增量检查：Prettier 自身不提供 --diff 或 --since 类增量参数，但提供 --cache 缓存加速参数，也支持基于 Git 的命令行增量方案。

--cache 参数（缓存加速）

参数	说明
`--cache`	启用缓存，跳过未变更文件（基于 Prettier 版本、配置、Node.js 版本和文件内容/元数据）
`--cache-strategy metadata`	使用文件元数据（时间戳）作为缓存键，速度更快
`--cache-strategy content`	使用文件内容作为缓存键（默认），更准确

# 使用缓存加速全量检查
npx prettier --check . --cache

缓存文件默认存储在 ./node_modules/.cache/prettier/.prettier-cache。

基于 Git 的命令行增量方案

# 检查相对于 main 分支的所有变更文件
git diff --name-only --diff-filter=ACMR origin/main...HEAD -- \
  '*.js' '*.ts' '*.jsx' '*.tsx' '*.json' '*.css' '*.html' '*.md' '*.yaml' '*.vue' \
  | xargs -r npx prettier --check

# 检查暂存区中的变更文件
git diff --name-only --cached --diff-filter=ACMR -- \
  '*.js' '*.ts' '*.jsx' '*.tsx' '*.json' '*.css' '*.html' '*.md' '*.yaml' '*.vue' \
  | xargs -r npx prettier --check

CI 脚本调用：在 CI 环境中通过脚本调用 Prettier 进行格式化检查。官方文档推荐使用 autofix.ci GitHub App 自动修复格式问题，以下为手动检查方案。

GitHub Actions

.github/workflows/format-check.yml：

name: Format Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  prettier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

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

GitLab CI

.gitlab-ci.yml：

stages:
  - lint

prettier-check:
  stage: lint
  image: node:22-alpine
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  before_script:
    - npm ci
  script:
    - npx prettier --check .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

增量检查：CI/CD 场景下可基于 git diff 筛选变更文件实现增量检查。

GitHub Actions（增量：基于 git diff）

- name: Check formatting of changed files
  run: |
    CHANGED_FILES=$(git diff --name-only origin/main...HEAD -- \
      '*.js' '*.ts' '*.jsx' '*.tsx' '*.json' '*.jsonc' '*.css' '*.scss' \
      '*.html' '*.md' '*.mdx' '*.yaml' '*.yml' '*.vue')
    if [ -n "$CHANGED_FILES" ]; then
      echo "$CHANGED_FILES" | xargs npx prettier --check
    else
      echo "No files to check."
    fi

GitLab CI（增量：基于 git diff）

script:
  - |
    CHANGED_FILES=$(git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA...$CI_COMMIT_SHA -- \
      '*.js' '*.ts' '*.jsx' '*.tsx' '*.json' '*.css' '*.html' '*.md' '*.yaml' '*.vue')
    if [ -n "$CHANGED_FILES" ]; then
      echo "$CHANGED_FILES" | xargs npx prettier --check
    else
      echo "No files to check."
    fi

5.7 npm / yarn / pnpm / bun（JS/TS 生态主流方式）

安装

# npm（推荐使用 --save-exact 锁定精确版本）
npm install --save-dev --save-exact prettier

# yarn
yarn add --dev --exact prettier

# pnpm
pnpm add --save-dev --save-exact prettier

# bun
bun add --dev --exact prettier

建议使用 --save-exact（或 --exact）锁定精确版本，确保团队成员和 CI 使用相同版本。Prettier 官方文档明确指出：即使补丁版本也可能导致格式差异。

package.json scripts 配置

{
  "scripts": {
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}

6. 告警抑制（屏蔽）方法

6.1 通过集成调度工具屏蔽

lint-staged 文件匹配

通过 lint-staged 的 glob 模式控制 Prettier 的作用范围：

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json,css,html}": "prettier --write",
    "*.md": "prettier --write --tab-width 4"
  }
}

pre-commit 框架 include/exclude

使用 pre-commit 框架时，可通过 files、exclude 和 types_or 等字段控制 Prettier 钩子的作用范围。

repos:
  - repo: local
    hooks:
      - id: prettier
        name: prettier
        entry: npx prettier --check
        language: system
        files: \.(js|ts|jsx|tsx|json|css|html|md|yaml|vue)$
        exclude: ^(dist/|build/|coverage/|node_modules/)

files：正则匹配需要处理的文件路径
exclude：正则匹配需要排除的文件路径
types_or：按文件类型过滤

6.2 通过工具配置文件屏蔽（.prettierignore）

官方文档：Ignoring Code - .prettierignore

在项目根目录创建 .prettierignore 文件，使用 gitignore 语法排除不需要格式化的文件和目录。

.prettierignore 示例：

# 构建产物
dist/
build/
coverage/
out/

# 依赖
node_modules/

# 自动生成的文件
*.min.js
*.min.css
package-lock.json
pnpm-lock.yaml
yarn.lock

# 静态资源
*.svg
*.png
*.jpg
*.ico

# 配置文件
.env
.env.*

# 其他
CHANGELOG.md
LICENSE

Prettier 默认会忽略 .git、.jj、.sl、.svn、.hg 目录和 node_modules 目录（除非使用 --with-node-modules 参数）。如果存在 .gitignore 文件，Prettier 也会遵循其中的规则。

6.3 通过工具命令行参数屏蔽

`--ignore-path` 参数

官方文档：CLI - --ignore-path

指定自定义的 ignore 文件路径（默认查找 .prettierignore 和 .gitignore）：

npx prettier --write . --ignore-path .my-custom-ignore

支持多个值：

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

负向 glob 模式排除

官方文档：Ignoring Code - Command Line File Patterns

使用否定模式排除特定文件，无需修改 ignore 文件：

# 格式化所有文件，但排除 js 和 vue 文件
npx prettier . "!**/*.{js,jsx,vue}" --write

`--no-config` 参数

不使用任何配置文件，回退到 Prettier 默认配置：

npx prettier --write . --no-config

6.4 通过代码屏蔽（prettier-ignore）

官方文档：Ignoring Code

在代码中使用注释跳过格式化，支持多种语言。

JavaScript / TypeScript

// prettier-ignore
const matrix = [
  1, 0, 0,
  0, 1, 0,
  0, 0, 1,
];

JSX

<div>
  {/* prettier-ignore */}
  <span     ugly  format=''   />
</div>

HTML

<!-- prettier-ignore -->
<div         class="x"       >hello world</div            >

CSS / SCSS

/* prettier-ignore */
.my    ugly rule
{
}

Markdown

<!-- prettier-ignore -->
Do   not    format   this

范围忽略（Range Ignore，v1.12.0+）

适用于自动生成的内容（如 all-contributors、markdown-toc 等）：

<!-- prettier-ignore-start -->
<!-- SOMETHING AUTO-GENERATED BY TOOLS - START -->
| MY | AWESOME | AUTO-GENERATED | TABLE |
|-|-|-|-|
| a | b | c | d |
<!-- SOMETHING AUTO-GENERATED BY TOOLS - END -->
<!-- prettier-ignore-end -->

注意： 和  前必须有空行。

YAML

# prettier-ignore
key  : value
hello: world

GraphQL

{
  # prettier-ignore
  addReaction(input:{superLongInputFieldName:"MDU6SXNjdWUyMzEzOTE1NTE=",content:HOORAY}) {
    reaction {content}
  }
}

文件级注释 Pragma（v1.7.0+）

官方文档：Options - Require Pragma

在文件顶部添加 @prettier 或 @format 注释，配合 --require-pragma 参数使用，实现渐进式迁移：

/**
 * @format
 */
const unformatted = "code";

npx prettier --write . --require-pragma

文件级注释排除 Pragma（v3.6.0+）

官方文档：Options - Check Ignore Pragma

在文件顶部添加 @noprettier 或 @noformat 注释，配合 --check-ignore-pragma 参数使用：

/**
 * @noprettier
 */
const code = "that won't be formatted";

npx prettier --write . --check-ignore-pragma

参考资料

Prettier 官网：https://prettier.io
Prettier GitHub 仓库：https://github.com/prettier/prettier
Prettier 3.8.4 Release：https://github.com/prettier/prettier/releases/tag/3.8.4
Prettier CLI 文档：https://prettier.io/docs/cli
Prettier 配置文件文档：https://prettier.io/docs/configuration
Prettier 选项文档：https://prettier.io/docs/options
Prettier 忽略代码文档：https://prettier.io/docs/ignore
Prettier Pre-commit Hook 文档：https://prettier.io/docs/precommit
Prettier CI 文档：https://prettier.io/docs/ci
Prettier 编辑器集成文档：https://prettier.io/docs/editors
Prettier WebStorm 设置文档：https://prettier.io/docs/webstorm
Prettier 与 Linter 集成文档：https://prettier.io/docs/integrating-with-linters
Prettier 插件文档：https://prettier.io/docs/plugins
Prettier 选项设计哲学：https://prettier.io/docs/option-philosophy
Prettier vs. Linters：https://prettier.io/docs/comparison
eslint-config-prettier：https://github.com/prettier/eslint-config-prettier
lint-staged：https://github.com/okonet/lint-staged
husky：https://github.com/typicode/husky
pre-commit 框架：https://pre-commit.com
Prettier VS Code 扩展：https://github.com/prettier/prettier-vscode