Prettier 配置文件 (.prettierrc) 完全指南

一、配置文件核心意义

.prettierrc（支持 JSON/JSON5/YAML/JS 格式）是 Prettier 的核心配置文件，用于定义代码自动格式化规则，统一团队代码风格。Prettier 是一款"有主见"的代码格式化工具，支持 JavaScript/TypeScript/JSX/HTML/CSS/JSON 等数十种语言，可集成到编辑器、构建工具或 CI 流程中，避免手动格式化的风格分歧。

二、配置文件格式与加载优先级

2.1 支持的配置文件格式

配置项	类型	示例/说明
JSON	文件名示例	.prettierrc/prettier.config.json
JSON5	文件名示例	.prettierrc.json5
YAML	文件名示例	.prettierrc.yml/.prettierrc.yaml
JavaScript	文件名示例	.prettierrc.js/prettier.config.js
package.json	配置方式	新增 "prettier" 字段

2.2 加载优先级（从高到低）

1. 命令行参数（--config）
2. 项目根目录 .prettierrc.js / .prettierrc.cjs
3. 项目根目录 .prettierrc.json / .prettierrc.json5
4. 项目根目录 .prettierrc.yml / .prettierrc.yaml
5. 项目根目录 .prettierrc（JSON 格式）
6. package.json 中的 prettier 字段
7. 全局配置（~/.prettierrc）

三、完整配置项详解

3.1 核心格式化规则（通用）

