四、Prettier 编辑器集成指南

晨米酱
0 阅读13分钟

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编辑器用户设置个人偏好（后备）
5Prettier 默认值无任何配置时

最佳实践：

# 项目结构
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
扩展 IDesbenp.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.enabletrue启用/禁用 Prettier 扩展
prettier.requireConfigfalse仅在有配置文件时格式化
prettier.ignorePath.prettierignore忽略文件路径
prettier.configPath-强制指定配置文件路径
prettier.useEditorConfigtrue读取 .editorconfig 设置
prettier.resolveGlobalModulesfalse解析全局安装的 Prettier
prettier.withNodeModulesfalse格式化 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/LinuxmacOS
Reformat with PrettierCtrl+Alt+Shift+PCmd+Alt+Shift+P
Reformat Code（通用）Ctrl+Alt+LCmd+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
Zednode_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_styleuseTabs缩进方式
indent_sizetabWidth缩进宽度
tab_widthtabWidthTab 宽度
max_line_lengthprintWidth行宽
end_of_lineendOfLine行尾符号
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 在 devDependenciesPrettier 作为开发依赖安装
.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 Codeesbenp.prettier-vscodeShift+Alt+FSettings / .vscode/settings.json
WebStorm内置Ctrl+Alt+Shift+PSettings → JavaScript → Prettier
Zed内置 + external formatterCmd/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               # 包含编辑器配置说明

参考资源

avatar
文章
阅读
粉丝