配置选项

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

Prettier 内置了多种格式化选项。

了解 Prettier 对配置选项的设计理念，请参阅选项哲学。

建议通过配置文件修改任何选项。这样 Prettier CLI、编辑器集成和其他工具都能识别您使用的选项。

实验性三元表达式

在成为默认行为前，尝试 Prettier 的新三元表达式格式化方案。

有效选项：

true - 使用好奇三元表达式（curious ternaries），将问号放在条件语句之后
false - 保留默认三元表达式行为：将问号与结果部分保持在同一行

Default	CLI Override	API Override
`false`	`--experimental-ternaries`	`experimentalTernaries: <bool>`

实验性运算符位置

有效选项：

"start" - 当二元表达式换行时，将运算符置于新行开头
"end" - 默认行为：当二元表达式换行时，将运算符放在前一行的末尾

Default	CLI Override	API Override
`"end"`	`--experimental-operator-position <start\|end>`	`experimentalOperatorPosition: "<start\|end>"`

行宽

指定格式化工具执行换行的长度阈值。

警告

出于可读性考虑，我们建议不要超过 80 个字符：

代码风格指南通常将最大行长度设为 100 或 120 字符。但实际编码时，开发者不会刻意填满每行空间，而是通过空白符分割长行提升可读性。实践中，平均行长远低于最大值。

Prettier 的 printWidth 选项机制不同：它不是严格的长度上限限制，而是向 Prettier 传递期望的行长参考值。Prettier 会生成长短不一的代码行，但总体上会趋近指定行宽。

请记住，计算机需要明确指令，而人类可以自主判断（例如换行时机）。换句话说，不要将 printWidth 当作 ESLint 的 max-len 使用——两者有本质区别：max-len 仅规定最大允许长度，而 printWidth 指定的是理想长度。

Default	CLI Override	API Override
`80`	`--print-width <int>`	`printWidth: <int>`

在 .editorconfig 文件中设置 max_line_length 可配置 Prettier 的行宽（除非被覆盖）。

（若需在格式化 Markdown 时禁用自动换行，可设置 Prose Wrap 选项）

缩进宽度

指定每级缩进对应的空格数。

Default	CLI Override	API Override
`2`	`--tab-width <int>`	`tabWidth: <int>`

在 .editorconfig 文件中设置 indent_size 或 tab_width 可配置 Prettier 的缩进宽度（除非被覆盖）。

制表符

使用制表符（tabs）而非空格进行缩进。

Default	CLI Override	API Override
`false`	`--use-tabs`	`useTabs: <bool>`

在 .editorconfig 文件中设置 indent_style 可配置 Prettier 的制表符使用（除非被覆盖）。

（制表符用于_缩进_，但 Prettier 使用空格进行_对齐_操作（例如三元表达式）。此行为称为 SmartTabs。）

分号

在语句末尾打印分号。

有效选项：

true - 在每个语句末尾添加分号
false - 仅在可能引发ASI故障的行首添加分号。

Default	CLI Override	API Override
`true`	`--no-semi`	`semi: <bool>`

引号

使用单引号替代双引号。

注意事项：

JSX引号不受此选项影响 — 参见 jsx-single-quote。
当一种引号使用频率明显高于另一种时，系统将选用较少使用的引号格式化字符串 — 例如："I'm double quoted" 输出为 "I'm double quoted"，而 "This \"example\" is single quoted" 输出为 'This "example" is single quoted'。

更多信息请参阅字符串设计理念。

Default	CLI Override	API Override
`false`	`--single-quote`	`singleQuote: <bool>`

属性引号

控制对象属性何时添加引号。

有效选项：

"as-needed" - 仅在必需时为对象属性添加引号。
"consistent" - 若对象中至少一个属性需要引号，则为所有属性添加引号。
"preserve" - 保留对象属性中原始引号使用方式。