配置项	类型	默认值	详细说明
printWidth	number	80	每行代码最大字符数（超过则自动换行）
tabWidth	number	2	缩进的空格数（tab 对应的空格数）
useTabs	boolean	false	是否使用 tab 缩进（true：tab 缩进；false：空格缩进）
semi	boolean	true	语句末尾是否添加分号
singleQuote	boolean	false	是否使用单引号（true：单引号；false：双引号）
quoteProps	string	as-needed	对象属性引号规则：as-needed（仅必要时添加）、consistent（统一添加/不添加）、preserve（保留原有格式）
jsxSingleQuote	boolean	false	JSX 中是否使用单引号（独立于 singleQuote）
trailingComma	string	es5	尾逗号规则：none（无尾逗号）、es5（ES5 合法的尾逗号）、all（所有场景）
bracketSpacing	boolean	true	对象字面量括号两侧是否留空格（true：{ foo: bar }；false：{foo:bar}）
bracketSameLine	boolean	false	JSX 标签的闭合括号是否换行（true：同行；false：换行）
arrowParens	string	always	箭头函数参数括号规则：always（始终添加 (x) => x）、avoid（单参数省略 x => x）
rangeStart	number	0	格式化的起始行（仅格式化指定范围代码）
rangeEnd	number	Infinity	格式化的结束行
parser	string	-	指定解析器：babel（JS/JSX）、typescript（TS/TSX）、json、html、css、markdown
filepath	string	-	指定文件路径（用于自动推断解析器，如 src/index.tsx）
requirePragma	boolean	false	仅格式化包含 /*_ @format _/ 注释的文件
insertPragma	boolean	false	格式化后在文件顶部插入 /*_ @format _/ 注释
proseWrap	string	preserve	Markdown 文本换行规则：preserve（保留原有换行）、always（超过宽度换行）、never（不换行）
htmlWhitespaceSensitivity	string	css	HTML 空白敏感度：css（遵循 CSS 规则）、strict（严格保留）、ignore（忽略）
vueIndentScriptAndStyle	boolean	false	Vue 文件中 script/style 标签是否缩进
endOfLine	string	lf	换行符类型：lf（\n）、crlf（\r\n）、cr（\r）、auto（自动检测）
embeddedLanguageFormatting	string	auto	嵌入语言格式化：auto（自动格式化）、off（禁用）

3.2 高级配置项（特定场景）

配置项	类型	默认值	详细说明
singleAttributePerLine	boolean	false	JSX/HTML 单个属性是否占一行（true：<div\n id="app"\n/>；false： ）
plugins	string[]	[]	加载自定义插件（如 @prettier/plugin-xml、prettier-plugin-tailwindcss）
overrides	array	[]	针对特定文件的自定义规则（优先级高于全局配置）
parserOptions	object	{}	解析器自定义选项（如 TypeScript 的 decoratorsBeforeExport）

3.3 忽略文件配置（.prettierignore）

与 .gitignore 语法一致，示例：

忽略 node_modules

node_modules/

忽略构建目录

dist/
build/

忽略特定文件

_.log
_.tmp
package-lock.json

忽略特定目录下的文件

src/assets/*

四、场景化配置示例

4.1 基础通用配置（.prettierrc JSON 格式）

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "jsxSingleQuote": false,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "avoid",
  "endOfLine": "lf",
  "proseWrap": "preserve",
  "htmlWhitespaceSensitivity": "css",
  "vueIndentScriptAndStyle": false,
  "singleAttributePerLine": false
}

4.2 前端项目完整配置（.prettierrc.js）

module.exports = {
  // 核心规则
  printWidth: 120,
  tabWidth: 2,
  useTabs: false,
  semi: true,
  singleQuote: true,
  jsxSingleQuote: false,
  trailingComma: "all",
  bracketSpacing: true,
  bracketSameLine: false,
  arrowParens: "avoid",
  endOfLine: "lf",

  // 特定语言规则
  proseWrap: "always",
  htmlWhitespaceSensitivity: "strict",
  vueIndentScriptAndStyle: true,

  // 自定义插件
  plugins: ["prettier-plugin-tailwindcss", "prettier-plugin-vue"],

  // 针对不同文件的覆盖规则
  overrides: [
    {
      files: ["*.json", "*.yml", "*.yaml"],
      options: {
        printWidth: 200,
        tabWidth: 2,
      },
    },
    {
      files: ["*.md"],
      options: {
        proseWrap: "preserve",
        printWidth: 80,
      },
    },
    {
      files: ["*.ts", "*.tsx"],
      options: {
        parser: "typescript",
        trailingComma: "all",
      },
    },
  ],
};

4.3 package.json 中配置

{
  "name": "my-project",
  "version": "1.0.0",
  "prettier": {
    "printWidth": 80,
    "tabWidth": 2,
    "singleQuote": true,
    "trailingComma": "es5"
  }
}

五、常用插件与集成

5.1 主流插件

插件名称	适用场景	配置方式
prettier-plugin-tailwindcss	Tailwind CSS 类名排序	安装后自动生效，无需额外配置
prettier-plugin-vue	Vue 文件格式化优化	加入 plugins 数组
prettier-plugin-organize-imports	TS/JS 导入语句排序	加入 plugins 数组
prettier-plugin-xml	XML/HTML 格式化	加入 plugins 数组，指定 parser: "xml"
prettier-plugin-python	Python 代码格式化	加入 plugins 数组

5.2 编辑器集成（VS Code）

1. 安装 Prettier 插件（esbenp.prettier-vscode）
2. 设置默认格式化器：

// .vscode/settings.json
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true, // 保存时自动格式化
  "editor.formatOnType": false, // 输入时自动格式化
  "prettier.configPath": ".prettierrc.js" // 指定配置文件路径
}

5.3 构建工具集成（npm script）

// package.json
{
  "scripts": {
    "format": "prettier --write \"src/**/*.{js,ts,jsx,tsx,css,md}\"", // 格式化指定文件
    "format:check": "prettier --check \"src/**/*.{js,ts,jsx,tsx}\"" // 检查未格式化文件
  }
}

六、最佳实践

6.1 团队协作规范

1. 项目根目录必须包含 .prettierrc 和 .prettierignore，统一规则；
2. 结合 ESLint 使用：关闭 ESLint 中与 Prettier 冲突的规则（使用 eslint-config-prettier）；
3. CI/CD 流程中加入 prettier --check，拒绝未格式化的代码提交；
4. 避免过度自定义规则，优先使用 Prettier 默认值（减少维护成本）。

6.2 性能优化

1. .prettierignore 中忽略 node_modules、dist 等无需格式化的目录；
2. 针对大型项目，使用 overrides 仅为核心文件配置规则；
3. 避免在 parserOptions 中配置不必要的解析器选项。

6.3 与 ESLint 配合

1. 安装依赖：

   npm install eslint-config-prettier eslint-plugin-prettier --save-dev

2. ESLint 配置：

// .eslintrc.json
{
  "extends": [
    "eslint:recommended",
    "plugin:prettier/recommended", // 启用 Prettier 规则
    "prettier" // 关闭冲突规则
  ]
}