企业官网建设流程全解析

• 开发工具
• 格式化
• CLI

本文以 Prettier 官方 Options 文档（website/versioned_docs/version-stable/options.md）为主体骨架，系统讲解 Prettier 的全部格式化选项：每个选项的默认值、取值集合、CLI 参数与 API 字段名，并结合当前仓库源码（src/main/core-options.evaluate.js、src/common/common-options.evaluate.js、src/language-js/options.js等）揭示其底层实现。读完本文，你将能够精准地为团队配置.prettierrc、写出正确的prettier --xxx命令行、在 API 中传参，并理解每个选项在 Prettier 内部是如何生效的。

选项的三种配置入口与整体架构

Prettier 提供了「一套语义、三个入口」的选项体系：无论通过配置文件、CLI 命令行还是JavaScript API设置选项，最终都会归一化到同一组内部选项对象上，驱动打印（printer）输出。

官方文档明确建议：如果修改任何选项，推荐通过配置文件来完成，这样 Prettier CLI、编辑器集成以及其他工具链都能感知到你的选项设置。关于 Prettier 对选项数量的克制态度，可阅读选项哲学。

从源码结构看，选项定义分布在三个层面：

• 全局核心选项定义在 src/main/core-options.evaluate.js，例如printWidth、tabWidth、useTabs、semi、parser、endOfLine等，它们对所有语言通用；
• 跨语言公共选项定义在 src/common/common-options.evaluate.js，例如proseWrap、singleAttributePerLine、bracketSameLine、bracketSpacing、objectWrap等；
• 语言专属选项定义在各语言模块的options.js中，例如 src/language-js/options.js 里的arrowParens、jsxBracketSameLine、quoteProps、singleQuote等。

每个选项都带有category（分类）、type（int/boolean/choice/path/string）、default（默认值）、description（描述）等元数据，分类常量定义在 src/main/option-categories.js（Global、Special、Config、Editor、Other、Output、Format 等）。

CLI 侧的参数名由 API 选项名经dashify转换而来（如stdinFilepath→--stdin-filepath），具体转换逻辑见 src/cli/options/get-context-options.js。因此下文每个选项都会同时给出Default / CLI Override / API Override三列。

行宽与缩进：Print Width、Tab Width、Tabs

Print Width（打印宽度）

指定 printer 换行时参考的行长度。

关键认知：printWidth不是硬性上限。它是在告诉 Prettier "你希望行大概多长"，Prettier 会尽量接近该宽度，但实际产出的行可能更短也可能更长。这与 ESLint 的max-len规则有本质区别：max-len规定的是"允许的最大行长度"，而printWidth表达的是"倾向的行长度"。文档还特别提醒，虽然许多代码规范把最大行长设为 100 或 120，但人类写代码时并不追求每行都顶到上限，因此从可读性角度出发，不建议把printWidth设得超过 80。

在源码中，src/main/core-options.evaluate.js 将printWidth定义为int类型、默认80，并给出了推荐范围{ start: 0, end: Number.POSITIVE_INFINITY, step: 1 }。此外，.editorconfig文件中的max_line_length也会映射到printWidth（除非显式覆盖），映射逻辑见 src/config/editorconfig/editorconfig-to-prettier.js：当max_line_length为"off"时等价于Number.POSITIVE_INFINITY，即关闭换行。

如果不希望 Markdown 文本被换行，可以配合下方的 Prose Wrap 选项禁用。

Tab Width（缩进宽度）

指定每一级缩进占用的空格数。

源码定义在 src/main/core-options.evaluate.js，默认2。.editorconfig中的indent_size或tab_width会映射到tabWidth（除非显式覆盖），见 src/config/editorconfig/editorconfig-to-prettier.js：当使用空格缩进且indent_size为正整数时优先取indent_size，否则取tab_width。

Tabs（制表符缩进）

用 Tab 代替空格进行缩进。

源码定义于 src/main/core-options.evaluate.js。.editorconfig中的indent_style会映射到useTabs（除非显式覆盖），见 src/config/editorconfig/editorconfig-to-prettier.js：indent_style: "space"→useTabs: false，indent_style: "tab"或indent_size: "tab"→useTabs: true。

需要特别注意的是：Tab 只用于"缩进"，而对齐（例如三元表达式中的对齐）Prettier 仍然使用空格。这种行为被称为 SmartTabs。

语句与引号风格：Semicolons、Quotes、Quote Props、JSX Quotes

Semicolons（分号）

是否在语句末尾打印分号。

• true：在每条语句末尾都加分号；
• false：仅在那些可能引发 ASI（自动分号插入）失败的行首添加分号。