Default	CLI Override	API Override
`"as-needed"`	`--quote-props <as-needed\|consistent\|preserve>`	`quoteProps: "<as-needed\|consistent\|preserve>"`

注意：Prettier 在 Angular 表达式、TypeScript 和 Flow 中永远不会移除数值属性名的引号，因为这些语言中字符串键与数值键的区分至关重要（参考：Angular、TypeScript、Flow）。同时 Prettier 也不会移除 Vue 的数值属性引号（详见相关issue）。

JSX 引号

在 JSX 中使用单引号替代双引号。

Default	CLI Override	API Override
`false`	`--jsx-single-quote`	`jsxSingleQuote: <bool>`

尾随逗号

v3.0.0 起默认值从 es5 变更为 all

在多行逗号分隔的语法结构中尽可能添加尾随逗号（例如单行数组永远不会添加尾随逗号）。

有效选项：

"all" - 尽可能添加尾随逗号（包括函数参数和调用）。运行此类格式化的代码需要支持 ES2017 的引擎（Node.js 8+ 或现代浏览器）或降级编译。此选项也支持 TypeScript 类型参数中的尾随逗号（自 2018 年 1 月发布的 TypeScript 2.7 起支持）。
"es5" - 在 ES5 有效位置添加尾随逗号（对象、数组等）。支持 TypeScript 和 Flow 类型参数中的尾随逗号。
"none" - 不添加尾随逗号。

Default	CLI Override	API Override
`"all"`	`--trailing-comma <all\|es5\|none>`	`trailingComma: "<all\|es5\|none>"`

括号间距

在对象字面量中的括号内添加空格。

有效选项：

true - 示例：{ foo: bar }。
false - 示例：{foo: bar}。

Default	CLI Override	API Override
`true`	`--no-bracket-spacing`	`bracketSpacing: <bool>`

对象换行

首次发布于 v3.5.0

配置 Prettier 如何对可以放在一行或跨多行的对象字面量进行换行。

默认情况下，如果第一个属性之前有换行符，Prettier 会将对象格式化为多行。作者可以利用这种启发式方法在上下文中提高可读性，尽管这也有一些缺点。详见多行对象。

有效选项：

"preserve" - 如果左大括号和第一个属性之间有换行符，则保留为多行格式。
"collapse" - 尽可能将对象压缩到单行显示。

Default	CLI Override	API Override
`"preserve"`	`--object-wrap <preserve\|collapse>`	`objectWrap: "<preserve\|collapse>"`

括号换行

将多行 HTML 元素（HTML、JSX、Vue、Angular）的 > 放在最后一行的末尾，而不是单独放在下一行（不适用于自闭合元素）。

有效选项：

true - 示例：

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>

false - 示例：

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>

Default	CLI Override	API Override
`false`	`--bracket-same-line`	`bracketSameLine: <bool>`

[已弃用] JSX 括号

危险

此选项已在 v2.4.0 中弃用，请改用 --bracket-same-line。

将多行 JSX 元素的 > 放在最后一行的末尾，而不是单独放在下一行（不适用于自闭合元素）。

有效选项：

true - 示例：

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>

false - 示例：

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>

Default	CLI Override	API Override
`false`	`--jsx-bracket-same-line`	`jsxBracketSameLine: <bool>`

箭头函数括号

首次发布于 v1.9.0，默认值在 v2.0.0 中由 avoid 改为 always

是否在唯一的箭头函数参数周围添加括号。

有效选项：

"always" - 始终添加括号。示例：(x) => x
"avoid" - 尽可能省略括号。示例：x => x

Default	CLI Override	API Override
`"always"`	`--arrow-parens <always\|avoid>`	`arrowParens: "<always\|avoid>"`

乍看之下省略括号似乎是更好的选择，因为视觉干扰更少。然而当 Prettier 移除括号后，添加类型注解、额外参数或默认值会变得更加困难。在编辑实际代码库时，保持括号使用的一致性能够提供更好的开发体验，这也证明了该选项默认值的合理性。

