四、Prettier 编辑器集成指南

1. 概述

1.1 核心原则

编辑器集成 Prettier 的目标是让开发者在编写代码时获得即时、一致的格式化体验。无论使用哪种编辑器，遵循以下原则可以确保团队协作的一致性。

原则	说明
项目级配置优先	使用项目中的 .prettierrc 而非编辑器全局设置
使用本地 Prettier	使用 node_modules 中的 Prettier 而非全局安装
保存时自动格式化	配置 Format on Save 减少手动操作
统一编辑器配置	将编辑器配置文件（如 .vscode/settings.json）纳入版本控制
配合 .editorconfig	使用 .editorconfig 统一基础编辑器行为

为什么项目级配置优先：

❌ 编辑器全局设置
├── 开发者 A 的 VS Code：printWidth: 80
├── 开发者 B 的 WebStorm：printWidth: 100
└── 开发者 C 的 Zed：printWidth: 120
→ 每次提交都产生格式差异

✅ 项目级配置
project/.prettierrc
├── 所有编辑器读取同一配置
└── 格式化结果完全一致

1.2 项目级配置优先

编辑器中的 Prettier 设置应仅作为「后备选项」，当项目中没有 .prettierrc 配置文件时才生效。

配置优先级（从高到低）：

优先级	配置来源	适用场景
1	项目 .prettierrc 等	团队项目（推荐）
2	项目 .editorconfig	基础编辑器设置
3	编辑器工作区设置	特定项目覆盖
4	编辑器用户设置	个人偏好（后备）
5	Prettier 默认值	无任何配置时

最佳实践：

# 项目结构
project/
├── .prettierrc           # Prettier 配置（必须）
├── .prettierignore       # 忽略文件（推荐）
├── .editorconfig         # 基础编辑器配置（推荐）
├── .vscode/
│   └── settings.json     # VS Code 工作区设置（可选）
└── package.json          # 包含 prettier 依赖

提示 ：关于 Prettier 配置文件的详细说明，请参阅 二、Prettier 配置文件指南。

2. VS Code

VS Code 是前端开发最流行的编辑器，通过官方扩展可以无缝集成 Prettier。

2.1 安装 Prettier 扩展

扩展信息：

项目	内容
扩展名称	Prettier - Code formatter
扩展 ID	esbenp.prettier-vscode
安装方式	VS Code 扩展面板搜索 "Prettier" 或命令行安装
仓库地址	github.com/prettier/pr...

命令行安装：

# 通过 VS Code 命令行安装
code --install-extension esbenp.prettier-vscode

扩展功能：

功能	说明
格式化文档	格式化整个文件
格式化选中内容	仅格式化选中的代码片段
保存时格式化	配合 editor.formatOnSave 自动格式化
配置文件支持	自动读取项目中的 .prettierrc 等配置文件
忽略文件支持	自动读取 .prettierignore
状态栏显示	底部状态栏显示 Prettier 状态

2.2 基础配置

安装扩展后，需要将 Prettier 设置为默认格式化工具并启用保存时格式化。

用户设置（settings.json）：

{
  // 将 Prettier 设为默认格式化工具
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // 保存时自动格式化
  "editor.formatOnSave": true,

  // 粘贴时格式化（可选）
  "editor.formatOnPaste": false
}

按语言设置默认格式化工具：