注意 CLI 开关是取反语义：默认是打印分号，因此命令行要用--no-semi来关闭。选项内部名称为semi，API 传参为semi: false。

Quotes（引号）

使用单引号代替双引号。

两点补充说明：

• JSX 引号不受此选项控制，请使用下方的jsxSingleQuote；
• 引号有自适应逻辑：如果字符串中某种引号数量更多，Prettier 会改用使用更少的引号来包裹字符串。例如"I'm double quoted"保持双引号不变，而"This \"example\" is single quoted"会格式化为'This "example" is single quoted'。

背后的字符串打印逻辑可参考字符串排版理由。引号相关的底层实现位于 src/utilities/get-preferred-quote.js 与 src/utilities/print-string.js。

Quote Props（对象属性引号）

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

• "as-needed"：只在必需时为对象属性加引号；
• "consistent"：只要对象中有一个属性需要引号，就给所有属性加引号；
• "preserve"：尊重输入中对象属性原有的引号使用情况。

一个重要的边界：在 Angular 表达式、TypeScript 和 Flow 中，数字属性名永远不会被去掉引号，因为这些语言中字符串键与数字键的语义有显著区别（这也是 Prettier 对 Vue 数字属性不去引号的原因）。

JSX Quotes（JSX 引号）

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

此选项与singleQuote相互独立：即便singleQuote: false，仍可单独设置jsxSingleQuote: true，反之亦然。

列表与对象排版：Trailing Commas、Bracket Spacing、Object Wrap

Trailing Commas（尾随逗号）

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

• "all"：在一切可能的位置加尾随逗号，包括函数参数与函数调用。这意味着运行该代码的引擎需支持 ES2017（Node.js 8+ 或现代浏览器），或通过 Babel 等做降级编译；同时会在 TypeScript 的类型参数中启用尾随逗号（TypeScript 2.7 起支持）；
• "es5"：仅在 ES5 合法的位置（对象、数组等）加尾随逗号；TypeScript 与 Flow 的类型参数中也会加；
• "none"：不加任何尾随逗号。

Bracket Spacing（花括号空格）

在对象字面量的花括号内侧打印空格。

• true：{ foo: bar }
• false：{foo: bar}

与semi一样，CLI 开关--no-bracket-spacing也是取反语义。该选项定义在公共选项中，见 src/common/common-options.evaluate.js，并被 src/language-js/options.js 等语言模块复用。

Object Wrap（对象换行策略）

配置对象字面量在"可单行容纳"与"跨多行"之间的排版策略。首次可用版本：v3.5.0。

默认情况下，如果对象第一个属性之前存在换行，Prettier 会将其格式化为多行——作者可以利用这一启发式规则来提升可读性，但它也有一些缺点（详见多行对象）。取值含义：

• "preserve"：若左花括号与第一个属性之间存在换行，则保持多行；
• "collapse"：尽可能压缩为单行。

HTML/JSX 标签排版：Bracket Line、废弃的 JSX Brackets、Single Attribute Per Line

Bracket Line（尖括号位置）

把多行 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>

该选项同样定义在公共选项中，见 src/common/common-options.evaluate.js。

[Deprecated] JSX Brackets（已废弃）

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

历史版本中它只控制 JSX 元素的>位置，语义与bracketSameLine相同：

在源码中它被标记为deprecated: "2.4.0"，见 src/language-js/options.js。CLI 侧处理废弃选项时不会将其转发为 API 参数（见 src/cli/options/get-context-options.js）。

Single Attribute Per Line（单属性单行）

在 HTML、Vue 和 JSX 中强制每个属性单独占一行。首次可用版本：v2.6.0。

定义于 src/common/common-options.evaluate.js，并被 src/language-js/options.js 复用。

函数与表达式：Arrow Function Parentheses、Experimental 系列

Arrow Function Parentheses（箭头函数参数括号）

是否在单个箭头函数参数外保留括号。首次可用版本：v1.9.0，默认值在 v2.0.0 从avoid改为always。

• "always"：始终保留括号，例如(x) => x；
• "avoid"：尽可能省略括号，例如x => x。

表面上看avoid更少视觉噪音，但一旦去掉括号，后续添加类型注解、额外参数或默认值都会变得更麻烦。统一保留括号在真实代码库的演进中提供更好的编辑体验，这也是always成为默认值的理由。定义见 src/language-js/options.js。

Experimental Ternaries（实验性三元表达式）

在它成为默认行为之前，提前体验 Prettier 的新型三元表达式排版。