范围

仅格式化文件的特定片段。

这两个选项可用于格式化从指定字符偏移量开始（包含）和结束（不包含）的代码片段。范围将扩展至：

向后延伸到包含所选语句的第一行开头
向前延伸到所选语句的末尾

Default	CLI Override	API Override
`0`	`--range-start <int>`	`rangeStart: <int>`
`Infinity`	`--range-end <int>`	`rangeEnd: <int>`

解析器

指定要使用的解析器。

Prettier 会根据输入文件路径自动推断解析器，因此通常无需更改此设置。

babel 和 flow 解析器都支持相同的 JavaScript 功能集（包括 Flow 类型注解）。它们在某些边缘情况下可能表现不同，如遇到此类情况可尝试改用 flow 而非 babel。类似地，typescript 和 babel-ts 也基本同理。babel-ts 可能支持 TypeScript 尚未实现的 JavaScript 功能（提案），但对无效代码的限制更严格，且实战测试不如 typescript 解析器充分。

有效选项：

"babel"（通过 @babel/parser）v1.16.0 之前称为 "babylon"
"babel-flow"（与 "babel" 相同，但显式启用 Flow 解析以避免歧义）首次出现于 v1.16.0
"babel-ts"（类似于 "typescript"，但使用 Babel 及其 TypeScript 插件）首次出现于 v2.0.0
"flow"（通过 flow-parser）
"typescript"（通过 @typescript-eslint/typescript-estree）首次出现于 v1.4.0
"espree"（通过 espree）首次出现于 v2.2.0
"meriyah"（通过 meriyah）首次出现于 v2.2.0
"acorn"（通过 acorn）首次出现于 v2.6.0
"css"（通过 postcss）首次出现于 v1.7.1
"scss"（通过 postcss-scss）首次出现于 v1.7.1
"less"（通过 postcss-less）首次出现于 v1.7.1
"json"（通过 @babel/parser parseExpression）首次出现于 v1.5.0
"json5"（与 "json" 相同解析器，但输出为 json5 格式）首次出现于 v1.13.0
"jsonc"（与 "json" 相同解析器，但输出为"支持注释的 JSON"）首次出现于 v3.2.0
"json-stringify"（与 "json" 相同解析器，但输出类似 JSON.stringify）首次出现于 v1.13.0
"graphql"（通过 graphql/language）首次出现于 v1.5.0
"markdown"（通过 remark-parse）首次出现于 v1.8.0
"mdx"（通过 remark-parse 和 @mdx-js/mdx）首次出现于 v1.15.0
"html"（通过 angular-html-parser）首次出现于 v1.15.0
"vue"（与 "html" 相同解析器，但额外支持 Vue 特定语法）首次出现于 v1.10.0
"angular"（与 "html" 相同解析器，但通过 angular-estree-parser 支持 Angular 特定语法）首次出现于 v1.15.0
"lwc"（与 "html" 相同解析器，但支持 LWC 无引号模板属性的特定语法）首次出现于 v1.17.0
"mjml"（与 "html" 解析器相同，但额外支持 MJML 特定语法）自 3.6.0 起可用
"yaml"（通过 yaml 和 yaml-unist-parser 实现）自 1.14.0 起可用

Default	CLI Override	API Override
None	`--parser <string>`	`parser: "<string>"`

注意：v1.13.0 之前默认值为 "babylon"。

注意：自定义解析器 API 已在 v3.0.0 移除，请改用插件（迁移指南）。

文件路径

指定用于推断解析器的文件名。

例如以下配置将使用 CSS 解析器：

cat foo | prettier --stdin-filepath foo.css

此选项仅在 CLI 和 API 中有意义，在配置文件中使用不具实际价值。

Default	CLI Override	API Override
None	`--stdin-filepath <string>`	`filepath: "<string>"`

