# https://github.com/prettier/prettier 项目说明书

生成时间：2026-06-14 20:58:17 UTC

## 目录

- [Prettier Overview and Core Architecture](#page-overview-architecture)
- [Language Support and Plugin System](#page-language-plugins)
- [CLI, Configuration System and Options](#page-cli-configuration)
- [Programmatic API, Editor Integration and Extensibility](#page-api-extensibility)

<a id='page-overview-architecture'></a>

## Prettier Overview and Core Architecture

### 相关页面

相关主题：[Language Support and Plugin System](#page-language-plugins), [CLI, Configuration System and Options](#page-cli-configuration), [Programmatic API, Editor Integration and Extensibility](#page-api-extensibility)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/prettier/prettier/blob/main/README.md)
- [package.json](https://github.com/prettier/prettier/blob/main/package.json)
- [website/README.md](https://github.com/prettier/prettier/blob/main/website/README.md)
- [website/src/pages/index.jsx](https://github.com/prettier/prettier/blob/main/website/src/pages/index.jsx)
- [src/language-js/print/binaryish.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/binaryish.js)
- [src/language-js/print/miscellaneous.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/miscellaneous.js)
- [src/cli/cli-options.evaluate.js](https://github.com/prettier/prettier/blob/main/src/cli/cli-options.evaluate.js)
- [packages/plugin-hermes/README.md](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/README.md)
- [packages/plugin-hermes/package.json](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/package.json)
- [packages/plugin-oxc/package.json](https://github.com/prettier/prettier/blob/main/packages/plugin-oxc/package.json)
</details>

# Prettier 总览与核心架构

## 1. 项目定位与设计目标

Prettier 是一个 **opinionated code formatter（强约定式代码格式化器）**。它通过解析源代码并依据自身规则重新打印来强制实施统一的代码风格，最大限度上减少了开发者在代码审查中讨论排版细节的成本。资料来源：[README.md:1-15]()

> "Prettier is an opinionated code formatter. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary."

Prettier 3.x 当前的开发版本号为 `3.9.0-dev`（截至最新 main 分支），采用 ESM 模块体系（`"type": "module"`），并要求 Node.js `>=22` 运行。资料来源：[package.json:3-18]()

Prettier 的设计哲学强调 **"抵制添加配置项"**（Resist adding configuration），这是社区中被广泛讨论的核心原则之一——issue #40 指出，每次添加新的可配置选项都会带来"公地悲剧"，削弱格式化器的一致性。资料来源：[README.md:31-32]()

## 2. 核心架构：解析 → 文档模型 → 打印

Prettier 的核心处理管线由三个阶段组成：解析（Parse）、构建中间文档（Doc）、打印（Print）。

### 2.1 解析阶段（Parser）

Prettier 通过为不同语言接入不同的解析器（Parser）来支持 JavaScript、TypeScript、CSS、HTML、Markdown、YAML、GraphQL、Angular 等多种语言。资料来源：[README.md:36-58]()

- 对于 JavaScript/TypeScript，使用 Babel、TypeScript 或 Hermes 等解析器。
- 通过插件机制，第三方可以为新语言接入自定义 Parser，例如 `@prettier/plugin-hermes` 通过 overrides 配置为 `**/*.{js.flow,js,mjs,cjs}` 文件指定 `parser: "hermes"`。资料来源：[packages/plugin-hermes/README.md:18-30]()
- 较新的 `@prettier/plugin-oxc` 提供基于 Oxc 的高性能 JavaScript 解析后端（`oxc-parser 0.135.0`）。资料来源：[package.json:74](), [packages/plugin-oxc/package.json:1-23]()

### 2.2 中间文档模型（Doc IR）

解析阶段生成的 AST 不会直接序列化为字符串，而是被转换为 Prettier 自有的 **Doc 文档中间表示（Intermediate Representation）**。Doc 由 `group`、`indent`、`line`、`softline`、`hardline`、`align`、`ifBreak`、`join` 等组合子构成，可以在不修改 AST 的前提下尝试多种换行方案。资料来源：[src/language-js/print/binaryish.js:1-14](), [src/language-js/print/miscellaneous.js:1-7]()

以 `BinaryExpression` / `LogicalExpression` / `NGPipeExpression` 的打印为例，`printBinaryishExpression` 通过 `align`、`indent`、`join`、`softline` 等组合子构造可折叠的 Doc 树，由后续 Doc Printer 决定何时折行。资料来源：[src/language-js/print/binaryish.js:25-32]()

### 2.3 打印阶段（Doc Printer）

Doc Printer 接收 Doc 树，按照 `printWidth` 等约束输出最终文本。该阶段独立于具体语言，因此同一套 Doc 渲染逻辑被所有语言共用——这也是 Prettier 能够在数十种语言之间保持一致风格的根本原因。资料来源：[README.md:62-66]()

### 2.4 整体数据流

```mermaid
flowchart LR
    A[源代码] --> B[Parser<br/>语言相关]
    B --> C[AST]
    C --> D[AST → Doc<br/>语言相关 Printer]
    D --> E[Doc IR<br/>group/indent/line]
    E --> F[Doc Printer<br/>语言无关]
    F --> G[格式化输出]
```

## 3. 插件系统（Plugin System）

Prettier 通过插件机制扩展语言支持与解析后端。当前版本在 `package.json` 的 `exports` 中暴露 `"./plugins/*"` 子路径，便于加载内置插件；同时也支持第三方包以 `"prettier"` peer 依赖的形式挂载。资料来源：[package.json:27-32]()

以 `@prettier/plugin-hermes` 为例，使用方式如下：

```js
// prettier.config.mjs
import * as prettierPluginHermes from "@prettier/plugin-hermes";
export default {
  plugins: [prettierPluginHermes],
};
```
资料来源：[packages/plugin-hermes/README.md:12-22]()

插件通过 overrides 机制可以按文件模式（files glob）绑定到具体的 parser，从而实现混合代码库的格式化。资料来源：[packages/plugin-hermes/README.md:24-31]()

## 4. CLI 与配置体系

`src/cli/cli-options.evaluate.js` 集中维护所有 CLI 选项，例如 `editorconfig`、`errorOnUnmatchedPattern`、`fileInfo`、`findConfigPath`、`ignorePath`、`ignoreUnknown`、`listDifferent` 等。资料来源：[src/cli/cli-options.evaluate.js:1-49]()

| 选项 | 类型 | 说明 |
|------|------|------|
| `editorconfig` | boolean | 解析配置时是否考虑 editorconfig |
| `errorOnUnmatchedPattern` | boolean | 模式未匹配时是否报错 |
| `ignorePath` | path[] | 忽略规则文件，默认 `.gitignore` 与 `.prettierignore` |
| `listDifferent` / `-l` | flag | 列出与格式化结果不同的文件 |
| `help` / `-h` | flag | 查看 CLI 用法或单个标志详情 |

`--prose-wrap preserve` 是社区中常被讨论的选项之一——issue #13634 报告该选项下段落可能被错误地提升为标题，提示 Markdown 选项在边界场景下仍需谨慎使用。资料来源：[src/cli/cli-options.evaluate.js:4-49]()

## 5. 文档站点与生态

`website/` 目录使用 Docusaurus 构建 prettier.io 站点。文档分为两类：`docs/` 目录存放下一版本（next）文档，发布时会被拷贝到 `website/versioned_docs/version-stable/` 形成稳定版本。资料来源：[website/README.md:24-30]()

首页 `website/src/pages/index.jsx` 通过 React 组件动态渲染语言支持、编辑器集成、依赖量等数据，展示了 Prettier 的生态规模。资料来源：[website/src/pages/index.jsx:55-89](), [website/src/pages/index.jsx:113-145]()

## 6. 常见失败模式与社区关注点

- **Markdown 列表数字精度**：issue #17778 指出，当有序列表项数字 ≥ `999999999999999934464` 时会被转为科学计数法；issue #19339 进一步讨论标记长度的 10 位限制源于浏览器整数溢出。
- **最终换行控制**：issue #6360 长期讨论是否允许禁用文件末尾换行，反映社区对"无配置"哲学的张力。
- **Markdown 解析器升级**：v3.9 已升级到最新 `micromark` 并支持 GraphQL v17，但 MDX 升级仍在进行中，可能需要下一个主版本。资料来源：[社区上下文](https://github.com/prettier/prettier/issues/19332)
- **嵌套三元运算符缩进**：issue #5814 是讨论度最高的格式化争议之一（232 条评论），反映格式化决策的复杂性。
- **`useTabs` 默认值**：issue #7475（661 条评论）讨论是否将默认缩进改为 Tab，体现了配置极简与开发者偏好之间的权衡。

## See Also

- [Prettier Options Philosophy](https://prettier.io/docs/option-philosophy)
- [CLI Usage](https://prettier.io/docs/cli)
- [Plugin API](https://prettier.io/docs/plugins)
- [Doc IR Internals](https://github.com/prettier/prettier/tree/main/src/document)

---

<a id='page-language-plugins'></a>

## Language Support and Plugin System

### 相关页面

相关主题：[Prettier Overview and Core Architecture](#page-overview-architecture), [Programmatic API, Editor Integration and Extensibility](#page-api-extensibility)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/prettier/prettier/blob/main/README.md)
- [package.json](https://github.com/prettier/prettier/blob/main/package.json)
- [src/cli/cli-options.evaluate.js](https://github.com/prettier/prettier/blob/main/src/cli/cli-options.evaluate.js)
- [src/language-js/print/miscellaneous.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/miscellaneous.js)
- [src/language-js/print/binaryish.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/binaryish.js)
- [src/language-js/print/union-type.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/union-type.js)
- [packages/plugin-hermes/package.json](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/package.json)
- [packages/plugin-hermes/README.md](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/README.md)
- [packages/plugin-oxc/package.json](https://github.com/prettier/prettier/blob/main/packages/plugin-oxc/package.json)
- [website/README.md](https://github.com/prettier/prettier/blob/main/website/README.md)
- [website/src/pages/index.jsx](https://github.com/prettier/prettier/blob/main/website/src/pages/index.jsx)
</details>

# Language Support and Plugin System

## 概述

Prettier 是一套「opinionated」代码格式化器,其核心价值在于:任何人都可以通过同一套规则格式化任意受支持的语言,而无需在代码评审中争论风格。为了在不强制捆绑所有解析器的前提下覆盖大量语言,Prettier 设计了一套以「语言插件 (Language Plugin)」为基本单元的扩展体系。

- 顶层包 `prettier` 在 [package.json](https://github.com/prettier/prettier/blob/main/package.json) 中声明 `main: ./src/index.cjs`、`exports: ./src/index.js`,并对外提供 `prettier/plugins/*` 子路径,使得任意符合约定的插件可以作为子路径被加载。
- 仓库根目录的 [README.md](https://github.com/prettier/prettier/blob/main/README.md) 在展示徽章与示例的同时,直接引导用户访问 `https://prettier.io/docs/plugins`,即官方对插件体系的说明入口。
- 语言插件遵循 `parsers` + `printers` 的契约:解析器把源码转换为 AST,打印机把 AST 渲染为 Prettier 的中间文档模型 (Doc),由统一的 doc-printer 输出最终文本。仓库中 `src/language-js/print/*` 下的大量文件 (例如 [src/language-js/print/binaryish.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/binaryish.js) 与 [src/language-js/print/union-type.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/union-type.js)) 即是这种 AST → Doc 渲染管线的典型实现。

```mermaid
flowchart LR
  Source[源码文本] --> Parser[Language Plugin: parsers]
  Parser --> AST[AST]
  AST --> Printer[Language Plugin: printers]
  Printer --> Doc[Doc 中间表示]
  Doc --> CoreDocPrinter[核心 doc-printer]
  CoreDocPrinter --> Output[格式化输出]
  Config[prettier config.plugins] -.加载.-> Parser
  External[(社区/官方插件包)] -.npm/imports.-> Config
```

## 内置语言插件

`prettier` 包默认捆绑了一组生产级语言插件,覆盖 JavaScript、TypeScript、CSS/LESS/SCSS、HTML/Vue/Angular、GraphQL、Markdown、YAML 等,这些插件在 [package.json](https://github.com/prettier/prettier/blob/main/package.json) 的 `dependencies` 中以解析器依赖的形式声明,例如 `@angular/compiler`、`postcss`、`postcss-scss`、`graphql`、`hermes-parser`、`flow-parser`、`oxc-parser` 等。

| 维度 | 体现位置 | 说明 |
| --- | --- | --- |
| 解析器依赖 | [package.json](https://github.com/prettier/prettier/blob/main/package.json) 的 `dependencies` 列表 | 通过 `oxc-parser` 0.135.0、`hermes-parser` 0.36.1、`flow-parser` 0.318.0、`graphql` 17.0.0-rc.0 等支持多套 JS/Flow/Graph 方言 |
| 渲染实现 | [src/language-js/print/miscellaneous.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/miscellaneous.js) 等 print 目录 | 把统一 AST 节点 (CallExpression、MemberExpression、OptionalIndexedAccessType 等) 翻译为 Doc 片段 |
| 文档/发布 | [website/README.md](https://github.com/prettier/prettier/blob/main/website/README.md) | 通过 Docusaurus 把 `docs/` 中的语言与插件说明发布到 `https://prettier.io/docs/next/` |

实际渲染时,语言插件会按 AST 节点类型路由到对应的 print 函数。例如下面这段摘自 [src/language-js/print/binaryish.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/binaryish.js) 的代码,演示了 `BinaryExpression`/`LogicalExpression`/`NGPipeExpression` 的分支如何被映射到 Doc 构造器 (`group`、`align`、`indent` 等):

```js
function printBinaryishExpression(path, options, print) {
  const { node, parent, grandparent, key } = path;
  const isInsideParenthesis =
    key !== "body" &&
    (parent.type === "IfStatement" ||
      parent.type === "WhileStatement" ||
      parent.type === "SwitchStatement" ||
      parent.type === "DoWhileStatement");
  // ...根据上下文选择单行/多行布局
}
```

类似的分支也出现在 [src/language-js/print/union-type.js](https://github.com/prettier/prettier/blob/main/src/language-js/print/union-type.js),它通过 `shouldHugUnionType` 决定 `TSUnionType` / `UnionTypeAnnotation` 是采用 `join(" | ", ...)` 的内联形式,还是按行 `| A` / `| B` / `| C` 的多行变体。

## 外部插件包

除内置语言外,Prettier 官方还把一些相对独立的解析器作为独立 npm 包发布,使主包保持精简,也为社区提供参考实现。两个具有代表性的插件包:

- **@prettier/plugin-hermes**: 名称、版本与入口在 [packages/plugin-hermes/package.json](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/package.json) 中以 `type: module`、`exports: {".": {types, default}}` 的形式声明,属于 ESM 包。
- **@prettier/plugin-oxc**: [packages/plugin-oxc/package.json](https://github.com/prettier/prettier/blob/main/packages/plugin-oxc/package.json) 同样使用 `type: module`,并区分了 `default` (Node 入口 `./index.mjs`) 与 `browser` (打包入口 `./index.browser.mjs`),便于浏览器端 / Playground 复用。

[packages/plugin-hermes/README.md](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/README.md) 给出了最小接入方式:在 `prettier.config.mjs` 中将插件加入 `plugins` 数组,或通过 `overrides` 显式把 `**/*.{js.flow,js,mjs,cjs}` 路由到 `parser: "hermes"`,并要求 `prettier>=3.6.0`。

## 配置、加载与版本兼容

CLI 层在 [src/cli/cli-options.evaluate.js](https://github.com/prettier/prettier/blob/main/src/cli/cli-options.evaluate.js) 中集中管理 `editorconfig`、`ignorePath`、`fileInfo`、`findConfigPath` 等开关,这些选项决定了 Prettier 在启动时如何发现配置文件、加载 `.prettierignore`、以及把 `prettier.config.mjs` 中 `plugins` 字段解析为可执行模块。`prettier` 主包通过 `package.json` 的 `imports` (`#universal` / `#universal/*`) 区分 Node 与浏览器实现,使同一份核心代码既能跑在 CLI,也能跑在 [website/README.md](https://github.com/prettier/prettier/blob/main/website/README.md) 中提到的 `yarn build:website` 产出的 Playground bundle (`standalone.js`)。

社区对语言支持的更新非常敏感,从 [Release v3.9](https://github.com/prettier/prettier/issues/19332) 中可以看到一次典型的「主版本跟随解析器」的演进:MDX 升级仍在进行中,而 `micromark`、`yaml@2`、`graphql@17` 等已纳入计划。这意味着对使用者而言,锁定 Prettier 小版本 (例如 `yarn add --dev --exact`,见 [packages/plugin-hermes/README.md](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/README.md) 的安装示例) 仍是规避 AST 行为变更的稳妥做法。

## 社区关注的语言/插件问题

围绕语言支持,社区讨论最多的并非「新增多少种语言」,而是格式细节的稳定性,这从 Top 议题中可见一斑:

- [Issue #40: Resist adding configuration](https://github.com/prettier/prettier/issues/40) 主张插件作者应坚持「opinionated」原则,避免每种语言都引入大量开关,这也间接塑造了插件体系偏向「少配置、可替换」的形态。
- [Issue #7475: Change useTabs to true by default](https://github.com/prettier/prettier/issues/7475) 反映了基础排版策略对几乎所有语言插件的连带影响。
- [Issue #5814: Nested ternary formatting](https://github.com/prettier/prettier/issues/5814) 与 [Issue #3806: Placing operators at the beginning of lines](https://github.com/prettier/prettier/issues/3806) 都横跨 JS/TS 与格式化表达式,需要 `print/binaryish.js` 等文件共同调整。
- Markdown 相关的 [Issue #13634](https://github.com/prettier/prettier/issues/13634) 与 [Issue #17778](https://github.com/prettier/prettier/issues/17778) (有序列表 marker 长度限制、极大数字被转成科学计数法),以及 [Release 3.8.4](https://github.com/prettier/prettier/releases/tag/3.8.4) 中关于「Markdown 列表子项之间空行被吞掉」的修复 ([#17746](https://github.com/prettier/prettier/pull/17746)),都集中在 `language-markdown` 这一内置插件上,是 v3.9 升级 `micromark` 的直接动机。

## See Also

- [Issue #40: Resist adding configuration](https://github.com/prettier/prettier/issues/40)
- [Release v3.9 tracking issue](https://github.com/prettier/prettier/issues/19332)
- [Release 3.8.4 changelog](https://github.com/prettier/prettier/releases/tag/3.8.4)
- 官方插件文档入口:[prettier.io/docs/plugins](https://prettier.io/docs/plugins) (经 [README.md](https://github.com/prettier/prettier/blob/main/README.md) 引导)

---

<a id='page-cli-configuration'></a>

## CLI, Configuration System and Options

### 相关页面

相关主题：[Prettier Overview and Core Architecture](#page-overview-architecture), [Programmatic API, Editor Integration and Extensibility](#page-api-extensibility)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cli/cli-options.evaluate.js](https://github.com/prettier/prettier/blob/main/src/cli/cli-options.evaluate.js)
- [src/cli/format.js](https://github.com/prettier/prettier/blob/main/src/cli/format.js)
- [src/cli/expand-patterns.js](https://github.com/prettier/prettier/blob/main/src/cli/expand-patterns.js)
- [src/cli/options/parse-cli-arguments.js](https://github.com/prettier/prettier/blob/main/src/cli/options/parse-cli-arguments.js)
- [src/cli/options/normalize-cli-options.js](https://github.com/prettier/prettier/blob/main/src/cli/options/normalize-cli-options.js)
- [src/experimental-cli/index.js](https://github.com/prettier/prettier/blob/main/src/experimental-cli/index.js)
- [package.json](https://github.com/prettier/prettier/blob/main/package.json)
- [README.md](https://github.com/prettier/prettier/blob/main/README.md)
- [packages/plugin-hermes/package.json](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/package.json)
</details>

# CLI、配置系统与选项

## 概述

Prettier 是一个**意见强烈的代码格式化工具**（Opinionated Code Formatter），通过解析源代码并按照其自身规则重新打印来强制一致的代码风格。CLI、配置系统与选项三者共同构成用户与 Prettier 交互的入口，决定了格式化行为如何被控制、查找和生效——CLI 承担参数解析、文件匹配与格式化调度；配置系统负责发现并合并来自多个来源的设置；选项层则集中定义所有可配置行为的元数据（默认值、类型、别名等），三者由仓库中显式分层的源码模块协作完成。

资料来源：[src/cli/cli-options.evaluate.js](), [README.md]()

## 选项元数据架构

CLI 选项在仓库中以**声明式元数据**形式集中维护。每个选项对象至少包含 `description`、`type` 以及可选的 `alias`、`category`、`default`、`array`、`oppositeDescription`、`exception` 等字段，便于 CLI 解析、文档生成和默认值校验复用同一份数据，避免选项定义在源码、文档与帮助输出之间漂移。

资料来源：[src/cli/cli-options.evaluate.js]()

| 字段 | 用途 | 示例 |
| --- | --- | --- |
| `type: "boolean"` | 布尔开关 | `errorOnUnmatchedPattern`、`ignoreUnknown` |
| `type: "path"` | 路径类型，支持数组形式 | `ignorePath`、`findConfigPath` |
| `type: "flag"` | 仅触发副作用 | `help`（支持 `--help <flag>`） |
| `alias` | 短选项映射 | `help` → `h`、`ignoreUnknown` → `u` |
| `category` | `--help` 输出分组 | `CATEGORY_CONFIG`、`CATEGORY_OUTPUT` |
| `oppositeDescription` | 提供"反向"描述 | 用于开关型选项的反义文档 |
| `array` | 多值数组 | `ignorePath: { array: true, default: [{ value: [".gitignore", ".prettierignore"] }] }` |
| `exception` | 允许特定值绕过校验 | `help: (value) => value === ""` |

以 `ignorePath` 为例，其定义为 `array: true`，默认值为 `[{ value: [".gitignore", ".prettierignore"] }]`，表明 Prettier 默认同时读取两类忽略文件作为过滤规则。`help` 选项则使用 `exception: (value) => value === ""` 来支持 `--help <flag>` 这种"查询特定 flag 详情"的子命令模式。

资料来源：[src/cli/cli-options.evaluate.js]()

## CLI 与 API 的双入口设计

仓库在 `package.json` 中同时暴露 CLI 与程序化 API 入口，使 Prettier 既可作为命令行工具被脚本/CI 调用，也可作为 Node 库嵌入到编辑器或构建工具中。

资料来源：[package.json]()

- `bin: "./bin/prettier.cjs"`：CLI 可执行入口
- `main: "./src/index.cjs"`：CommonJS 入口（`require` 兼容）
- `exports.default: "./src/index.js"`：ESM 默认入口
- `browser` / `unpkg`：浏览器与 CDN 入口，对应 `./standalone.js`
- `exports["./plugins/*"]`：插件子路径，允许第三方格式化器以插件方式加载

Node 引擎要求被显式锁定为 `"engines": { "node": ">=22" }`，确保运行时的现代特性（如原生 fetch、原生 ESM 解析稳定版）可用；同时 `"type": "module"` 表明主包面向 ESM 优先的运行时。

## 配置文件的解析与优先级

Prettier 在格式化之前会按一定优先级合并多来源配置。命令行参数具有最高优先级，其次是项目中的 `.prettierrc*` / `prettier.config.*`，再次是 `editorconfig`（需显式启用 `editorconfig` 选项），最后是内置默认值。`findConfigPath` 选项专门用于"查找并打印给定输入文件的配置文件路径"，便于在多层级 monorepo 中调试配置继承问题。

资料来源：[src/cli/cli-options.evaluate.js](), [README.md]()

社区中关于"选项膨胀"的长期争论（见 Issue #40 "Resist adding configuration"，41 条评论）正建立在"配置优先级 + 最小化选项集"的哲学之上——任何新增配置都会显著增加测试矩阵、文档维护成本与跨语言一致性风险。

## 选项哲学与插件可扩展性

Prettier 的核心原则之一是**"只暴露必要选项"**。除少数核心开关（如 `printWidth`、`tabWidth`、`useTabs`、`semi` 等）外，许多看似合理的格式化变体被刻意不开放，以维护"无需讨论风格"的初衷。这种克制也体现在 CLI 选项元数据中：大量字段没有 `default` 键，说明默认值由具体格式化语言决定而非全局统一。

资料来源：[README.md]()

当内置选项无法满足特殊需求时，可通过插件机制扩展。`package.json` 的 `exports["./plugins/*"]` 字段允许发布独立的格式化器包，例如 `@prettier/plugin-hermes`（其 `package.json` 中 `sideEffects: false`、`type: "module"` 表明面向现代打包器优化）。插件以相同的元数据约定（`languages`、`parsers`、`printers`、`options`）接入主流程，从而在不修改核心的前提下为新语言提供格式化能力。

资料来源：[packages/plugin-hermes/package.json](), [package.json]()

## 配置与格式化的整体流程

```mermaid
flowchart LR
    A[CLI 参数] --> D[parse-cli-arguments]
    B[配置文件 .prettierrc] --> E[normalize-cli-options]
    C[editorconfig] --> E
    D --> E
    E --> F[merged options]
    F --> G[format / core]
    G --> H[plugin printers]
    H --> I[格式化输出]
```

资料来源：[src/cli/options/parse-cli-arguments.js](), [src/cli/options/normalize-cli-options.js](), [src/cli/format.js]()

## 常见失效模式

- **配置文件冲突**：当 `.prettierrc` 与 `prettier.config.js` 同时存在且字段不一致时，仅其中一个生效，可通过 `findConfigPath` 定位实际加载的文件。
- **忽略规则叠加**：`--ignore-path` 与 `.prettierignore` 叠加；默认行为会读取 `.gitignore` 与 `.prettierignore`，未显式设置 `ignorePath` 数组时难以覆盖默认值。
- **未知文件**：默认对无法识别扩展名的文件报错，需启用 `ignoreUnknown`（别名 `-u`）或显式 `--parser` 指定解析器。
- **选项拼写错误**：CLI 对未知 flag 不会自动给出"最接近的合法选项"提示，应通过 `--help <flag>` 反查。

## 参见

- 选项哲学：[docs/option-philosophy](https://prettier.io/docs/option-philosophy)
- CLI 完整文档：[docs/cli](https://prettier.io/docs/cli)
- API 文档：[docs/api](https://prettier.io/docs/api)
- 插件开发指南：[docs/plugins](https://prettier.io/docs/plugins)

---

<a id='page-api-extensibility'></a>

## Programmatic API, Editor Integration and Extensibility

### 相关页面

相关主题：[Prettier Overview and Core Architecture](#page-overview-architecture), [Language Support and Plugin System](#page-language-plugins), [CLI, Configuration System and Options](#page-cli-configuration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/prettier/prettier/blob/main/package.json)
- [README.md](https://github.com/prettier/prettier/blob/main/README.md)
- [packages/plugin-hermes/package.json](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/package.json)
- [packages/plugin-hermes/README.md](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/README.md)
- [src/cli/cli-options.evaluate.js](https://github.com/prettier/prettier/blob/main/src/cli/cli-options.evaluate.js)
- [website/src/pages/index.jsx](https://github.com/prettier/prettier/blob/main/website/src/pages/index.jsx)
- [website/README.md](https://github.com/prettier/prettier/blob/main/website/README.md)
</details>

# Programmatic API, Editor Integration and Extensibility

## 1. 概述：Prettier 的三层集成面

Prettier 在仓库层面以同一个代码库同时提供 **Node.js 库、CLI 与浏览器/编辑器 Standalone Bundle** 三种入口；这三者共同支撑了「程序化 API、编辑器集成、可扩展性」这一主题。仓库根的 [`package.json`](https://github.com/prettier/prettier/blob/main/package.json) 通过 `exports`、`bin`、`browser`、`unpkg` 字段把这三类入口显式声明出来，使编辑器、IDE、CI 与第三方包可以按场景选择最合适的对接方式。Prettier 官方在 [README.md](https://github.com/prettier/prettier/blob/main/README.md) 中也明确将其定位为「opinionated code formatter」并建议「Run it in your editor on-save、in a pre-commit hook、or in CI environments」。

> 社区中关于「是否要持续增加可配置项」的长期讨论（[#40 Resist adding configuration](https://github.com/prettier/prettier/issues/40)）直接影响 API 与插件的扩展面：Prettier 倾向于暴露稳定的少量 `options`、把语言/方言的差异交给插件实现，而不是把每一种格式策略都直接写入主包。

## 2. 程序化 API（Node.js 入口）

主入口通过 `exports["."]` 暴露，对应 TypeScript 类型在 `src/index.d.ts`、CJS 兼容入口在 [`src/index.cjs`](https://github.com/prettier/prettier/blob/main/src/index.cjs)：

```json
"exports": {
  ".": {
    "types": "./src/index.d.ts",
    "require": "./src/index.cjs",
    "default": "./src/index.js"
  },
  "./standalone": "./src/standalone.js",
  "./plugins/*": "./src/plugins/*.js",
  "./*": "./*"
}
```

- `"."`：Node.js 主入口，ESM 优先，必要时回退到 CJS。`package.json` 中 `engines.node` 被强制约束为 `">=22"`，因此任何嵌入式宿主也需要保证 Node 22+。
- `"./standalone"`：浏览器/编辑器友好的单文件构建。
- `"./plugins/*"`：允许通过子路径加载插件，例如 `prettier/plugins/estree`。
- `"./*"`：宽松的「任何其他相对路径」兜底，承载诸如 `prettier/plugins/typescript` 之类的内置子模块。

CLI 与 Node API 的选项共用同一份 schema，定义在 [`src/cli/cli-options.evaluate.js`](https://github.com/prettier/prettier/blob/main/src/cli/cli-options.evaluate.js)。这份 evaluate 文件同时作为 CLI 解析与 API 校验的源头，因此 `prettier.format()`、`prettier.check()` 等程序化调用得到的选项和 `--write`、`--check`、`--list-different` 行为完全一致——这正是编辑器扩展可以信赖的契约。

## 3. 编辑器集成与 Standalone Bundle

编辑器集成通常不会启动 Node CLI，而是直接 import 库或使用浏览器友好的单文件包。仓库通过 `package.json` 的 `browser` 与 `unpkg` 字段统一指向 `"./standalone.js"`：

```json
"browser": "./standalone.js",
"unpkg": "./standalone.js"
```

[`website/src/pages/index.jsx`](https://github.com/prettier/prettier/blob/main/website/src/pages/index.jsx) 中 `EditorSupportSection` 把这些差异化的对接方式呈现为官网的「Editor Support」板块，数据来源是 [`website/data/editors.yml`](https://github.com/prettier/prettier/blob/main/website/data/editors.yml)，鼓励社区以 PR 方式补全新编辑器条目。Playground 与官网本地开发则通过 [`website/README.md`](https://github.com/prettier/prettier/blob/main/website/README.md) 中描述的 `yarn build:website` / `yarn build:website:pr` 把同一份代码库打包成浏览器可消费的 bundle，并配合 `static/service-worker.mjs` 做缓存。

| 入口字段 | 目标宿主 | 典型用途 |
| --- | --- | --- |
| `exports["."]` | Node.js | 程序化 API、CI 脚本、Pre-commit hook |
| `bin: ./bin/prettier.cjs` | Shell | 命令行 `prettier` |
| `browser` / `unpkg` | 浏览器/编辑器 WebView | VS Code、WebStorm、Playground |
| `exports["./standalone"]` | 显式 Node + ESM | 服务端按需引入独立 bundle |

需要特别注意的是，3.7.3 修复了 `prettier.getFileInfo()` 的行为回归（社区 issue 关联：VS Code 扩展的兼容性问题），这说明 Prettier 的「程序化 API」是把 `format`、`check`、`getFileInfo` 等方法同时提供给编辑器宿主使用的，宿主依赖的隐性契约在每次小版本都可能变化。

## 4. 可扩展性：插件、Parser、Printer

Prettier 的语言支持不是硬编码到核心，而是通过插件协议在运行时注入。`exports["./plugins/*"]` 为此提供了「按子路径懒加载」的能力。仓库内的 [`packages/plugin-hermes`](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/package.json) 是一个最小可参考的实现：

```jsonc
// packages/plugin-hermes/package.json
{
  "name": "@prettier/plugin-hermes",
  "type": "module",
  "exports": {
    ".": { "types": "./index.d.ts", "default": "./index.mjs" },
    "./*": "./*"
  },
  "sideEffects": false
}
```

该插件在 [`packages/plugin-hermes/README.md`](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/README.md) 中给出了标准接入流程：作为 `devDependency` 安装，然后在 `prettier.config.mjs` 的 `plugins` 数组中显式引用：

```js
// prettier.config.mjs
import * as prettierPluginHermes from "@prettier/plugin-hermes";
export default {
  plugins: [prettierPluginHermes],
};
```

插件需要提供 `languages`（含 `name`、`parsers`、`extensions`）和 `parsers`（含 `parse`、`astFormat`、`locStart`、`locEnd`）以及对应 `astFormat` 的 `printers`——这一契约与 [`src/cli/cli-options.evaluate.js`](https://github.com/prettier/prettier/blob/main/src/cli/cli-options.evaluate.js) 中 CLI 派发到的「按语言 → parser → printer」管线是对齐的。3.8.1 发布的「Include available `printers` in plugin type declarations」也是为了让插件作者在 TypeScript 上拿到与核心一致的 `printers` 推导，从而降低集成门槛。

对于新语言接入，约定俗成的步骤是：

1. 在 `prettier.config` 中通过 `plugins: [myPlugin]` 显式注册；
2. 通过 `overrides` 把文件 glob 映射到对应 parser：
   ```js
   overrides: [{ files: ["**/*.{js.flow,js,mjs,cjs}"], parser: "hermes", plugins: [prettierPluginHermes] }]
   ```
3. 让该 parser 在 `parsers.*.astFormat` 上声明自己的输出格式，核心调度层会按 `astFormat` 自动派发到对应 `printers`。
   核心调度层会按 `astFormat` 自动派发到对应 `printers`。
   这一管线在 [`src/language-js/print/`](https://github.com/prettier/prettier/blob/main/src/language-js/print) 目录里也有体现：例如 `class.js`、`union-type.js`、`binaryish.js`、`match.js`、`miscellaneous.js` 等模块都以「`print*(path, options, print)`」为统一签名，插件 `printers` 同样需要遵循这一签名，从而被 `path.map(print, ...)` 这类调用复用。

## 5. 通用注意事项与失败模式

- **Node 版本要求**：[`package.json`](https://github.com/prettier/prettier/blob/main/package.json) 中 `engines.node: ">=22"`，当宿主（CI、旧版编辑器运行时）低于 22 时会直接抛 `please-upgrade-node`。
- **API 兼容性**：3.7.3 的 `getFileInfo()` 修复和 3.8.1 的插件 `printers` 类型扩展均说明，程序化 API 与插件契约在小版本之间也会发生微调，编辑器扩展与下游插件作者应锁版本。
- **配置 vs 扩展**：根据 [#40](https://github.com/prettier/prettier/issues/40) 的长期共识，语言/方言/解析器差异应通过插件承载，而不是新增顶层 `options`；新的格式化策略也应优先放进 [`src/language-js/print/`](https://github.com/prettier/prettier/blob/main/src/language-js/print) 之类的实现细节中，而不是暴露为新配置。

## See Also

- CLI 与选项：[`src/cli/cli-options.evaluate.js`](https://github.com/prettier/prettier/blob/main/src/cli/cli-options.evaluate.js)
- 官网与 Playground 构建：[`website/README.md`](https://github.com/prettier/prettier/blob/main/website/README.md)
- Hermes 插件参考实现：[`packages/plugin-hermes`](https://github.com/prettier/prettier/blob/main/packages/plugin-hermes/package.json)
- JS/TS 打印管线（插件 `printers` 范例）：[`src/language-js/print/`](https://github.com/prettier/prettier/blob/main/src/language-js/print)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：prettier/prettier

摘要：发现 25 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：维护坑 - 来源证据：Should not increase ordered list mark。

## 1. 维护坑 · 来源证据：Should not increase ordered list mark

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Should not increase ordered list mark
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/prettier/prettier/issues/19339 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 失败模式：installation: Dependency Dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Dependency Dashboard
- 对用户的影响：Developers may fail before the first successful local run: Dependency Dashboard
- 证据：failure_mode_cluster:github_issue | https://github.com/prettier/prettier/issues/15461 | Dependency Dashboard

## 3. 安装坑 · 来源证据：Dependency Dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Dependency Dashboard
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/prettier/prettier/issues/15461 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：Release v3.9

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v3.9
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/prettier/prettier/issues/19332 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 5. 配置坑 · 失败模式：configuration: Disable New line at then end of file

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Disable New line at then end of file
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Disable New line at then end of file
- 证据：failure_mode_cluster:github_issue | https://github.com/prettier/prettier/issues/6360 | Disable New line at then end of file

## 6. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | github_repo:75104123 | https://github.com/prettier/prettier | README/documentation is current enough for a first validation pass.

## 7. 维护坑 · 失败模式：migration: 3.8.4

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: 3.8.4
- 对用户的影响：Upgrade or migration may change expected behavior: 3.8.4
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.8.4 | 3.8.4

## 8. 维护坑 · 失败模式：migration: Release v3.9

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Release v3.9
- 对用户的影响：Developers may hit a documented source-backed failure mode: Release v3.9
- 证据：failure_mode_cluster:github_issue | https://github.com/prettier/prettier/issues/19332 | Release v3.9

## 9. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | github_repo:75104123 | https://github.com/prettier/prettier | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | github_repo:75104123 | https://github.com/prettier/prettier | no_demo; severity=medium

## 11. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | github_repo:75104123 | https://github.com/prettier/prettier | no_demo; severity=medium

## 12. 能力坑 · 失败模式：capability: Markdown: Formatting ordered list containing a number greater or equal to 9999999999999999344...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Markdown: Formatting ordered list containing a number greater or equal to 999999999999999934464 converts the number into decimal exponential notation
- 对用户的影响：Developers may hit a documented source-backed failure mode: Markdown: Formatting ordered list containing a number greater or equal to 999999999999999934464 converts the number into decimal exponential notation
- 证据：failure_mode_cluster:github_issue | https://github.com/prettier/prettier/issues/17778 | Markdown: Formatting ordered list containing a number greater or equal to 999999999999999934464 converts the number into decimal exponential notation

## 13. 能力坑 · 失败模式：capability: Paragraph can be turned into heading with `--prose-wrap preserve`

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Paragraph can be turned into heading with `--prose-wrap preserve`
- 对用户的影响：Developers may hit a documented source-backed failure mode: Paragraph can be turned into heading with `--prose-wrap preserve`
- 证据：failure_mode_cluster:github_issue | https://github.com/prettier/prettier/issues/13634 | Paragraph can be turned into heading with `--prose-wrap preserve`

## 14. 能力坑 · 失败模式：capability: Should not increase ordered list mark

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Should not increase ordered list mark
- 对用户的影响：Developers may hit a documented source-backed failure mode: Should not increase ordered list mark
- 证据：failure_mode_cluster:github_issue | https://github.com/prettier/prettier/issues/19339 | Should not increase ordered list mark

## 15. 运行坑 · 失败模式：performance: 3.7.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: 3.7.1
- 对用户的影响：Upgrade or migration may change expected behavior: 3.7.1
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.7.1 | 3.7.1

## 16. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | github_repo:75104123 | https://github.com/prettier/prettier | issue_or_pr_quality=unknown

## 17. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | github_repo:75104123 | https://github.com/prettier/prettier | release_recency=unknown

## 18. 维护坑 · 失败模式：maintenance: 3.7.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: 3.7.0
- 对用户的影响：Upgrade or migration may change expected behavior: 3.7.0
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.7.0 | 3.7.0

## 19. 维护坑 · 失败模式：maintenance: 3.7.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: 3.7.2
- 对用户的影响：Upgrade or migration may change expected behavior: 3.7.2
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.7.2 | 3.7.2

## 20. 维护坑 · 失败模式：maintenance: 3.7.3

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: 3.7.3
- 对用户的影响：Upgrade or migration may change expected behavior: 3.7.3
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.7.3 | 3.7.3

## 21. 维护坑 · 失败模式：maintenance: 3.7.4

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: 3.7.4
- 对用户的影响：Upgrade or migration may change expected behavior: 3.7.4
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.7.4 | 3.7.4

## 22. 维护坑 · 失败模式：maintenance: 3.8.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: 3.8.0
- 对用户的影响：Upgrade or migration may change expected behavior: 3.8.0
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.8.0 | 3.8.0

## 23. 维护坑 · 失败模式：maintenance: 3.8.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: 3.8.1
- 对用户的影响：Upgrade or migration may change expected behavior: 3.8.1
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.8.1 | 3.8.1

## 24. 维护坑 · 失败模式：maintenance: 3.8.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: 3.8.2
- 对用户的影响：Upgrade or migration may change expected behavior: 3.8.2
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.8.2 | 3.8.2

## 25. 维护坑 · 失败模式：maintenance: 3.8.3

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: 3.8.3
- 对用户的影响：Upgrade or migration may change expected behavior: 3.8.3
- 证据：failure_mode_cluster:github_release | https://github.com/prettier/prettier/releases/tag/3.8.3 | 3.8.3

<!-- canonical_name: prettier/prettier; human_manual_source: deepwiki_human_wiki -->