2026/9/18 16:45:16
FEATURED · 精选文章 
Prettier 格式化选项全解从 printWidth 到 Pragma 的完整配置指南与源码实现剖析【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettierPrettier 作为一套有主见的代码格式化工具通过一组精心设计的格式化选项format options控制换行、缩进、引号、分号等核心行为。本文基于 Prettier 仓库的 Options 文档完整梳理每个选项的默认值、CLI 与 API 写法、生效范围并结合src/main、src/language-js等目录下的源码实现剖析选项是如何被定义、校验并参与格式化流程的帮助你既能正确配置也能理解其底层机制。选项总览与设计取向Prettier 自带一小撮格式化选项a handful of format options这一克制的设计背后有其哲学考量详见 Option Philosophy。官方建议如果你需要修改任何选项推荐通过 配置文件 完成这样 Prettier CLI、编辑器集成 以及其他工具链都能感知你使用的选项而不是依赖每次调用时的临时参数。从源码结构看Prettier 的选项定义分散在三层全局核心选项src/main/core-options.evaluate.js 定义了printWidth、tabWidth、useTabs、endOfLine、parser、filepath、plugins、requirePragma、insertPragma、rangeStart/rangeEnd等跨语言选项通用格式选项src/common/common-options.evaluate.js 定义了bracketSpacing、singleQuote、proseWrap、objectWrap、bracketSameLine、singleAttributePerLine等Common类别选项语言特定选项如 src/language-js/options.js 为 JavaScript 家族定义了semi、quoteProps、trailingComma、arrowParens、experimentalTernaries、experimentalOperatorPosition等并直接复用 common 层中的同名字段bracketSameLine、objectWrap等通过commonOptions.xxx引用注入。每个选项的元信息类型、默认值、取值 choices、分类、废弃标记以统一的OptionInfo结构声明见 src/main/core-options.evaluate.js 中的 JSDoc 类型注释--help输出与 API 校验都基于这套声明。CLI 侧则另有 src/cli/cli-options.evaluate.js 专门声明--check、--write、--config、configPrecedence等仅 CLI 存在的选项。JavaScript 与 TypeScript 选项experimentalTernaries实验性三元表达式格式允许在好奇式三元表达式curious ternaries成为默认行为之前提前试用对应 ternary 格式化改造。有效取值true— 使用好奇式三元问号跟随条件之后换行const x condition ? yes : no;false— 保持默认行为问号与 then 分支位于同一行const x condition ? yes : no;默认值CLI 写法API 写法false--experimental-ternariesexperimentalTernaries: bool源码中该选项声明于 src/language-js/options.js输出逻辑同时存在新旧两套实现src/language-js/print/ternary.js中通过printTernaryOld来自ternary-old.js保留了旧版折行策略便于在实验开关关闭时维持既有输出。experimentalOperatorPosition二元运算符位置有效取值start— 二元表达式换行时运算符打印在新行开头end— 默认行为运算符留在上一行末尾。默认值CLI 写法API 写法end--experimental-operator-position start\|endexperimentalOperatorPosition: \start\|end该选项同样定义在 src/language-js/options.js其choices与文档取值一一对应。printWidth建议行宽指定打印器尝试换行的行长度。可读性提示官方不建议使用超过 80 个字符的行宽。许多代码风格指南把最大行宽定在 100 或 120但人类手写代码时并不会刻意让每行都顶满实践中平均行长往往远低于上限。Prettier 的printWidth并非硬性上限而是告诉 Prettier大致希望行有多长——它既会产出更短的也会产出更长的行总体趋向该值。切记不要把它当成 ESLint 的max-len来用max-len只声明最大允许长度而printWidth声明的是普遍偏好的长度。默认值CLI 写法API 写法80--print-width intprintWidth: int在 .editorconfig 中设置max_line_length会配置 Prettier 的行宽除非被更高优先级覆盖。若在格式化 Markdown 时不想换行可将 proseWrap 设为preserve以外的取值来禁用。从源码看printWidth在 src/main/core-options.evaluate.js 中声明默认值80推荐取值范围{ start: 0, end: Infinity, step: 1 }而 .editorconfig 的映射实现里还有一个文档未强调的细节max_line_length off会被转换为printWidth Infinity见 editorconfig-to-prettier.js即彻底关闭行宽约束。tabWidth每级缩进的空白数默认值CLI 写法API 写法2--tab-width inttabWidth: int在.editorconfig中设置indent_size或tab_width会配置 Prettier 的 tab 宽度除非被覆盖。源码映射规则在 editorconfig-to-prettier.js当useTabs为false且indent_size是正整数时优先取indent_size否则回退到tab_width。useTabs使用 Tab 缩进用 Tab 而非空格缩进行。默认值CLI 写法API 写法false--use-tabsuseTabs: bool在.editorconfig中设置indent_style会配置 Prettier 的 Tab 使用除非被覆盖。注意Tab 仅用于缩进Prettier 仍用空格对齐例如三元表达式中的对齐这种行为即编辑器中熟知的 SmartTabs。源码中useTabs的映射见 editorconfig-to-prettier.jsindent_style space置为falsetab或indent_size tab置为true。semi分号在语句末尾打印分号。有效取值true— 每条语句末尾加分号false— 仅在行首可能引发 ASI自动分号插入失败的地方加分号。默认值CLI 写法API 写法true--no-semisemi: bool源码声明见 src/language-js/options.js其oppositeDescription明确说明禁用后的兜底行为。实际的 ASI 兜底输出逻辑位于 src/language-js/semicolon/semicolon.js。singleQuote引号风格使用单引号代替双引号。注意事项JSX 中的引号不受此选项影响见 jsxSingleQuote当字符串中某种引号出现次数超过另一种时Prettier 会采用出现较少的那种引号作为字符串定界符——例如Im double quoted保持双引号而This \example\ is single quoted会被格式化为This example is single quoted。更多动机可参考 strings 设计说明。默认值CLI 写法API 写法false--single-quotesingleQuote: bool补充一个源码细节.editorconfig 的quote_type single|double也会映射到singleQuote该功能在 editorconfig-to-prettier.js 的注释中被标注为Undocumented feature属于非正式支持能力使用它需要知晓这一前提。quoteProps对象属性的引号策略改变对象中属性名的引号使用方式。有效取值as-needed— 仅在必需时给属性加引号consistent— 若对象中任一属性需要引号则给所有属性加引号preserve— 尊重输入中属性引号的原始用法。默认值CLI 写法API 写法as-needed--quote-props as-needed\|consistent\|preservequoteProps: \as-needed\|consistent\|preserve注意Prettier 在 Angular 表达式、TypeScript 和 Flow 中永远不会去掉数字形属性名的引号因为这些语言里字符串键与数字键的区分具有语义差异对 Vue 同理不会去除数字属性引号。jsxSingleQuoteJSX 引号在 JSX 中使用单引号代替双引号。默认值CLI 写法API 写法false--jsx-single-quotejsxSingleQuote: booltrailingComma尾随逗号默认值在 v3.0.0 中从es5变为all在可打印尾随逗号的多行逗号分隔结构中尽可能打印尾随逗号例如单行数组永远不会加尾随逗号。有效取值all— 尽可能全部加上包括函数参数与调用。以这种格式输出的 JavaScript 代码需要支持 ES2017 的引擎Node.js 8 或现代浏览器或降级编译支持同时为 TypeScript 2.7 的类型参数启用尾随逗号es5— 仅在 ES5 合法的场合加对象、数组等以及 TypeScript 和 Flow 的类型参数none— 不加尾随逗号。默认值CLI 写法API 写法all--trailing-comma all\|es5\|nonetrailingComma: \all\|es5\|none源码中该选项的默认值all可见于 src/language-js/options.js与 v3.0.0 起的行为一致。bracketSpacing花括号空格在对象字面量的花括号内打印空格。有效取值true— 例如{ foo: bar }false— 例如{foo: bar}。默认值CLI 写法API 写法true--no-bracket-spacingbracketSpacing: boolobjectWrap对象换行策略自 v3.5.0 起可用配置当对象字面量既可放一行也可拆多行时 Prettier 的换行方式。默认情况下若第一个属性之前存在换行Prettier 会把对象格式化为多行这一启发式由作者用于改善上下文可读性但也存在局限参见 Multi-line objects 设计说明。有效取值preserve— 若开括号与第一个属性之间有换行则保持多行collapse— 尽量收敛到单行。默认值CLI 写法API 写法preserve--object-wrap preserve\|collapseobjectWrap: \preserve\|collapse该选项属于 Common 类别声明于 src/common/common-options.evaluate.js并被 JS 语言层复用。arrowParens箭头函数参数括号自 v1.9.0 可用默认值在 v2.0.0 中从avoid变为always是否为单独一个的箭头函数参数包裹括号。有效取值always— 始终包含括号。例如(x) xavoid— 可能时省略括号。例如x x。默认值CLI 写法API 写法always--arrow-parens always\|avoidarrowParens: \always\|avoid乍看之下避免括号似乎视觉噪声更小但当 Prettier 移除括号后添加类型注解、追加参数或默认值等其他改动都变得更困难。在真实代码库中一致使用括号带来更好的开发体验这也是默认值的由来。HTML / Vue / Angular / JSX 选项bracketSameLine多行元素的位置把多行 HTMLHTML、JSX、Vue、Angular元素的放在最后一行末尾而不是单独放在下一行自闭合元素除外。有效取值true— 示例button classNameprettier-class idprettier-id onClick{this.handleClick} Click Here /buttonfalse— 示例button classNameprettier-class idprettier-id onClick{this.handleClick} Click Here /button默认值CLI 写法API 写法false--bracket-same-linebracketSameLine: bool[已废弃] jsxBracketSameLineJSX 括号该选项已在 v2.4.0 废弃请改用--bracket-same-line。把多行 JSX 元素的放在最后一行末尾自闭合元素除外。默认值CLI 写法API 写法false--jsx-bracket-same-linejsxBracketSameLine: bool源码中该选项带有deprecated: 2.4.0标记见 src/language-js/options.jsCLI 的--help会据此提示替代项旧配置传入时会被重定向处理。htmlWhitespaceSensitivityHTML 空白敏感度自 v1.15.0 可用Handlebars 自 2.3.0 可用指定 HTML、Vue、Angular 与 Handlebars 的全局空白敏感度详见 Prettier 官方博客中关于 whitespace-sensitive formatting 的说明见仓库博客文章 2018-11-07-1.15.0.md。有效取值css— 遵循 CSSdisplay属性的默认值来判断空白是否敏感对 Handlebars 按strict处理strict— 所有标签周围的空白或缺失都视为有意义ignore— 所有标签周围的空白都视为无意义。默认值CLI 写法API 写法css--html-whitespace-sensitivity css\|strict\|ignorehtmlWhitespaceSensitivity: \css\|strict\|ignorevueIndentScriptAndStyleVue script/style 缩进自 v1.19.0 可用是否缩进 Vue 文件中script与style标签内的代码。有效取值false— 不缩进true— 缩进。默认值CLI 写法API 写法false--vue-indent-script-and-stylevueIndentScriptAndStyle: boolsingleAttributePerLine单属性单行自 v2.6.0 可用在 HTML、Vue 与 JSX 中强制每个属性独占一行。有效取值false— 不强制true— 强制。默认值CLI 写法API 写法false--single-attribute-per-linesingleAttributePerLine: boolParser、File Path 与 Range定位格式化目标parser指定解析器指定使用哪个 parser。Prettier 会根据输入文件路径自动推断 parser通常无需修改此设置。babel与flow两个 parser 支持相同的 JavaScript 特性集包括 Flow 类型注解少数边缘情况可能表现不同——遇到时可尝试用flow替代babel。typescript与babel-ts的关系类似babel-ts可能支持 TypeScript 尚未支持的 JS 提案特性但对非法代码更不宽容且实战检验不如typescriptparser 充分。有效取值babel基于 babel/parserv1.16.0 前名为babylonbabel-flow等同babel但显式启用 Flow 解析以避免歧义自 v1.16.0 可用babel-ts类似typescript但使用 Babel 及其 TypeScript 插件自 v2.0.0 可用flow基于 flow-parsertypescript基于 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 可用json5parser 与json相同但按 json5 输出自 v1.13.0 可用jsoncparser 与json相同但按带注释 JSON输出自 v3.2.0 可用json-stringify解析行为类似JSON.parse()但更宽松空白风格类似JSON.stringify()自 v1.13.0 可用graphql基于 graphql/language自 v1.5.0 可用markdown基于 micromark自 v1.8.0 可用mdx基于 remark-parse 与 remark-mdx自 v1.15.0 可用html基于 angular-html-parser自 1.15.0 可用vueparser 与html相同但额外格式化 vue 专属语法自 1.10.0 可用angularparser 与html相同但通过 angular-estree-parser 额外格式化 angular 专属语法自 1.15.0 可用lwcparser 与html相同但额外格式化 LWC 非引号模板属性语法自 1.17.0 可用mjmlparser 与html相同但额外格式化 MJML 专属语法自 3.6.0 可用glimmerEmber / Handlebars基于 glimmer/syntax自 1.10.0 可用yaml基于 yaml 与 yaml-unist-parser自 1.14.0 可用默认值CLI 写法API 写法无--parser stringparser: string注v1.13.0 之前默认值为babylon。注Custom parser API 已在 v3.0.0 移除请改用 插件迁移方式见 API 文档。源码中 parser 的合法取值清单直接硬编码在 src/main/core-options.evaluate.js 的choices字段中flow、babel、babel-flow、babel-ts、typescript、acorn、espree、meriyah、css、less、scss、json、json5、jsonc、json-stringify、graphql、markdown、mdx、vue、yaml、glimmer、html、angular、lwc、mjml内置各语言 parser 由 src/plugins/ 目录下的插件模块如 babel.js、typescript.js、postcss.js 等注册。filepath推断 parser 的文件名指定用于推断 parser 的文件名。例如以下命令会选用 CSS parsercat foo | prettier --stdin-filepath foo.css该选项只在 CLI 与 API 中有效写入配置文件没有意义。默认值CLI 写法API 写法无--stdin-filepath stringfilepath: string在核心选项中它声明为type: path、category: CATEGORY_SPECIAL且cliName被显式重命名为stdin-filepath见 src/main/core-options.evaluate.js这正是 API 字段名与 CLI 旗标不一致的原因。rangeStart / rangeEnd只格式化文件片段默认值CLI 写法API 写法0--range-start intrangeStart: intInfinity--range-end intrangeEnd: int这两个选项可以按字符偏移量格式化从起点含到终点不含的一段代码。范围会扩展向后扩展到包含所选语句的第一行的行首向前扩展到所选语句的末尾。从源码看范围格式化在 src/main/core.js 中实现calculateRange基于 AST 计算[rangeStart, rangeEnd]text.slice(rangeStart, rangeEnd)切出片段独立格式化随后再把格式化结果拼回原文text.slice(0, rangeStart) rangeTrimmed text.slice(rangeEnd)并正确处理缩进与cursorOffset的偏移换算。编辑器在仅格式化选区时正是依赖这一机制。Pragma 系列渐进式接入 PrettierrequirePragma要求 prettier / format 标记自 v1.7.0 可用Prettier 可以限制为只格式化文件顶部包含特殊注释pragma的文件这对把大型未格式化代码库逐步迁移到 Prettier 非常有用。当提供--require-pragma时以下面任一项作为首个注释的文件会被格式化/** * prettier */或/** * format */默认值CLI 写法API 写法false--require-pragmarequirePragma: bool各语言的 pragma 注释识别由语言插件实现例如 JS 侧的 src/language-js/pragma.js通用工具见 src/utilities/pragma/。insertPragma自动插入 format 标记自 v1.8.0 可用Prettier 可以在文件顶部插入特殊的format标记表明该文件已经过 Prettier 格式化。与--require-pragma配合使用效果良好若文件顶部已存在 docblock则会在其内新增一行插入format标记。注意配合使用并非同时使用两者同时给出时--require-pragma优先--insert-pragma被忽略。设计意图是在大代码库的渐进式接入过程中参与迁移的开发者使用--insert-pragma而团队其余成员与自动化工具使用--require-pragma只处理已迁移的文件。该特性受 Facebook 的 Prettier 接入策略启发见 1.3.0 发布博客。默认值CLI 写法API 写法false--insert-pragmainsertPragma: boolcheckIgnorePragma允许单文件豁免自 v3.6.0 可用Prettier 可以允许单个文件在顶部包含特殊 pragma 注释时主动退出格式化。由于检查这些标记在格式化时会带来微小的前置开销该选项默认关闭。提供--check-ignore-pragma时以下面任一项作为首个注释的文件不会被格式化/** * noprettier */或/** * noformat */默认值CLI 写法API 写法false--check-ignore-pragmacheckIgnorePragma: bool源码声明见 src/main/core-options.evaluate.js。Markdown 与多语言通用选项proseWrap正文换行策略自 v1.8.2 可用由于部分服务如 GitHub 评论、BitBucket使用对换行敏感的渲染器Prettier 默认不改变 Markdown 正文的换行。要按行宽换行请设为always若希望所有正文块强制单行、依赖编辑器/查看器的软换行可用never。有效取值always— 按printWidth换行正文never— 每个正文块放一行preserve— 保持既有换行不变。自 v1.9.0 可用例如给定这样的 Markdown 段落The quick brown fox jumps over the lazy dog.在printWidth: 20下Prettier 的输出为alwaysThe quick brown fox jumps over the lazy dog.neverThe quick brown fox jumps over the lazy dog.preserveThe quick brown fox jumps over the lazy dog.默认值CLI 写法API 写法preserve--prose-wrap always\|never\|preserveproseWrap: \always\|never\|preserveendOfLine换行符自 v1.15.0 可用默认值在 v2.0.0 中从auto变为lf出于历史原因文本文件中存在两种常见换行符\nLFLine Feed与\r\nCRLFCarriage Return Line Feed。前者通行于 Linux 与 macOS后者盛行于 Windows。当来自不同操作系统的人协作时共享的 git 仓库很容易出现混合换行符Windows 用户还可能在提交过的文件中误把换行符从LF改成CRLF产生巨大的git diff也让git blame的行级历史更难阅读。若希望 Prettier 覆盖的 git 仓库中只保留 Linux 风格换行符确保 Prettier 的endOfLine选项设为lf自 v2.0.0 起的默认值配置 pre-commit 钩子 运行 Prettier在 CI 流水线中配置 Prettier 的--check检查在仓库的.gitattributes中添加* textauto eollf。此变更后可能需要要求 Windows 用户重新 clone 仓库以确保 git 没有在 checkout 时把LF转换为CRLF。所有现代编辑器在任意操作系统下都能正确显示\nLF换行符但 Windows 的旧版 Notepad 只能处理\r\n会把此类文件视觉上压成一行。有效取值lf— 仅 Line Feed\n通行于 Linux、macOS 以及 git 仓库内部crlf— Carriage Return Line Feed\r\n通行于 Windowscr— 仅 Carriage Return\r极少使用auto— 保持现有换行符文件内混合取值会按首行之后的实际用法归一化。默认值CLI 写法API 写法lf--end-of-line lf\|crlf\|cr\|autoendOfLine: \lf\|crlf\|cr\|auto在.editorconfig中设置end_of_line会配置 Prettier 的换行符使用除非被覆盖映射逻辑见 editorconfig-to-prettier.js。embeddedLanguageFormatting内嵌语言格式化自 v2.1.0 可用控制 Prettier 是否格式化文件中以引号包裹的内嵌代码。当 Prettier 识别出你在另一个文件的字符串里放了一段它知道如何格式化的代码——例如 JavaScript 中标签名为html的 tagged template或 Markdown 中的代码块——默认会尝试格式化它。当不希望字符串被当作代码解释时这个选项可以让你在默认行为auto与完全禁用off之间切换。有效取值auto— 当 Prettier 能自动识别内嵌代码时对其进行格式化off— 从不自动格式化内嵌代码。默认值CLI 写法API 写法auto--embedded-language-formattingoff\|autoembeddedLanguageFormatting: \off\|auto从源码结构看内嵌格式化的入口在 src/main/multiparser.js例如其中会清理rangeStart等与片段格式化冲突的选项各语言插件通过embed机制如 src/language-html/embed.js声明哪些字符串位置应交给哪个 parser 二次格式化。选项在 CLI 与配置文件中如何协同每个选项都给出了 CLI 与 API 两种写法当二者与配置文件同时出现时评估顺序由 CLI 的--config-precedence决定可选值见 src/cli/cli-options.evaluate.jscli-override默认— CLI 选项优先于配置文件file-override— 配置文件优先于 CLI 选项prefer-file— 找到配置文件则求值它并忽略其他 CLI 选项找不到则 CLI 选项正常生效。配合--config显式指定.prettierrc、package.json或prettier.config.js与--editorconfig默认开启控制是否解析.editorconfig可以在大型项目中精确控制谁说了算。小结Prettier 的选项体系小而稳定全局选项printWidth、tabWidth、useTabs、endOfLine、parser等定义于src/main/core-options.evaluate.js语言选项semi、trailingComma、quoteProps、arrowParens、experimentalTernaries、experimentalOperatorPosition等定义于各src/language-*/options.jsCommon 选项位于src/common/common-options.evaluate.js修改选项请优先写入配置文件或.editorconfig其indent_style、indent_size/tab_width、max_line_length、end_of_line、quote_type均有源码级映射保持 CLI、编辑器与 CI 的行为一致需要渐进式接入大代码库时组合使用--require-pragma--insert-pragma需要单文件豁免时启用 v3.6.0 的--check-ignore-pragma编辑器选区格式化、stdin 场景分别依赖rangeStart/rangeEnd与filepath--stdin-filepath二者均为 Special 类别选项不应写入配置文件遇到废弃选项如jsxBracketSameLine时以--help的废弃提示与本文对应的替代项--bracket-same-line为准。【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Prettier 格式化选项全解：从 printWidth 到 Pragma 的完整配置指南与源码实现剖析
Prettier 格式化选项全解从 printWidth 到 Pragma 的完整配置指南与源码实现剖析【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettierPrettier 作为一套有主见的代码格式化工具通过一组精心设计的格式化选项format options控制换行、缩进、引号、分号等核心行为。本文基于 Prettier 仓库的 Options 文档完整梳理每个选项的默认值、CLI 与 API 写法、生效范围并结合src/main、src/language-js等目录下的源码实现剖析选项是如何被定义、校验并参与格式化流程的帮助你既能正确配置也能理解其底层机制。选项总览与设计取向Prettier 自带一小撮格式化选项a handful of format options这一克制的设计背后有其哲学考量详见 Option Philosophy。官方建议如果你需要修改任何选项推荐通过 配置文件 完成这样 Prettier CLI、编辑器集成 以及其他工具链都能感知你使用的选项而不是依赖每次调用时的临时参数。从源码结构看Prettier 的选项定义分散在三层全局核心选项src/main/core-options.evaluate.js 定义了printWidth、tabWidth、useTabs、endOfLine、parser、filepath、plugins、requirePragma、insertPragma、rangeStart/rangeEnd等跨语言选项通用格式选项src/common/common-options.evaluate.js 定义了bracketSpacing、singleQuote、proseWrap、objectWrap、bracketSameLine、singleAttributePerLine等Common类别选项语言特定选项如 src/language-js/options.js 为 JavaScript 家族定义了semi、quoteProps、trailingComma、arrowParens、experimentalTernaries、experimentalOperatorPosition等并直接复用 common 层中的同名字段bracketSameLine、objectWrap等通过commonOptions.xxx引用注入。每个选项的元信息类型、默认值、取值 choices、分类、废弃标记以统一的OptionInfo结构声明见 src/main/core-options.evaluate.js 中的 JSDoc 类型注释--help输出与 API 校验都基于这套声明。CLI 侧则另有 src/cli/cli-options.evaluate.js 专门声明--check、--write、--config、configPrecedence等仅 CLI 存在的选项。JavaScript 与 TypeScript 选项experimentalTernaries实验性三元表达式格式允许在好奇式三元表达式curious ternaries成为默认行为之前提前试用对应 ternary 格式化改造。有效取值true— 使用好奇式三元问号跟随条件之后换行const x condition ? yes : no;false— 保持默认行为问号与 then 分支位于同一行const x condition ? yes : no;默认值CLI 写法API 写法false--experimental-ternariesexperimentalTernaries: bool源码中该选项声明于 src/language-js/options.js输出逻辑同时存在新旧两套实现src/language-js/print/ternary.js中通过printTernaryOld来自ternary-old.js保留了旧版折行策略便于在实验开关关闭时维持既有输出。experimentalOperatorPosition二元运算符位置有效取值start— 二元表达式换行时运算符打印在新行开头end— 默认行为运算符留在上一行末尾。默认值CLI 写法API 写法end--experimental-operator-position start\|endexperimentalOperatorPosition: \start\|end该选项同样定义在 src/language-js/options.js其choices与文档取值一一对应。printWidth建议行宽指定打印器尝试换行的行长度。可读性提示官方不建议使用超过 80 个字符的行宽。许多代码风格指南把最大行宽定在 100 或 120但人类手写代码时并不会刻意让每行都顶满实践中平均行长往往远低于上限。Prettier 的printWidth并非硬性上限而是告诉 Prettier大致希望行有多长——它既会产出更短的也会产出更长的行总体趋向该值。切记不要把它当成 ESLint 的max-len来用max-len只声明最大允许长度而printWidth声明的是普遍偏好的长度。默认值CLI 写法API 写法80--print-width intprintWidth: int在 .editorconfig 中设置max_line_length会配置 Prettier 的行宽除非被更高优先级覆盖。若在格式化 Markdown 时不想换行可将 proseWrap 设为preserve以外的取值来禁用。从源码看printWidth在 src/main/core-options.evaluate.js 中声明默认值80推荐取值范围{ start: 0, end: Infinity, step: 1 }而 .editorconfig 的映射实现里还有一个文档未强调的细节max_line_length off会被转换为printWidth Infinity见 editorconfig-to-prettier.js即彻底关闭行宽约束。tabWidth每级缩进的空白数默认值CLI 写法API 写法2--tab-width inttabWidth: int在.editorconfig中设置indent_size或tab_width会配置 Prettier 的 tab 宽度除非被覆盖。源码映射规则在 editorconfig-to-prettier.js当useTabs为false且indent_size是正整数时优先取indent_size否则回退到tab_width。useTabs使用 Tab 缩进用 Tab 而非空格缩进行。默认值CLI 写法API 写法false--use-tabsuseTabs: bool在.editorconfig中设置indent_style会配置 Prettier 的 Tab 使用除非被覆盖。注意Tab 仅用于缩进Prettier 仍用空格对齐例如三元表达式中的对齐这种行为即编辑器中熟知的 SmartTabs。源码中useTabs的映射见 editorconfig-to-prettier.jsindent_style space置为falsetab或indent_size tab置为true。semi分号在语句末尾打印分号。有效取值true— 每条语句末尾加分号false— 仅在行首可能引发 ASI自动分号插入失败的地方加分号。默认值CLI 写法API 写法true--no-semisemi: bool源码声明见 src/language-js/options.js其oppositeDescription明确说明禁用后的兜底行为。实际的 ASI 兜底输出逻辑位于 src/language-js/semicolon/semicolon.js。singleQuote引号风格使用单引号代替双引号。注意事项JSX 中的引号不受此选项影响见 jsxSingleQuote当字符串中某种引号出现次数超过另一种时Prettier 会采用出现较少的那种引号作为字符串定界符——例如Im double quoted保持双引号而This \example\ is single quoted会被格式化为This example is single quoted。更多动机可参考 strings 设计说明。默认值CLI 写法API 写法false--single-quotesingleQuote: bool补充一个源码细节.editorconfig 的quote_type single|double也会映射到singleQuote该功能在 editorconfig-to-prettier.js 的注释中被标注为Undocumented feature属于非正式支持能力使用它需要知晓这一前提。quoteProps对象属性的引号策略改变对象中属性名的引号使用方式。有效取值as-needed— 仅在必需时给属性加引号consistent— 若对象中任一属性需要引号则给所有属性加引号preserve— 尊重输入中属性引号的原始用法。默认值CLI 写法API 写法as-needed--quote-props as-needed\|consistent\|preservequoteProps: \as-needed\|consistent\|preserve注意Prettier 在 Angular 表达式、TypeScript 和 Flow 中永远不会去掉数字形属性名的引号因为这些语言里字符串键与数字键的区分具有语义差异对 Vue 同理不会去除数字属性引号。jsxSingleQuoteJSX 引号在 JSX 中使用单引号代替双引号。默认值CLI 写法API 写法false--jsx-single-quotejsxSingleQuote: booltrailingComma尾随逗号默认值在 v3.0.0 中从es5变为all在可打印尾随逗号的多行逗号分隔结构中尽可能打印尾随逗号例如单行数组永远不会加尾随逗号。有效取值all— 尽可能全部加上包括函数参数与调用。以这种格式输出的 JavaScript 代码需要支持 ES2017 的引擎Node.js 8 或现代浏览器或降级编译支持同时为 TypeScript 2.7 的类型参数启用尾随逗号es5— 仅在 ES5 合法的场合加对象、数组等以及 TypeScript 和 Flow 的类型参数none— 不加尾随逗号。默认值CLI 写法API 写法all--trailing-comma all\|es5\|nonetrailingComma: \all\|es5\|none源码中该选项的默认值all可见于 src/language-js/options.js与 v3.0.0 起的行为一致。bracketSpacing花括号空格在对象字面量的花括号内打印空格。有效取值true— 例如{ foo: bar }false— 例如{foo: bar}。默认值CLI 写法API 写法true--no-bracket-spacingbracketSpacing: boolobjectWrap对象换行策略自 v3.5.0 起可用配置当对象字面量既可放一行也可拆多行时 Prettier 的换行方式。默认情况下若第一个属性之前存在换行Prettier 会把对象格式化为多行这一启发式由作者用于改善上下文可读性但也存在局限参见 Multi-line objects 设计说明。有效取值preserve— 若开括号与第一个属性之间有换行则保持多行collapse— 尽量收敛到单行。默认值CLI 写法API 写法preserve--object-wrap preserve\|collapseobjectWrap: \preserve\|collapse该选项属于 Common 类别声明于 src/common/common-options.evaluate.js并被 JS 语言层复用。arrowParens箭头函数参数括号自 v1.9.0 可用默认值在 v2.0.0 中从avoid变为always是否为单独一个的箭头函数参数包裹括号。有效取值always— 始终包含括号。例如(x) xavoid— 可能时省略括号。例如x x。默认值CLI 写法API 写法always--arrow-parens always\|avoidarrowParens: \always\|avoid乍看之下避免括号似乎视觉噪声更小但当 Prettier 移除括号后添加类型注解、追加参数或默认值等其他改动都变得更困难。在真实代码库中一致使用括号带来更好的开发体验这也是默认值的由来。HTML / Vue / Angular / JSX 选项bracketSameLine多行元素的位置把多行 HTMLHTML、JSX、Vue、Angular元素的放在最后一行末尾而不是单独放在下一行自闭合元素除外。有效取值true— 示例button classNameprettier-class idprettier-id onClick{this.handleClick} Click Here /buttonfalse— 示例button classNameprettier-class idprettier-id onClick{this.handleClick} Click Here /button默认值CLI 写法API 写法false--bracket-same-linebracketSameLine: bool[已废弃] jsxBracketSameLineJSX 括号该选项已在 v2.4.0 废弃请改用--bracket-same-line。把多行 JSX 元素的放在最后一行末尾自闭合元素除外。默认值CLI 写法API 写法false--jsx-bracket-same-linejsxBracketSameLine: bool源码中该选项带有deprecated: 2.4.0标记见 src/language-js/options.jsCLI 的--help会据此提示替代项旧配置传入时会被重定向处理。htmlWhitespaceSensitivityHTML 空白敏感度自 v1.15.0 可用Handlebars 自 2.3.0 可用指定 HTML、Vue、Angular 与 Handlebars 的全局空白敏感度详见 Prettier 官方博客中关于 whitespace-sensitive formatting 的说明见仓库博客文章 2018-11-07-1.15.0.md。有效取值css— 遵循 CSSdisplay属性的默认值来判断空白是否敏感对 Handlebars 按strict处理strict— 所有标签周围的空白或缺失都视为有意义ignore— 所有标签周围的空白都视为无意义。默认值CLI 写法API 写法css--html-whitespace-sensitivity css\|strict\|ignorehtmlWhitespaceSensitivity: \css\|strict\|ignorevueIndentScriptAndStyleVue script/style 缩进自 v1.19.0 可用是否缩进 Vue 文件中script与style标签内的代码。有效取值false— 不缩进true— 缩进。默认值CLI 写法API 写法false--vue-indent-script-and-stylevueIndentScriptAndStyle: boolsingleAttributePerLine单属性单行自 v2.6.0 可用在 HTML、Vue 与 JSX 中强制每个属性独占一行。有效取值false— 不强制true— 强制。默认值CLI 写法API 写法false--single-attribute-per-linesingleAttributePerLine: boolParser、File Path 与 Range定位格式化目标parser指定解析器指定使用哪个 parser。Prettier 会根据输入文件路径自动推断 parser通常无需修改此设置。babel与flow两个 parser 支持相同的 JavaScript 特性集包括 Flow 类型注解少数边缘情况可能表现不同——遇到时可尝试用flow替代babel。typescript与babel-ts的关系类似babel-ts可能支持 TypeScript 尚未支持的 JS 提案特性但对非法代码更不宽容且实战检验不如typescriptparser 充分。有效取值babel基于 babel/parserv1.16.0 前名为babylonbabel-flow等同babel但显式启用 Flow 解析以避免歧义自 v1.16.0 可用babel-ts类似typescript但使用 Babel 及其 TypeScript 插件自 v2.0.0 可用flow基于 flow-parsertypescript基于 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 可用json5parser 与json相同但按 json5 输出自 v1.13.0 可用jsoncparser 与json相同但按带注释 JSON输出自 v3.2.0 可用json-stringify解析行为类似JSON.parse()但更宽松空白风格类似JSON.stringify()自 v1.13.0 可用graphql基于 graphql/language自 v1.5.0 可用markdown基于 micromark自 v1.8.0 可用mdx基于 remark-parse 与 remark-mdx自 v1.15.0 可用html基于 angular-html-parser自 1.15.0 可用vueparser 与html相同但额外格式化 vue 专属语法自 1.10.0 可用angularparser 与html相同但通过 angular-estree-parser 额外格式化 angular 专属语法自 1.15.0 可用lwcparser 与html相同但额外格式化 LWC 非引号模板属性语法自 1.17.0 可用mjmlparser 与html相同但额外格式化 MJML 专属语法自 3.6.0 可用glimmerEmber / Handlebars基于 glimmer/syntax自 1.10.0 可用yaml基于 yaml 与 yaml-unist-parser自 1.14.0 可用默认值CLI 写法API 写法无--parser stringparser: string注v1.13.0 之前默认值为babylon。注Custom parser API 已在 v3.0.0 移除请改用 插件迁移方式见 API 文档。源码中 parser 的合法取值清单直接硬编码在 src/main/core-options.evaluate.js 的choices字段中flow、babel、babel-flow、babel-ts、typescript、acorn、espree、meriyah、css、less、scss、json、json5、jsonc、json-stringify、graphql、markdown、mdx、vue、yaml、glimmer、html、angular、lwc、mjml内置各语言 parser 由 src/plugins/ 目录下的插件模块如 babel.js、typescript.js、postcss.js 等注册。filepath推断 parser 的文件名指定用于推断 parser 的文件名。例如以下命令会选用 CSS parsercat foo | prettier --stdin-filepath foo.css该选项只在 CLI 与 API 中有效写入配置文件没有意义。默认值CLI 写法API 写法无--stdin-filepath stringfilepath: string在核心选项中它声明为type: path、category: CATEGORY_SPECIAL且cliName被显式重命名为stdin-filepath见 src/main/core-options.evaluate.js这正是 API 字段名与 CLI 旗标不一致的原因。rangeStart / rangeEnd只格式化文件片段默认值CLI 写法API 写法0--range-start intrangeStart: intInfinity--range-end intrangeEnd: int这两个选项可以按字符偏移量格式化从起点含到终点不含的一段代码。范围会扩展向后扩展到包含所选语句的第一行的行首向前扩展到所选语句的末尾。从源码看范围格式化在 src/main/core.js 中实现calculateRange基于 AST 计算[rangeStart, rangeEnd]text.slice(rangeStart, rangeEnd)切出片段独立格式化随后再把格式化结果拼回原文text.slice(0, rangeStart) rangeTrimmed text.slice(rangeEnd)并正确处理缩进与cursorOffset的偏移换算。编辑器在仅格式化选区时正是依赖这一机制。Pragma 系列渐进式接入 PrettierrequirePragma要求 prettier / format 标记自 v1.7.0 可用Prettier 可以限制为只格式化文件顶部包含特殊注释pragma的文件这对把大型未格式化代码库逐步迁移到 Prettier 非常有用。当提供--require-pragma时以下面任一项作为首个注释的文件会被格式化/** * prettier */或/** * format */默认值CLI 写法API 写法false--require-pragmarequirePragma: bool各语言的 pragma 注释识别由语言插件实现例如 JS 侧的 src/language-js/pragma.js通用工具见 src/utilities/pragma/。insertPragma自动插入 format 标记自 v1.8.0 可用Prettier 可以在文件顶部插入特殊的format标记表明该文件已经过 Prettier 格式化。与--require-pragma配合使用效果良好若文件顶部已存在 docblock则会在其内新增一行插入format标记。注意配合使用并非同时使用两者同时给出时--require-pragma优先--insert-pragma被忽略。设计意图是在大代码库的渐进式接入过程中参与迁移的开发者使用--insert-pragma而团队其余成员与自动化工具使用--require-pragma只处理已迁移的文件。该特性受 Facebook 的 Prettier 接入策略启发见 1.3.0 发布博客。默认值CLI 写法API 写法false--insert-pragmainsertPragma: boolcheckIgnorePragma允许单文件豁免自 v3.6.0 可用Prettier 可以允许单个文件在顶部包含特殊 pragma 注释时主动退出格式化。由于检查这些标记在格式化时会带来微小的前置开销该选项默认关闭。提供--check-ignore-pragma时以下面任一项作为首个注释的文件不会被格式化/** * noprettier */或/** * noformat */默认值CLI 写法API 写法false--check-ignore-pragmacheckIgnorePragma: bool源码声明见 src/main/core-options.evaluate.js。Markdown 与多语言通用选项proseWrap正文换行策略自 v1.8.2 可用由于部分服务如 GitHub 评论、BitBucket使用对换行敏感的渲染器Prettier 默认不改变 Markdown 正文的换行。要按行宽换行请设为always若希望所有正文块强制单行、依赖编辑器/查看器的软换行可用never。有效取值always— 按printWidth换行正文never— 每个正文块放一行preserve— 保持既有换行不变。自 v1.9.0 可用例如给定这样的 Markdown 段落The quick brown fox jumps over the lazy dog.在printWidth: 20下Prettier 的输出为alwaysThe quick brown fox jumps over the lazy dog.neverThe quick brown fox jumps over the lazy dog.preserveThe quick brown fox jumps over the lazy dog.默认值CLI 写法API 写法preserve--prose-wrap always\|never\|preserveproseWrap: \always\|never\|preserveendOfLine换行符自 v1.15.0 可用默认值在 v2.0.0 中从auto变为lf出于历史原因文本文件中存在两种常见换行符\nLFLine Feed与\r\nCRLFCarriage Return Line Feed。前者通行于 Linux 与 macOS后者盛行于 Windows。当来自不同操作系统的人协作时共享的 git 仓库很容易出现混合换行符Windows 用户还可能在提交过的文件中误把换行符从LF改成CRLF产生巨大的git diff也让git blame的行级历史更难阅读。若希望 Prettier 覆盖的 git 仓库中只保留 Linux 风格换行符确保 Prettier 的endOfLine选项设为lf自 v2.0.0 起的默认值配置 pre-commit 钩子 运行 Prettier在 CI 流水线中配置 Prettier 的--check检查在仓库的.gitattributes中添加* textauto eollf。此变更后可能需要要求 Windows 用户重新 clone 仓库以确保 git 没有在 checkout 时把LF转换为CRLF。所有现代编辑器在任意操作系统下都能正确显示\nLF换行符但 Windows 的旧版 Notepad 只能处理\r\n会把此类文件视觉上压成一行。有效取值lf— 仅 Line Feed\n通行于 Linux、macOS 以及 git 仓库内部crlf— Carriage Return Line Feed\r\n通行于 Windowscr— 仅 Carriage Return\r极少使用auto— 保持现有换行符文件内混合取值会按首行之后的实际用法归一化。默认值CLI 写法API 写法lf--end-of-line lf\|crlf\|cr\|autoendOfLine: \lf\|crlf\|cr\|auto在.editorconfig中设置end_of_line会配置 Prettier 的换行符使用除非被覆盖映射逻辑见 editorconfig-to-prettier.js。embeddedLanguageFormatting内嵌语言格式化自 v2.1.0 可用控制 Prettier 是否格式化文件中以引号包裹的内嵌代码。当 Prettier 识别出你在另一个文件的字符串里放了一段它知道如何格式化的代码——例如 JavaScript 中标签名为html的 tagged template或 Markdown 中的代码块——默认会尝试格式化它。当不希望字符串被当作代码解释时这个选项可以让你在默认行为auto与完全禁用off之间切换。有效取值auto— 当 Prettier 能自动识别内嵌代码时对其进行格式化off— 从不自动格式化内嵌代码。默认值CLI 写法API 写法auto--embedded-language-formattingoff\|autoembeddedLanguageFormatting: \off\|auto从源码结构看内嵌格式化的入口在 src/main/multiparser.js例如其中会清理rangeStart等与片段格式化冲突的选项各语言插件通过embed机制如 src/language-html/embed.js声明哪些字符串位置应交给哪个 parser 二次格式化。选项在 CLI 与配置文件中如何协同每个选项都给出了 CLI 与 API 两种写法当二者与配置文件同时出现时评估顺序由 CLI 的--config-precedence决定可选值见 src/cli/cli-options.evaluate.jscli-override默认— CLI 选项优先于配置文件file-override— 配置文件优先于 CLI 选项prefer-file— 找到配置文件则求值它并忽略其他 CLI 选项找不到则 CLI 选项正常生效。配合--config显式指定.prettierrc、package.json或prettier.config.js与--editorconfig默认开启控制是否解析.editorconfig可以在大型项目中精确控制谁说了算。小结Prettier 的选项体系小而稳定全局选项printWidth、tabWidth、useTabs、endOfLine、parser等定义于src/main/core-options.evaluate.js语言选项semi、trailingComma、quoteProps、arrowParens、experimentalTernaries、experimentalOperatorPosition等定义于各src/language-*/options.jsCommon 选项位于src/common/common-options.evaluate.js修改选项请优先写入配置文件或.editorconfig其indent_style、indent_size/tab_width、max_line_length、end_of_line、quote_type均有源码级映射保持 CLI、编辑器与 CI 的行为一致需要渐进式接入大代码库时组合使用--require-pragma--insert-pragma需要单文件豁免时启用 v3.6.0 的--check-ignore-pragma编辑器选区格式化、stdin 场景分别依赖rangeStart/rangeEnd与filepath--stdin-filepath二者均为 Special 类别选项不应写入配置文件遇到废弃选项如jsxBracketSameLine时以--help的废弃提示与本文对应的替代项--bracket-same-line为准。【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