要求编译指示

自 v1.7.0 起可用

Prettier 可限制自身仅格式化包含特殊注释（称为编译指示）的文件。这在逐步迁移大型未格式化代码库时非常有用。

当启用 --require-pragma 时，以下注释作为文件首行内容将触发格式化：

/**
 * @prettier
 */

或者

/**
 * @format
 */

Default	CLI Override	API Override
`false`	`--require-pragma`	`requirePragma: <bool>`

插入编译指示

自 v1.8.0 起可用

Prettier 可在文件顶部插入特殊标记 @format 表明文件已被格式化。与 --require-pragma 配合使用时效果最佳。若文件已有文档块，此选项会添加带 @format 标记的新行。

注意“配合使用”并非“同时使用”。当两个选项同时启用时，--require-pragma 优先级更高，此时 --insert-pragma 将被忽略。该功能旨在支持大型代码库的渐进式迁移：参与迁移的开发者使用 --insert-pragma，而其他成员和自动化工具通过 --require-pragma 仅处理已迁移文件。此设计灵感源于 Facebook 的迁移策略。

Default	CLI Override	API Override
`false`	`--insert-pragma`	`insertPragma: <bool>`

检查忽略编译指示

自 v3.6.0 起可用

当文件顶部包含特殊注释（编译指示）时，Prettier 允许这些文件跳过格式化。

检查这些标记会产生少量格式化开销，因此默认不启用此功能。

启用 --check-ignore-pragma 时，以下注释作为文件首行内容将跳过格式化：

/**
 * @noprettier
 */

或者

/**
 * @noformat
 */

Default	CLI Override	API Override
`false`	`--check-ignore-pragma`	`checkIgnorePragma: <bool>`

散文换行

自 v1.8.2 起可用

默认情况下，Prettier 不会更改 Markdown 文本的换行（因 GitHub 评论等平台使用行敏感渲染器）。若需按打印宽度自动换行，请设为 "always"；如需强制所有散文块单行显示（依赖编辑器软换行），请设为 "never"。

有效选项：

"always" - 超过打印宽度时自动换行
"never" - 取消换行，每段散文显示为单行
"preserve" - 不做处理，保留原文格式。v1.9.0 起可用

Default	CLI Override	API Override
`"preserve"`	`--prose-wrap <always\|never\|preserve>`	`proseWrap: "<always\|never\|preserve>"`

HTML 空白符敏感度

v1.15.0 起可用，Handlebars 支持自 v2.3.0 起

指定 HTML、Vue、Angular 和 Handlebars 的全局空白符敏感度。详见空白符敏感格式化说明。

有效选项：

"css" - 遵循 CSS display 属性的默认值。在 Handlebars 中等同于 strict
"strict" - 所有标签周围的空白符（或缺省）均视为有意义
"ignore" - 所有标签周围的空白符（或缺省）均视为无意义

Default	CLI Override	API Override
`"css"`	`--html-whitespace-sensitivity <css\|strict\|ignore>`	`htmlWhitespaceSensitivity: "<css\|strict\|ignore>"`

Vue 文件 script 和 style 标签缩进

v1.19.0 起可用

是否缩进 Vue 文件中 <script> 和 <style> 标签内的代码

有效选项：

false - 不缩进 Vue 文件中的 script 和 style 标签
true - 缩进 Vue 文件中的 script 和 style 标签

Default	CLI Override	API Override
`false`	`--vue-indent-script-and-style`	`vueIndentScriptAndStyle: <bool>`

行尾结束符

v1.15.0 起可用，v2.0.0 起默认值从 auto 改为 lf

由于历史原因，文本文件存在两种常见的行尾结束符：\n（即 LF，换行符）和 \r\n（即 CRLF，回车符+换行符）。前者在 Linux 和 macOS 中常见，后者在 Windows 中普遍使用。维基百科详细解释了这一现象的原因。

