VSCode 中 Prettier 工作原理与使用指南

🧠 一、总体概念：三层架构

当你在 VSCode 中使用 Prettier 时，其实是三层协作在一起的：

scss 复制代码

┌────────────────────────────┐
│  VSCode (编辑器)           │ ← 触发格式化命令 (Shift + Alt + F)
├────────────────────────────┤
│  Prettier VSCode 插件层     │ ← "代理层"，决定用哪个 Prettier、加载哪个配置
├────────────────────────────┤
│  Prettier CLI / JS 核心库   │ ← 真正的格式化引擎 (格式化 AST → 输出)
└────────────────────────────┘

⚙️ 二、完整执行流程（当你按下格式化快捷键）

以下是 VSCode 执行 Prettier 格式化的完整路径（每一步都可影响结果）：

Step 1. 触发格式化请求

VSCode 通过内置接口调用 "editor.defaultFormatter" 注册的扩展。

如果设置为 "esbenp.prettier-vscode"，就会调用 Prettier 插件。

VSCode 并不关心你是哪个版本的 prettier，只是发出"请格式化"指令。

Step 2. 插件定位 Prettier 执行环境

插件会依次尝试以下几种方式找到 Prettier 的"运行实例"：

优先级	查找位置	说明
①	项目本地 `node_modules/prettier`	最优先。若存在，则始终使用项目内版本（以确保一致性）。
②	全局 Prettier（仅当 `"resolveGlobalModules": true`）	若开启此项且本地无 prettier，则尝试全局环境路径。
③	VSCode 插件内置 prettier	插件自带一个 fallback 版本（通常较新），作为最后兜底。

⚠️ 注意：一旦项目内有本地 prettier，VSCode 用户配置中 prettier 的路径就会被忽略。

Step 3. 确定配置文件来源

插件加载 prettier 后，会进入配置解析阶段：

优先级	配置来源	说明
①	项目根目录 `.prettierrc`, `.prettierrc.json`, `.prettierrc.js`, `prettier.config.js`	自动查找并加载
②	VSCode 设置 `"prettier.configPath"`	强制使用特定配置文件路径（覆盖上面的①）
③	VSCode 用户设置中的 prettier 选项（如 tabWidth、semi 等）	当找不到配置文件时生效
④	Prettier 默认配置	如果 `"requireConfig": true` 且没找到配置，则不格式化；若为 `false`，用默认风格。

Step 4. 读取文件内容并格式化

插件将当前文件内容发送给 Prettier 核心库：

ini 复制代码

formatted = prettier.format(documentText, resolvedOptions)

此时：

resolvedOptions = （项目配置 + 用户配置 + 默认配置）合并结果；
核心库解析 AST（抽象语法树），重新格式化输出字符串；
插件替换编辑器中文件内容。

Step 5. 返回结果

格式化完成后，VSCode 自动更新编辑器中的内容。

如果格式化失败，插件会提示错误，如：

"Prettier not found"
"No configuration found"
"Cannot read config file ..."

🧩 三、重要配置项的作用机制

配置项	作用	默认	典型误区
`"editor.defaultFormatter"`	指定 VSCode 使用哪个扩展格式化	无	忘记设置导致调用别的扩展
`"prettier.requireConfig"`	是否必须有配置文件才能运行	false	设为 true 会导致 demo项目或单文件无法格式化
`"prettier.resolveGlobalModules"`	若本地无 prettier，是否尝试全局版本	false	开启后在多 Node 环境可能出错
`"prettier.configPath"`	指定配置文件路径，覆盖自动查找	无	一旦设置，会让项目内 `.prettierrc` 失效,除非配置路径和配置文件保持一致
`"prettier.prettierPath"`	指定 prettier 模块路径	无	用于自定义版本或特殊安装结构
`"prettier.useEditorConfig"`	是否读取 `.editorconfig`	true	可统一缩进、换行规则
`"prettier.ignorePath"`	指定忽略文件路径	`.prettierignore`	可自定义忽略规则

↔️ 四、Prettier 配置与实例是分开的

很多人混淆这两个概念：

类型	举例	作用
Prettier 实例	`/node_modules/prettier/index.js`	决定使用哪个版本执行格式化逻辑
Prettier 配置文件	`.prettierrc`, `prettier.config.js`	决定格式化风格（缩进、分号、引号）

这两者独立存在，VSCode 插件会：

先找到实例（运行哪个 prettier）；
再加载配置（按哪个规则格式化）。

📊 五、整体执行逻辑流程图（简化）

scss 复制代码

┌────────────────────────────────────┐
│ VSCode 触发格式化命令              │
└──────────────┬─────────────────────┘
               │
               ▼
┌────────────────────────────────────┐
│ Prettier 插件启动                  │
│ 检查当前文件语言是否支持           │
└──────────────┬─────────────────────┘
               │
               ▼
┌────────────────────────────────────┐
│ 查找 Prettier 实例                 │
│ ① 本地 node_modules                │
│ ② 全局模块 (resolveGlobalModules)  │
│ ③ 插件内置 prettier                │
└──────────────┬─────────────────────┘
               │
               ▼
┌────────────────────────────────────┐
│ 查找配置文件                       │
│ ① .prettierrc / config.js          │
│ ② configPath (若设置则覆盖)        │
│ ③ VSCode 设置                      │
│ ④ 默认配置                         │
└──────────────┬─────────────────────┘
               │
               ▼
┌────────────────────────────────────┐
│ 调用 prettier.format()              │
│ 输出格式化结果并更新编辑器内容       │
└────────────────────────────────────┘

⚖️ 六、 VSCode 保存格式化 vs CLI 命令格式化

场景	触发方式	Prettier 实例	配置文件加载逻辑
VSCode 保存文件自动格式化	`editor.formatDocument`	项目本地 prettier（优先）或插件内置 prettier	自动查找 `.prettierrc`、`prettier.config.js` 或 package.json 中的 `prettier` 字段；若未找到且 `"requireConfig": false`，使用 VSCode 用户配置
命令行或 npm run format	`prettier --write .`	项目本地 prettier（node_modules）	从执行命令目录开始查找 `.prettierrc`、`prettier.config.js`

⚠️ 两者独立运行，但如果项目本地依赖 + 配置齐全，结果是一致的。

✅ 七、最佳实践总结

场景	推荐配置
团队/正式项目	在项目中本地安装 `prettier` 并添加 `.prettierrc`
个人 demo / 单文件	不装依赖，仅靠 VSCode 用户配置（`requireConfig:false`）
特殊环境统一格式	才使用 `configPath` 指定路径
多 Node 版本环境	不启用 `resolveGlobalModules`，避免找错路径