Configuration File

您可以通过以下方式配置 Prettier（按优先级从高到低排序）：

  • 在 package.json 或 https://github.com/pnpm/pnpm/pull/1799 文件中添加 "prettier" 配置项。
  • 使用 JSON 或 YAML 格式的 .prettierrc 文件。
  • .prettierrc.json、.prettierrc.yml、.prettierrc.yaml 或 .prettierrc.json5 文件。
  • 通过 .prettierrc.js、prettier.config.js、.prettierrc.ts 或 prettier.config.ts 文件导出对象（使用 export default 或 module.exports，具体取决于 package.json 中的 https://nodejs.org/api/packages.html#type 值）。
  • 使用 .prettierrc.mjs、prettier.config.mjs、.prettierrc.mts 或 prettier.config.mts 文件导出对象（必须使用 export default）。
  • 使用 .prettierrc.cjs、prettier.config.cjs、.prettierrc.cts 或 prettier.config.cts 文件导出对象（必须使用 module.exports）。
  • .prettierrc.toml 文件。

相关信息

TypeScript 配置文件需要#typescript-配置文件

配置文件解析流程：从待格式化文件所在目录开始，向上递归查找文件树，直到找到（或未找到）配置文件。

Prettier 刻意不支持任何全局配置，这是为了确保项目复制到其他计算机时保持格式行为一致。否则无法保证团队成员获得相同的格式化结果。

配置文件支持的选项与 options.md 完全相同。

TypeScript 配置文件

TypeScript 支持需满足：

  • Node.js >= 22.6.0
  • Node.js v24.3.0 之前版本需添加 --experimental-strip-types 标志
# 方式一：直接指定实验性标志
node --experimental-strip-types node_modules/prettier/bin/prettier.cjs . --write
# 方式二：通过环境变量指定
NODE_OPTIONS="--experimental-strip-types" prettier . --write

基础配置示例

JSON 格式

{
  // 在 ES5 有效处添加尾部逗号（对象/数组等）
  "trailingComma": "es5", 
  // 缩进宽度为 4 空格
  "tabWidth": 4,         
  // 禁用语句结尾分号
  "semi": false,         
  // 使用单引号替代双引号
  "singleQuote": true    
}

JS 模块 (ES Modules)

// 适用于：prettier.config.js, .prettierrc.js, prettier.config.mjs, .prettierrc.mjs

/**
 * @see https://prettier.io/docs/configuration
 * @type {import("prettier").Config}
 */
const config = {
  trailingComma: "es5",
  tabWidth: 4,
  semi: false,
  singleQuote: true,
};

export default config; // ES Modules 导出方式

JS 模块 (CommonJS)

// 适用于：prettier.config.js, .prettierrc.js, prettier.config.cjs, .prettierrc.cjs

/**
 * @see https://prettier.io/docs/configuration
 * @type {import("prettier").Config}
 */
const config = {
  trailingComma: "es5",
  tabWidth: 4,
  semi: false,
  singleQuote: true,
};

module.exports = config; // CommonJS 导出方式

TypeScript 模块 (ES Modules)

// 适用于：prettier.config.ts, .prettierrc.ts, prettier.config.mts, .prettierrc.mts

import { type Config } from "prettier"; // 导入类型声明

const config: Config = {
  trailingComma: "none", // 禁用所有尾部逗号
};

export default config; // ES Modules 导出

TypeScript 模块 (CommonJS)

// 适用于：prettier.config.ts, .prettierrc.ts, prettier.config.cts, .prettierrc.cts

import { type Config } from "prettier"; // 导入类型声明

const config: Config = {
  trailingComma: "none", // 禁用所有尾部逗号
};

module.exports = config; // CommonJS 导出

YAML 格式

# 适用于 .prettierrc 或 .prettierrc.yaml
trailingComma: "es5"
tabWidth: 4
semi: false
singleQuote: true

TOML 格式