当不同操作系统的开发者在项目中协作时，共享的 git 仓库很容易出现混合行尾结束符。Windows 用户也可能意外地将已提交文件的行尾从 LF 改为 CRLF。这会产生大范围的 git diff，使得文件的逐行历史记录（git blame）难以追溯。

若要确保 git 仓库中 Prettier 覆盖的文件仅包含 Linux 风格的行尾结束符：

确保 Prettier 的 endOfLine 选项设为 lf（v2.0.0 起此为默认值）
配置预提交钩子以运行 Prettier
在 CI 流程中使用 --check 标志运行 Prettier。若使用 Travis CI，需在 .travis.yml 中设置 autocrlf 选项为 input
在仓库的 .gitattributes 文件中添加 * text=auto eol=lf
此变更后，需让 Windows 用户重新克隆仓库，以确保 git 在检出时未将 LF 转为 CRLF

所有现代文本编辑器在各操作系统均能正确显示 \n（LF）行尾。但旧版 Windows 记事本仅支持 \r\n（CRLF），会将这些行显示为单行。

有效选项：

"lf" – 仅使用换行符 (\n)，常见于 Linux/macOS 系统及 git 仓库
"crlf" - 回车换行符 (\r\n)，Windows 系统常用
"cr" - 仅回车符 (\r)，极少使用
"auto" - 保留现有换行符（混合使用时会通过首行后的换行符进行标准化处理）

Default	CLI Override	API Override
`"lf"`	`--end-of-line <lf\|crlf\|cr\|auto>`	`endOfLine: "<lf\|crlf\|cr\|auto>"`

在 .editorconfig 文件中设置 end_of_line 将配置 Prettier 的换行符使用方式，除非被覆盖。

嵌入式语言格式化

首次发布于 v2.1.0

控制 Prettier 是否格式化文件中嵌入的引用代码。

当 Prettier 检测到类似以下情况时：在 JavaScript 的 html 标签模板或 Markdown 代码块等场景中，您将可格式化代码嵌入到其他文件的字符串内，默认会尝试格式化这些代码。

有时此行为可能不符合预期，特别是当您无意将字符串解释为代码时。此选项可在默认行为 (auto) 和完全禁用 (off) 之间切换。

有效选项：

"auto" – 若 Prettier 能自动识别则格式化嵌入式代码。
"off" - 永不自动格式化嵌入式代码。

Default	CLI Override	API Override
`"auto"`	`--embedded-language-formatting=<off\|auto>`	`embeddedLanguageFormatting: "<off\|auto>"`

每行单个属性

首次发布于 v2.6.0

在 HTML、Vue 和 JSX 中强制每行仅保留单个属性。

有效选项：

false - 不强制每行单个属性。
true - 强制每行单个属性。

Default	CLI Override	API Override
`false`	`--single-attribute-per-line`	`singleAttributePerLine: <bool>`

实验性三元表达式​

实验性运算符位置​

行宽​

缩进宽度​

制表符​

分号​

引号​

属性引号​

JSX 引号​

尾随逗号​

括号间距​

对象换行​

括号换行​

[已弃用] JSX 括号​

箭头函数括号​

范围​

解析器​

文件路径​

要求编译指示​

插入编译指示​

检查忽略编译指示​

散文换行​

HTML 空白符敏感度​

Vue 文件 script 和 style 标签缩进​

行尾结束符​

嵌入式语言格式化​

每行单个属性​

实验性三元表达式

实验性运算符位置

行宽

缩进宽度

制表符

分号

引号

属性引号

JSX 引号

尾随逗号

括号间距

对象换行

括号换行

[已弃用] JSX 括号

箭头函数括号

范围

解析器

文件路径

要求编译指示

插入编译指示

检查忽略编译指示

散文换行

HTML 空白符敏感度

Vue 文件 script 和 style 标签缩进

行尾结束符

嵌入式语言格式化

每行单个属性