• true：使用 "curious ternaries" 风格，问号跟在条件之后（换行时问号位于新行行首）；
• false：保留默认行为，问号与 consequent 保持在同一行。

Experimental Operator Position（实验性运算符位置）

控制二元表达式换行时运算符的打印位置。

• "start"：二元表达式换行时，运算符打印在新行的行首；
• "end"：默认行为，运算符留在前一行的行尾。

Range（范围格式化）

只格式化文件的某一段。

这两个选项分别指定格式化区间的起始与结束字符偏移（前者包含、后者排除）。实际格式化区间会向外扩展：

• 向后扩展到包含选中语句的第一行的行首；
• 向前扩展到选中语句的末尾。

源码层面，区间计算逻辑位于 src/main/range.js 的calculateRange函数：它先在区间两端收缩空白字符，再借助 AST 的locStart/locEnd找到起始偏移与结束偏移对应的节点，通过findSiblingAncestors找到共同的语句级祖先，最终返回[min(locStart(startNode), locStart(endNode)), max(locEnd(startNode), locEnd(endNode))]。值得注意的是，不同语言对"语句"的判定不同：JavaScript 看节点类型是否以Statement/Declaration结尾，JSON 有一套jsonSourceElements集合，GraphQL 则有一套graphqlSourceElements集合，Vue 会跳过root标签。默认值定义见 src/main/core-options.evaluate.js。

Parser（解析器）与 File Path（文件路径推断）

Parser

指定使用哪个解析器。Prettier 通常会根据输入文件路径自动推断解析器，因此多数情况下无需手动设置。

官方文档说明：babel与flow支持同一套 JavaScript 特性（包括 Flow 类型注解），仅在个别边界情况下有差异，遇到时可互换尝试；typescript与babel-ts的情况类似——babel-ts可能支持 TypeScript 尚未支持的 JS 提案特性，但对非法代码更不宽容，也未经typescript解析器那般久经考验。

有效取值与对应实现（括号内为该解析器在当前仓库中的实现文件）：

• "babel"（基于 Babel parser）——实现于 src/language-js/parse/babel.js；v1.16.0 前名为"babylon"
• "babel-flow"——同"babel"但显式开启 Flow 解析以避免歧义，v1.16.0 起可用
• "babel-ts"——类似"typescript"但使用 Babel 的 TypeScript 插件，v2.0.0 起可用
• "flow"（基于 flow-parser）——实现于 src/language-js/parse/flow.js
• "typescript"（基于 @typescript-eslint/typescript-estree）——实现于 src/language-js/parse/typescript.js，v1.4.0 起可用
• "espree"（基于 espree）——实现于 src/language-js/parse/espree.js，v2.2.0 起可用
• "meriyah"（基于 meriyah）——实现于 src/language-js/parse/meriyah.js，v2.2.0 起可用
• "acorn"（基于 acorn）——实现于 src/language-js/parse/acorn.js，v2.6.0 起可用
• "css"（基于 postcss）、"scss"（基于 postcss-scss）、"less"（基于 postcss-less）——统一由 src/language-css/parser-postcss.js 提供，v1.7.1 起可用
• "json"（基于 Babel parser 的parseExpression）、"json5"（输出 JSON5 风格）、"jsonc"（"JSON with Comments"，v3.2.0 起）、"json-stringify"（解析宽松度类似JSON.parse()，空白风格类似JSON.stringify()）——实现于 src/language-json/parse
• "graphql"（基于 graphql/language）——实现于 src/language-graphql/parser-graphql.js，v1.5.0 起可用
• "markdown"（基于 micromark）——实现于 src/language-markdown/parsers.js，v1.8.0 起可用
• "mdx"（基于 remark-parse 与 remark-mdx），v1.15.0 起可用
• "html"（基于 angular-html-parser）、"vue"（同"html"但支持 Vue 专属语法，v1.10.0 起）、"angular"（额外支持 Angular 专属语法，v1.15.0 起）、"lwc"（支持未加引号的模板属性，v1.17.0 起）、"mjml"（v3.6.0 起）——统一入口见 src/language-html/parse/parsers.js
• "glimmer"（Ember / Handlebars）——实现于 src/language-handlebars/parser-glimmer.js，v1.10.0 起可用
• "yaml"（基于 yaml 与 yaml-unist-parser）——实现于 src/language-yaml/parser-yaml.js，v1.14.0 起可用

历史注记：默认值在 v1.13.0 前是"babylon"；v3.0.0 起 Custom parser API 已被移除，请改用插件机制（迁移方式见 docs/api.md 的 Custom parser API 相关章节）。

上述 parser 名称在 src/main/core-options.evaluate.js 中以choice类型列出，且带有exception: (value) => typeof value === "string" || typeof value === "function"的豁免，以兼容插件注册的自定义解析器。

File Path（文件路径）

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

典型用法：通过管道向 Prettier 喂入无扩展名的内容时，用--stdin-filepath告诉它按什么语言解析。例如下面这条命令会让 Prettier 使用 CSS 解析器：

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

该选项只对 CLI 与 API 有意义，放在配置文件中没有意义。解析器推断的完整优先级链见 src/utilities/infer-parser.js 的inferParser函数：

1. 按fileInfo.language语言名匹配；
2. 按physicalFile的文件名/扩展名匹配；
3. 按file的文件名/扩展名匹配；
4. 调用语言插件的isSupported钩子判定；
5. 最后（仅 Node 环境）读取无扩展名文件 shebang 中的 interpreter 来推断。

CLI 参数名--stdin-filepath由cliName显式指定（见 src/main/core-options.evaluate.js），因为默认的 dashify 转换会得到--filepath。

Pragma 标记：Require Pragma、Insert Pragma、Check Ignore Pragma

Pragma 是位于文件头部特殊 docblock 注释中的标记，用于控制 Prettier 是否格式化某个文件。三种 pragma 相关选项配合使用，可以平滑地在大规模历史代码库中渐进式落地 Prettier。

Require Pragma（要求标记）

首次可用版本：v1.7.0。开启后，Prettier 只格式化文件顶部包含特殊注释（pragma）的文件。

以下两种文件头注释之一会使文件在开启--require-pragma时被格式化：

/** * @prettier */

或

/** * @format */

Insert Pragma（插入标记）

首次可用版本：v1.8.0。Prettier 会在文件顶部插入@format标记，声明该文件已经过 Prettier 格式化。如果文件顶部已有 docblock，则会在其中追加一行@format。

注意"配合使用"不等于"同时使用"：当两个选项同时开启时，--require-pragma拥有更高优先级，--insert-pragma会被忽略。推荐的分工是：参与迁移的开发者使用--insert-pragma逐个标记文件，而团队其余成员与自动化工具使用--require-pragma只处理已完成迁移的文件。该策略源自 Facebook 的迁移实践。

Check Ignore Pragma（检查忽略标记）

首次可用版本：v3.6.0。允许单个文件通过头部特殊注释选择退出格式化。

检测这些标记会带来少量前置开销，因此默认关闭。开启后，含以下头部注释之一的文件不会被格式化：

/** * @noprettier */

或

/** * @noformat */

源码实现：所有 pragma 相关的正则都集中在 src/utilities/pragma/pragma.evaluate.js：

• 合法标记集合由FORMAT_PRAGMAS = ["format", "prettier"]与FORMAT_IGNORE_PRAGMAS = ["noformat", "noprettier"]定义；
• 针对不同语言注释语法准备了多套正则：YAML 的# @format行注释、GraphQL 的# @format、HTML 的<!-- @format -->、Markdown 的 HTML 注释 / JSX 注释 / 多行注释形式；
• 选项定义见 src/main/core-options.evaluate.js（checkIgnorePragma）、#L100-L106（insertPragma）、#L183-L190（requirePragma）。

标记语言专用选项：Prose Wrap、HTML Whitespace Sensitivity、Vue 缩进

Prose Wrap（散文换行）

控制 Markdown 文本（prose）的换行行为。首次可用版本：v1.8.2。

默认不改动 Markdown 文本的换行，因为部分服务（如 GitHub 评论、BitBucket）使用对换行敏感的渲染器。

• "always"：将散文按printWidth换行；
• "never"：把每个散文段落放在单独一行，依靠编辑器/查看器的软换行；
• "preserve"：保持原有换行不变（v1.9.0 起可用）。

对给定段落：

The quick brown fox jumps over the lazy dog.

在printWidth: 20下三种取值的结果分别为：

• "always"

  The quick brown fox jumps over the lazy dog.

• "never"

  The quick brown fox jumps over the lazy dog.

• "preserve"

  The quick brown fox jumps over the lazy dog.

HTML Whitespace Sensitivity（HTML 空白敏感度）

指定 HTML、Vue、Angular 与 Handlebars 的全局空白敏感度。首次可用版本：v1.15.0；对 Handlebars 自 v2.3.0 起可用。

• "css"：尊重 CSSdisplay属性的默认值（对 Handlebars 按strict处理）；
• "strict"：所有标签周围的空白（或缺失）都被视为有意义；
• "ignore"：所有标签周围的空白（或缺失）都被视为无意义。

Vue 文件中 script 与 style 标签的缩进

是否缩进 Vue 文件中<script>与<style>标签内部的代码。首次可用版本：v1.19.0。

• false：不缩进 Vue 文件的 script 和 style 标签；
• true：缩进 Vue 文件的 script 和 style 标签。

跨平台与嵌入式代码：End of Line、Embedded Language Formatting

End of Line（行尾符）

控制换行符类型。首次可用版本：v1.15.0，默认值在 v2.0.0 从auto改为lf。

历史原因导致文本文件存在两种常见行尾：\n（LF，Linux/macOS 及 git 仓库内常见）与\r\n（CRLF，Windows 常见）。跨操作系统协作时很容易在共享仓库中混入两种行尾，Windows 用户也可能无意间把已提交文件的 LF 改成 CRLF，从而产生巨大的git diff，让git blame难以阅读。

各取值含义：

• "lf"：仅 Line Feed（\n）；
• "crlf"：Carriage Return + Line Feed（\r\n）；
• "cr"：仅 Carriage Return（\r），极少使用；
• "auto"：维持现有行尾（同一文件内混用时，按首行之后实际使用的行尾归一化）。

如果你希望整个 git 仓库中被 Prettier 覆盖的文件只包含 Linux 风格行尾，文档给出了四步操作流程：

1. 确保endOfLine为lf（v2.0.0 起的默认值）；
2. 配置预提交钩子运行 Prettier；
3. 在 CI 流水线中使用--check标志运行 Prettier；
4. 在仓库的.gitattributes中加入* text=auto eol=lf（可能需要让 Windows 用户重新 clone 仓库，避免 git 在 checkout 时把 LF 转成 CRLF）。

所有现代操作系统上的现代编辑器都能正确显示 LF；但旧版 Windows 记事本只会处理 CRLF，会把 LF 行全部挤成一行。

源码层面，endOfLine的四个取值定义于 src/main/core-options.evaluate.js，换行符的实际处理逻辑位于 src/common/end-of-line.js。.editorconfig中的end_of_line也会映射到此选项（仅接受lf/crlf/cr三种值），见 src/config/editorconfig/editorconfig-to-prettier.js。

Embedded Language Formatting（嵌入式语言格式化）

控制是否格式化文件中嵌入的引用代码。首次可用版本：v2.1.0。

当 Prettier 识别出字符串里嵌入了它能够格式化的代码时——例如 JavaScript 中以html作为标签的模板字符串，或 Markdown 中的代码块——默认会尝试格式化这些内嵌代码。但如果字符串并非有意写成的代码，这种自动行为反而可能不合预期。取值：

• "auto"：若 Prettier 能自动识别嵌入代码，则进行格式化；
• "off"：永不自动格式化嵌入代码。

定义见 src/main/core-options.evaluate.js。嵌入格式化在各语言模块中实现，例如 src/language-js/embed（CSS、GraphQL、HTML、Markdown 嵌入）、src/language-html/embed 等。

组合实战：用一份配置管理团队格式规范

结合以上全部选项，一份典型的团队级.prettierrc（JSON 格式，完整配置方式见配置文件指南）可以是：

{ "printWidth": 80, "tabWidth": 2, "useTabs": false, "semi": true, "singleQuote": true, "quoteProps": "as-needed", "jsxSingleQuote": false, "trailingComma": "all", "bracketSpacing": true, "objectWrap": "preserve", "bracketSameLine": false, "arrowParens": "always", "proseWrap": "preserve", "htmlWhitespaceSensitivity": "css", "vueIndentScriptAndStyle": false, "endOfLine": "lf", "embeddedLanguageFormatting": "auto", "singleAttributePerLine": false }

优先级方面需要记住两个要点：

1. CLI 参数 > 配置文件 > 默认值：命令行中显式传入的选项会覆盖配置文件中的同名设置；
2. EditorConfig 映射的优先级低于显式选项：.editorconfig中的max_line_length、indent_size/tab_width、indent_style、end_of_line（以及未文档化的quote_type）会映射为 Prettier 选项，但一旦配置文件中显式指定了对应选项，以显式配置为准。完整映射规则见 src/config/editorconfig/editorconfig-to-prettier.js。

所有选项的默认值与元数据都可以在源码中一站式查询：全局选项见 src/main/core-options.evaluate.js，公共选项见 src/common/common-options.evaluate.js，各语言专属选项见src/language-*/options.js。官方稳定版文档（本文对应的原始出处）位于 website/versioned_docs/version-stable/options.md，与仓库根目录下的 docs/options.md 内容一致，读者可以对照研读。

• 开发工具
• 格式化
• CLI