# 适用于 .prettierrc.toml
trailingComma = "es5"
tabWidth = 4
semi = false
singleQuote = true

配置覆盖规则

通过覆盖规则可为特定文件扩展名、文件夹或文件设置独立配置，语法继承自 ESLint 的 https://eslint.org/docs/latest/user-guide/configuring/configuration-files#how-do-overrides-work。

JSON 格式覆盖示例

{
  // 全局禁用分号
  "semi": false,  
  "overrides": [
    {
      // 对 .test.js 文件启用分号
      "files": "*.test.js", 
      "options": {
        "semi": true
      }
    },
    {
      // 对 HTML 文件和 legacy 目录下 JS 文件设置 4 空格缩进
      "files": ["*.html", "legacy/**/*.js"], 
      "options": {
        "tabWidth": 4
      }
    }
  ]
}

YAML 格式覆盖示例

semi: false
overrides:
  - files: "*.test.js"
    options:
      semi: true
  - files:
      - "*.html"
      - "legacy/**/*.js"
    options:
      tabWidth: 4

关键说明：

  • files 是每个覆盖规则的必填项，可为字符串或字符串数组
  • excludeFiles 可选，用于排除特定文件（同样支持字符串或数组）

设置 options.md#parser 选项

Prettier 默认根据文件扩展名自动推断解析器。结合 overrides 可自定义未知文件的解析规则。

示例 1：格式化 Prettier 自身配置

{
  "overrides": [
    {
      "files": ".prettierrc", // 目标文件
      "options": { "parser": "json" } // 强制使用 JSON 解析器
    }
  ]
}

示例 2：JS 文件改用 Flow 解析器

{
  "overrides": [
    {
      "files": "*.js",
      "options": {
        "parser": "flow" // 替代默认的 babel 解析器
      }
    }
  ]
}

重要警告：
❌ 禁止 在配置顶层直接设置 parser 选项
✅ 仅允许 在 overrides 内部使用
否则将破坏 Prettier 的自动解析器推断机制，导致错误解析（如用 JS 解析器处理 CSS 文件）。

配置模式校验

如需校验配置格式，可使用 JSON Schema：
https://json.schemastore.org/prettierrc

EditorConfig 集成

项目中的 https://editorconfig.org/ 会被 Prettier 自动解析并转换对应配置（优先级低于 .prettierrc）。

配置映射关系如下：

# 禁止向上级目录查找配置
# root = true

[*]
# Prettier 固定行为（不可配置）
charset = utf-8               # 强制 UTF-8 编码
insert_final_newline = true   # 文件末尾插入空行
# 注意：Prettier 不会修剪模板字符串内尾部空格（但编辑器可能修剪）
# trim_trailing_whitespace = true

# 以下映射 Prettier 可配置项
# (默认配置值，如自定义需调整)
end_of_line = lf        # 换行符(LF)
indent_style = space    # 空格缩进
indent_size = 2         # 缩进空格数
max_line_length = 80    # 最大行宽

默认配置可直接复用的 .editorconfig 模板：

[*]
charset = utf-8
insert_final_newline = true
end_of_line = lf
indent_style = space
indent_size = 2
max_line_length = 80

核心要点总结

  1. 配置优先级：采用从高到低的层级覆盖机制，package.json 优先级最高，TOML 文件优先级最低
  2. 无全局配置：工程化设计确保跨环境一致性，禁止全局配置防止团队协作差异
  3. 多格式支持：支持 JSON/YAML/JS/TS/TOML 等多种配置文件格式
  4. 覆盖配置：通过 overrides 实现文件粒度的差异化配置
  5. 解析器约束：解析器选项需严格限定在 overrides 内使用，避免破坏自动推断
  6. 环境集成：自动兼容 .editorconfig 配置，优化编辑器协同体验
  7. TS 特殊要求：Node.js <24.3 需通过 --experimental-strip-types 启用完整支持
最后更新: