Prettier 配置参数详解与命令行用法

介绍

prettier 是一个流行的代码格式化工具

它和 ESLint 的分工要分清：ESLint 管代码质量，比如未使用的变量、可能出错的写法；prettier 只管长相，缩进、引号、换行、分号这些。prettier 的做法比较激进——它把源码解析成 AST，然后完全丢掉原来的格式，按自己的规则重新打印一遍。所以它的可配置项刻意做得很少，团队里没什么可争的，装上就统一了。

这也解释了为什么有些格式没法通过配置控制。prettier 的设计哲学是「只暴露真正有分歧的选项」，比如单双引号、有无分号；至于运算符两边怎么断行、对象什么时候展开，它按自己的算法算，不给你调。想调只能接受它，或者不用它。

安装

装成项目的开发依赖，让版本跟着仓库走。prettier 不同小版本的输出可能有差异，如果团队成员各装各的版本，会出现互相把对方的代码重新格式化一遍的情况，diff 全是格式改动：

yarn add prettier -D

具体参数使用示例

配置文件可以是 .prettierrc、.prettierrc.json、prettier.config.js，或者直接写在 package.json 的 prettier 字段里。下面这份是我常用的配置，每一项都带了注释说明作用：

module.exports = {
  // 每行最多显示120个字符
  printWidth: 120,
  // tab 缩进
  tabWidth: 2,
  // 使用tab（制表位）缩进而非空格
  useTabs: false,
  // 每行结束都加上分号
  semi: true,
  // 使用单引号而不是双引号
  singleQuote: true,
  /**
   * "as-needed"：仅在需要时在对象属性周围添加引号。
   * "consistent"：如果对象中至少有一个属性需要用引号引起来，请用所有属性引起来。
   * "preserve"：保持对象属性中引号的输入
   */
  quoteProps: 'as-needed',
  // 在 jsx 中使用单引号代替双引号
  jsxSingleQuote: false,
  /**
   * all：所有可能的地方都加上逗号，比如数组、对象最后一个元素
   * none：不尾随逗号
   * es5：在ES5中有效的结尾逗号（对象，数组等）
   * */
  trailingComma: 'none',
  // 在对象，数组括号与文字之间加空格 "{ foo: bar }"
  bracketSpacing: true,
  // 在 jsx 中把 '>' 是否单独放一行
  jsxBracketSameLine: false,
  /** 箭头函数参数只有一个时是否要有小括号。
   * avoid：省略括号 例：x => x
   * always 始终拥有 例：(x) => x
   */
  arrowParens: 'always',
  // 若为true，文件顶部加了 /*** @prettier */或/*** @format */的文件才会被格式化
  requirePragma: false,
  // 当requirePragma参数为true时,此参数为true将向@format标记后面添加一个换行符
  insertPragma: false,
  /**
   * 折行
   * always：当超出 print width 时就折行
   * never：不折行
   * perserve：按照文件原样折行
   */
  proseWrap: 'never',
  /**
   * 指定HTML文件的全局空格敏感度
   * css：遵守 CSS display 属性的默认值。
   * strict：空白被认为是敏感的。
   * ignore：空白被认为是不敏感的。
   */
  htmlWhitespaceSensitivity: 'ignore',
  // 结尾是 lf-\n cr-\r lfcr-\n\r  auto-保持现有的行尾设置
  endOfLine: 'auto',
  // 是否给 vue 中的 <script> and <style>标签加缩进
  vueIndentScriptAndStyle: true,
  // 让 prettier 使用 eslint 的代码格式进行校验
  eslintIntegration: true,
  // 让 prettier 使用 stylelint 的代码格式进行校验
  stylelintIntegration: true,
};

几个需要额外说明的项：

endOfLine 我现在倾向于设成 'lf' 而不是 'auto'。Windows 上 git 默认 autocrlf 会把换行转成 CRLF，如果 prettier 用 auto 保持现状，Mac 和 Windows 的同事提交的文件换行符就不一致，diff 里整个文件都算改动。统一写死 lf，配合 .gitattributes 里的 * text=auto eol=lf 最省心。

jsxBracketSameLine 在 prettier 2.4 之后已经废弃，替代项是 bracketSameLine，而且作用范围扩大到了 HTML、Vue 模板。新项目直接用新名字，老配置留着会打印一条 deprecation 警告。

最后两项 eslintIntegration 和 stylelintIntegration 严格说不是 prettier 的官方配置项，它们来自早期编辑器插件的设定，prettier 本身会忽略。真要让 prettier 和 ESLint 协同，正确做法是装 eslint-config-prettier 把 ESLint 里跟格式相关的规则全部关掉，避免两边规则打架——典型症状是保存时格式化成一种样子，ESLint 又报错要求改回去。

printWidth 设 120 是个偏宽的值。它不是硬性截断，而是 prettier 决定「这行要不要拆开」的参考阈值，实际输出可能超过它（比如一个很长的字符串就没法拆）。

webstorm 中的配置

WebStorm 内置了 prettier 支持，不用装插件。在设置里找到 Prettier 面板，指定 prettier 包的路径（一般是项目里的 node_modules/prettier）和要作用的文件类型 glob，勾上「On save」就能保存时自动格式化。下图是我的配置界面，重点看 Prettier package 那一栏指向的是项目本地的包，不是全局安装的：

prettier 命令行

编辑器插件解决日常保存时的格式化，但 CI 里卡门禁、或者一次性格式化整个老项目，还是要走命令行。

• -v 或者 --version 查看 prettier 版本

先确认装的是哪个版本，排查「本地和 CI 格式化结果不一样」这类问题时第一步就看它：

prettier -v

• --check 检查目录下哪些代码文件需要格式化

这个参数只报告不修改，把不符合规范的文件路径列出来，有不合规的就以非零状态码退出。CI 里用它做门禁最合适——谁没格式化就让流水线红掉，而不是让 CI 悄悄改代码：

prettier --check .

下图是执行结果，列出的每一行都是需要重新格式化的文件，末尾会提示用 --write 来修复：

• --write 检查并格式化项目所有文件，npx prettier . --write

--write 会直接改写文件。范围可以是整个目录，也可以像下面这样只处理单个文件，改动小的时候更可控：

prettier ./src/views/demo/other/prettier.vue --write

第一次对老项目全量格式化时，务必单独提一个 commit，别和业务改动混在一起。几千个文件的格式 diff 混进功能改动里，review 没法做，出问题也没法回溯。提完可以把这个 commit 的 hash 写进 .git-blame-ignore-revs，这样 git blame 会跳过它，不会把所有代码的作者都显示成你。

package.json 中的 prettier 修复配置

写进 scripts 就不用每次记参数了。glob 要用双引号包起来，否则会被 shell 先展开，遇到文件多的目录可能超出参数长度限制，而且 shell 的 glob 默认不支持 ** 递归：

"lint:prettier": "prettier --write  \"src/**/*.{js,json,tsx,css,less,scss,vue,html,md}\"",

配套建一个 .prettierignore 文件，把 dist、node_modules、自动生成的 *.d.ts 之类排除掉。语法和 .gitignore 一样。prettier 默认会跳过 node_modules，但生成物目录得自己写。