{
  // 全局默认格式化工具
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // JavaScript 使用 Prettier
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // TypeScript 使用 Prettier
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // JSON 使用 Prettier
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // Markdown 使用 Prettier
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

注意 ：VS Code 不支持合并语言选择器（如 [javascript][typescript]），必须为每种语言单独设置。

Prettier 扩展专用设置：

设置	默认值	说明
prettier.enable	true	启用/禁用 Prettier 扩展
prettier.requireConfig	false	仅在有配置文件时格式化
prettier.ignorePath	.prettierignore	忽略文件路径
prettier.configPath	-	强制指定配置文件路径
prettier.useEditorConfig	true	读取 .editorconfig 设置
prettier.resolveGlobalModules	false	解析全局安装的 Prettier
prettier.withNodeModules	false	格式化 node_modules 中的文件

2.3 工作区设置

工作区设置存储在项目的 .vscode/settings.json 中，可以纳入版本控制与团队共享。

推荐的工作区配置（.vscode/settings.json）：

{
  // ===== 格式化设置 =====
  // 默认格式化工具
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // 保存时格式化
  "editor.formatOnSave": true,

  // ===== 语言特定设置 =====
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[scss]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[yaml]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // ===== Prettier 扩展设置 =====
  // 仅在有配置文件时格式化（团队项目推荐开启）
  "prettier.requireConfig": true
}

配合 ESLint 使用：

{
  // Prettier 作为格式化工具
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,

  // ESLint 自动修复
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
  // VS Code 保存时执行顺序：codeActionsOnSave（ESLint）→ formatOnSave（Prettier）
}

2.4 常见问题

问题一：Prettier 没有生效

排查步骤	操作方法
1	检查扩展是否已安装并启用
2	点击状态栏 "Prettier" 查看输出日志
3	确认 editor.defaultFormatter 设置正确
4	检查项目中是否有 .prettierrc 配置文件
5	运行 npm install 确保依赖已安装

查看 Prettier 输出日志：

1. 点击 VS Code 底部状态栏的 "Prettier"
2. 或：View → Output → 选择 "Prettier"
3. 查看错误信息

问题二：格式化结果与预期不符

# 检查 Prettier 使用的配置
npx prettier --find-config-path src/index.js

# 检查格式化结果
npx prettier --check src/index.js

问题三：工作区信任警告

VS Code 的工作区信任功能会限制不受信任文件夹中的 Prettier 行为：

信任状态	Prettier 行为
受信任	正常使用项目本地 Prettier、插件
不受信任	仅使用扩展内置 Prettier，不加载本地模块和插件

解决方法：

1. 打开命令面板（Ctrl+Shift+P / Cmd+Shift+P）
2. 运行 "Workspaces: Manage Workspace Trust"
3. 将工作区标记为受信任

问题四：与其他扩展冲突

{
  // 禁用 VS Code 内置的 JavaScript 格式化
  "javascript.format.enable": false,
  "typescript.format.enable": false,

  // 确保 Prettier 优先
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

3. JetBrains 系列

JetBrains 系列 IDE（WebStorm、IntelliJ IDEA、PhpStorm 等）内置了 Prettier 支持，无需安装额外插件。

3.1 WebStorm/IDEA 配置

启用 Prettier 插件：

步骤	操作
1	打开设置：Ctrl+Alt+S（macOS: Cmd+,）
2	导航到：Plugins
3	搜索 "Prettier"，确认已启用

配置 Prettier：

步骤	操作
1	打开设置：Ctrl+Alt+S（macOS: Cmd+,）
2	导航到：Languages & Frameworks → JavaScript → Prettier
3	选择配置模式（自动或手动）

配置模式对比：

模式	说明
自动	IDE 自动检测 node_modules/prettier，仅在依赖范围内生效
手动	手动指定 Prettier 路径，可扩展到依赖范围外的文件

自动配置（推荐）：

Languages & Frameworks → JavaScript → Prettier
├── ☑ Automatic Prettier configuration
└── IDE 自动发现：
    ├── node_modules/prettier
    ├── .prettierrc / prettier.config.js 等配置文件
    └── .prettierignore

手动配置：

Languages & Frameworks → JavaScript → Prettier
├── ☑ Manual Prettier configuration
├── Prettier package: ~/project/node_modules/prettier
├── Run for files: **/*.{js,ts,jsx,tsx,vue,json,css,scss,html,md}
└── ☐ Apply Prettier to files outside the prettier dependency scope

3.2 指定 Prettier 路径

在手动配置模式下，需要正确指定 Prettier 包的路径。

Prettier 包路径设置：

场景	路径示例
项目本地安装	~/project/node_modules/prettier
Monorepo	~/monorepo/node_modules/prettier
全局安装	/usr/local/lib/node_modules/prettier
pnpm	~/project/node_modules/.pnpm/prettier@*/node_modules/prettier

文件模式配置（Run for files）：

默认模式：**/*.{js,ts,jsx,tsx,cjs,cts,mjs,mts,vue,astro}

常见自定义模式：

场景	模式
添加更多文件类型	**/*.{js,ts,jsx,tsx,json,css,scss,html,md,yaml}
限制特定目录	src/**/*.{js,ts,jsx,tsx}
排除特定目录	!**/dist/**（通过 .prettierignore 实现）

启用自动执行：

选项	说明
Run on save	保存文件时自动格式化
Run on paste	粘贴代码时自动格式化
Run on 'Reformat Code' action	使用快捷键重新格式化时调用 Prettier

推荐设置：
├── ☑ Run on save
├── ☐ Run on paste（可选）
└── ☑ Run on 'Reformat Code' action

3.3 快捷键设置

内置快捷键：

操作	Windows/Linux	macOS
Reformat with Prettier	Ctrl+Alt+Shift+P	Cmd+Alt+Shift+P
Reformat Code（通用）	Ctrl+Alt+L	Cmd+Alt+L

自定义快捷键：

1. 打开设置：Ctrl+Alt+S（macOS: Cmd+,）
2. 导航到：Keymap
3. 搜索 "Prettier"
4. 右键点击 "Reformat with Prettier"
5. 选择 "Add Keyboard Shortcut"
6. 设置自定义快捷键

状态栏小部件：

WebStorm 在状态栏显示 Prettier 图标，提供快速访问：

功能	说明
点击图标	显示快速菜单
Restart Service	重启 Prettier 服务
Edit Config	打开 Prettier 配置文件
Settings	打开 Prettier 设置页面

4. Zed

Zed 支持通过语言级设置调用外部格式化器。对于 JavaScript/TypeScript 项目，Zed 默认使用语言服务器（TypeScript 内置）进行格式化，如果项目需要与 Prettier CLI 及其插件生态保持一致（例如与 CI、lint-staged 输出一致），就需要把 Prettier 配置为外部 formatter，并开启保存时格式化。

4.1 基础配置

配置入口：

配置范围	文件位置	适用场景
用户级	Zed Settings Editor	个人默认配置
项目级	.zed/settings.json	团队共享（推荐）
语言级	languages.<语言名> 节点	为不同语言设置不同格式化器

先理解 external 的执行规则：

规则	说明
command 必须是可执行文件名或路径	例如 prettier、node_modules/.bin/prettier、yarn
command 不是 shell 命令行	不能写 "yarn prettier" 这种带空格的整串命令
子命令放到 arguments	例如 "command": "yarn" + "arguments": ["prettier", ...]

方案 A（推荐）：使用项目本地二进制 node_modules/.bin/prettier

{
  "languages": {
    "TypeScript": {
      "formatter": {
        "external": {
          "command": "node_modules/.bin/prettier",
          "arguments": ["--stdin-filepath", "{buffer_path}"]
        }
      },
      "format_on_save": "on"
    }
  }
}

方案 B：通过包管理器调用 Prettier（适合统一 Node 工具链）

{
  "languages": {
    "TypeScript": {
      "formatter": {
        "external": {
          "command": "pnpm",
          "arguments": ["exec", "prettier", "--stdin-filepath", "{buffer_path}"]
        }
      },
      "format_on_save": "on"
    }
  }
}

说明 ：npm、yarn 也可用同样思路。关键点是 command 写包管理器可执行文件，prettier 放在 arguments。

---

提示 ：--stdin-filepath 可让 Prettier 根据当前文件路径正确选择 parser，并读取项目内 .prettierrc 与 .prettierignore。若项目尚未安装依赖（没有 node_modules），请先执行 npm install / pnpm install / yarn。

4.2 项目级共享配置

将 Zed 配置写入仓库内的 .zed/settings.json，可确保团队成员获得一致的保存时格式化行为。

推荐的 .zed/settings.json（项目本地 Prettier）：

{
  "languages": {
    "JavaScript": {
      "formatter": {
        "external": {
          "command": "node_modules/.bin/prettier",
          "arguments": ["--stdin-filepath", "{buffer_path}"]
        }
      },
      "format_on_save": "on"
    },
    "TypeScript": {
      "formatter": {
        "external": {
          "command": "node_modules/.bin/prettier",
          "arguments": ["--stdin-filepath", "{buffer_path}"]
        }
      },
      "format_on_save": "on"
    },
    "JSON": {
      "formatter": {
        "external": {
          "command": "node_modules/.bin/prettier",
          "arguments": ["--stdin-filepath", "{buffer_path}"]
        }
      },
      "format_on_save": "on"
    },
    "Markdown": {
      "formatter": {
        "external": {
          "command": "node_modules/.bin/prettier",
          "arguments": ["--stdin-filepath", "{buffer_path}"]
        }
      },
      "format_on_save": "on"
    }
  }
}

关键配置项说明：

配置项	说明
external.command	外部可执行文件（如本地 bin 或包管理器）
external.arguments	传递给 Prettier 的参数
format_on_save	保存时自动格式化（"on"/"off"）

4.3 与 ESLint 组合

在 Zed 中可以把「ESLint 修复」和「Prettier 格式化」串联执行：先运行 source.fixAll.eslint，再执行 Prettier。

{
  "languages": {
    "JavaScript": {
      "formatter": [
        {
          "code_action": "source.fixAll.eslint"
        },
        {
          "external": {
            "command": "node_modules/.bin/prettier",
            "arguments": ["--stdin-filepath", "{buffer_path}"]
          }
        }
      ],
      "format_on_save": "on"
    }
  }
}

4.4 常见问题

问题一：报错 No such file or directory (os error 2)

这通常表示 Zed 找不到 external.command 指定的可执行文件，而不是 Prettier 规则配置错误。

常见写法	结果	说明
"command": "yarn prettier"	❌ 失败	Zed 不按 shell 拆分命令
"command": "prettier"	可能失败	依赖 Zed 进程的 PATH 能找到 prettier
"command": "node_modules/.bin/prettier"	✅ 推荐	明确使用项目本地二进制
"command": "yarn", "arguments": ["prettier", ...]	✅ 可用	子命令写在 arguments

问题二：保存时未格式化或配置未生效

排查步骤	操作方法
1	检查 languages.<语言>.format_on_save 是否为 "on"
2	检查 formatter.external.command 是否存在且可执行
3	若使用本地路径，确认 node_modules/.bin/prettier 已生成
4	运行 npx prettier --find-config-path src/index.ts 确认配置来源
5	运行 npx prettier --check src/index.ts 验证格式化结果
6	在 Zed 命令面板执行 zed: open log 查看完整错误

注意 ：如果 prettier 命令不可用，请先在项目中安装依赖：npm install --save-dev prettier。

5. 跨编辑器一致性

5.1 使用项目本地 Prettier

确保所有编辑器使用项目中安装的 Prettier 版本是保持一致性的关键。

为什么使用本地 Prettier：

问题	使用全局 Prettier	使用本地 Prettier
版本不一致	开发者 Prettier 版本不同	所有人使用相同版本
配置不生效	全局 Prettier 可能忽略配置	正确读取项目配置
插件不可用	全局环境无法找到插件	插件安装在 node_modules
CI/CD 不一致	本地与 CI 格式化结果不同	本地与 CI 结果一致

确保本地安装：

# 安装 Prettier 为开发依赖
npm install --save-dev prettier

# 或使用其他包管理器
pnpm add -D prettier
yarn add -D prettier

各编辑器使用本地 Prettier 的配置：

编辑器	配置方式
VS Code	默认自动使用 node_modules/prettier
WebStorm	自动配置模式或手动指定 node_modules/prettier
Zed	node_modules/.bin/prettier（推荐）/ pnpm 或 yarn 或 npm exec（备选）

VS Code 配置：

{
  // 仅在有配置文件时格式化，避免使用全局设置
  "prettier.requireConfig": true,

  // 禁用解析全局模块
  "prettier.resolveGlobalModules": false
}

5.2 .editorconfig 配合

.editorconfig 是跨编辑器的基础配置文件，Prettier 会读取其中的部分设置。

Prettier 支持的 .editorconfig 选项：

.editorconfig 选项	Prettier 选项	说明
indent_style	useTabs	缩进方式
indent_size	tabWidth	缩进宽度
tab_width	tabWidth	Tab 宽度
max_line_length	printWidth	行宽
end_of_line	endOfLine	行尾符号
quote_type（非标准）	singleQuote	引号类型

推荐的 .editorconfig：

# .editorconfig
# https://editorconfig.org

root = true

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

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

配置优先级：

Prettier 配置文件（.prettierrc）
    ↓ 覆盖
.editorconfig
    ↓ 覆盖
Prettier 默认值

注意 ：如果 .prettierrc 中明确设置了某个选项，该选项会覆盖 .editorconfig 中的对应值。

VS Code 配合 .editorconfig：

{
  // 启用 .editorconfig 支持
  "prettier.useEditorConfig": true
}

5.3 团队配置共享策略

策略一：共享编辑器配置文件

将编辑器配置文件纳入版本控制，团队成员克隆仓库后自动获得统一配置。

# 推荐纳入版本控制的文件
project/
├── .editorconfig         # 跨编辑器基础配置
├── .prettierrc           # Prettier 配置
├── .prettierignore       # Prettier 忽略文件
├── .vscode/
│   ├── settings.json     # VS Code 工作区设置
│   └── extensions.json   # 推荐扩展列表
└── .idea/                # JetBrains 配置（可选）
    └── prettier.xml

VS Code 推荐扩展（.vscode/extensions.json）：

{
  "recommendations": [
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "editorconfig.editorconfig"
  ]
}

策略二：文档化配置步骤

在项目 README 中说明编辑器配置要求：

## 开发环境配置

### VS Code

1. 安装推荐扩展（VS Code 会自动提示）
2. 项目已包含工作区设置，无需额外配置

### WebStorm

1. 打开设置 → Languages & Frameworks → JavaScript → Prettier
2. 选择 "Automatic Prettier configuration"
3. 勾选 "Run on save"

### Zed

1. 在项目中创建 `.zed/settings.json`
2. 参考 4.2 模板配置 `formatter.external`（推荐本地 `node_modules/.bin/prettier`）
3. 设置 `format_on_save` 为 `"on"`

策略三：使用 Git Hooks 作为保障

即使编辑器配置不正确，Git Hooks 也能确保提交的代码已格式化：

# 安装 husky 和 lint-staged
npm install --save-dev husky lint-staged

# package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json,css,scss,html,md}": "prettier --write"
  }
}

配置完整性检查清单：

检查项	说明
.prettierrc 存在	项目有 Prettier 配置文件
prettier 在 devDependencies	Prettier 作为开发依赖安装
.editorconfig 存在	有跨编辑器基础配置
.vscode/settings.json 存在	VS Code 用户有工作区配置
编辑器配置已共享	配置文件已纳入版本控制
Git Hooks 已配置	提交前自动格式化作为保障

6. 总结

6.1 核心要点回顾

要点	说明
项目配置优先	使用 .prettierrc 而非编辑器全局设置
使用本地 Prettier	确保 node_modules 中安装了 Prettier
保存时自动格式化	配置 Format on Save 提升开发体验
共享编辑器配置	将 .vscode/settings.json 等纳入版本控制
.editorconfig 配合	使用 .editorconfig 统一基础编辑器行为
Git Hooks 保障	使用 husky + lint-staged 作为最后防线

6.2 编辑器配置速查表

编辑器	插件/扩展	格式化快捷键	配置位置
VS Code	esbenp.prettier-vscode	Shift+Alt+F	Settings / .vscode/settings.json
WebStorm	内置	Ctrl+Alt+Shift+P	Settings → JavaScript → Prettier
Zed	内置 + external formatter	Cmd/Ctrl+S（保存触发）	Settings Editor / .zed/settings.json

6.3 推荐的项目配置文件结构

project/
├── .editorconfig           # 跨编辑器基础配置
├── .prettierrc             # Prettier 配置
├── .prettierignore         # Prettier 忽略文件
├── .vscode/
│   ├── settings.json       # VS Code 工作区设置
│   └── extensions.json     # VS Code 推荐扩展
├── package.json            # 包含 prettier 依赖
└── README.md               # 包含编辑器配置说明

参考资源

• Prettier Editor Integration
• Prettier VS Code Extension
• Prettier WebStorm Setup
• Zed Docs - Getting Started
• Zed Docs - Configuring Languages
• Zed Docs - All Settings
• EditorConfig
• 二、Prettier 配置文件指南