VS Code配置Prettier实现JS代码保存自动格式化

在 VS Code 中实现 JavaScript 代码在保存时自动格式化，核心逻辑由三个要点组成：在编辑器中安装官方 Prettier 扩展、将 Prettier 指定为 JavaScript 的默认格式化工具（Default Formatter），并开启保存自动格式化（Format On Save）开关。完成这三步后，每次在编辑器中按下保存快捷键，Prettier 就会在毫秒内静默解析当前文件的代码结构，按照预设规则规整缩进、分号与引号。

一、安装 Prettier 扩展

VS Code 本身仅内置了基础的代码缩进机制，代码风格的标准化与美化依赖专用的格式化插件。Prettier 是目前前端生态中使用最广泛的代码格式化引擎之一，具有强约束性与跨技术栈通用性。

在 VS Code 中安装 Prettier 的操作步骤如下：

1. 使用快捷键打开扩展视图：macOS 上按下 Cmd + Shift + X，Windows / Linux 上按下 Ctrl + Shift + X；或者直接点击左侧活动栏的积木形状“扩展”图标。
2. 在扩展检索框中输入 Prettier - Code formatter。
3. 在检索列表中找到标识符为 esbenp.prettier-vscode、由 Prettier 官方发布的扩展项，点击“安装”（Install）按钮。
4. 安装完毕后无需重启编辑器，扩展会自动加载并在后台注册相应的代码格式化服务。

二、核心配置项设置与生效机制

安装扩展后，必须明确告知 VS Code“在保存时调用该扩展”，否则编辑器在保存时仍然保持静默。这一调度主要涉及两个关键设置项：editor.formatOnSave 与 editor.defaultFormatter。

1. 打开配置文件 settings.json

虽然 VS Code 提供了图形化“首选项 - 设置”界面，但直接修改 settings.json 是最清晰、最不易产生配置遗漏的方式：

• 按下快捷键 Cmd + Shift + P（macOS）或 Ctrl + Shift + P（Windows / Linux）呼出命令面板。
• 输入 Open User Settings (JSON) 并回车，进入用户的全局配置文件。

2. 写入格式化调度配置

在打开的 JSON 对象中，添加如下配置项：

{
  // 开启文件保存时自动执行格式化
  "editor.formatOnSave": true,

  // 针对 JavaScript 文件明确锁定默认格式化器为 Prettier
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // （可选）若希望对全局所有语言通用 Prettier 兜底
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

推荐采用 "[javascript]" 这种针对语言环境的分组写法。这样可以确保在编写 JavaScript 时由 Prettier 负责排版，同时不影响其他可能需要专属格式化器（如 Python 的 Black 或 Go 的 gofmt）的语言环境。

如上图所示，当用户触发保存动作后，编辑器的执行链路具体如下：首先拦截保存事件并判断 editor.formatOnSave 是否开启；紧接着根据当前文件的语言识别类型找到注册的 esbenp.prettier-vscode 插件；Prettier 随后加载作用域内的规则，将源码解析为 AST（抽象语法树），完成重新序列化；最后将文本编辑事务（Text Edits）精准写回文档并写入磁盘。整个过程在后台毫秒级完成，不影响打字流畅度。

三、配置方案对比：全局用户设置 vs 项目工作区配置

在实际开发过程中，保存格式化存在两种不同的配置落地方式：一种是在 VS Code 软件层面设置的全局用户配置（User Settings），另一种是随代码仓库存储的项目工程配置（Workspace Settings + .prettierrc）。了解两者的关键差异有助于避免团队协作中的摩擦。

关键差异为什么重要？

这两者的关键差异在于代码规范的约束边界与协作成本。若仅在全局配置中指定规则，当团队成员 A 偏好单引号、团队成员 B 偏好双引号时，即使两人都配置了保存自动格式化，每次提交代码也会将对方修改的文件重新刷一遍引号，导致 Git 提交历史中充斥着海量的无意义排版 Diff，严重干扰代码审查（Code Review）。

而在项目根目录下创建 .prettierrc 配置文件并提交到 Git 仓库，能保证团队内所有开发人员在保存时读取相同的规则。标准的 .prettierrc 示例如下：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80
}

规则说明：

• "semi": true：在语句末尾统一添加分号。
• "singleQuote": true：使用单引号替代双引号（JSX 内仍保持规范的双引号）。
• "tabWidth": 2：每个缩进层级使用 2 个空格。
• "trailingComma": "es5"：在 ES5 有效的多行对象或数组末尾保留尾逗号，减少版本控制中增删属性时的 Diff 行数。
• "printWidth": 80：每行代码最大字符宽度建议为 80，超出时自动折行。

四、操作验证与效果展示

完成配置后，可以通过一段格式不规则的 JavaScript 代码进行即时验证。在工作区中新建一个 test.js 文件，输入以下排版混乱的原始示例：

// 验证输入代码（格式不规整：缩进混乱、缺少空格、单双引号混用）
function calculateUserSummary(  userInfo,orderList ){
const userTitle="VIP Customer" ;
let totalAmount= 0;
orderList.forEach( item=>{
    totalAmount +=item.price*item.count
  } )
return { name:userInfo.name, title:userTitle,total: totalAmount}
}

在编辑器中按下保存快捷键 Cmd + S（macOS）或 Ctrl + S（Windows），Prettier 会立即执行重排。预期输出的格式化效果如下：

// 自动格式化后的输出结果（缩进统一为 2 空格、运算符空格规范、单引号与分号补齐）
function calculateUserSummary(userInfo, orderList) {
  const userTitle = 'VIP Customer';
  let totalAmount = 0;
  orderList.forEach((item) => {
    totalAmount += item.price * item.count;
  });
  return { name: userInfo.name, title: userTitle, total: totalAmount };
}

如果保存后代码立刻变成了规整后的形态，说明从 VS Code 监听事件、Prettier 扩展调度到规则应用的完整链路已经成功打通。

五、保存未生效的常见原因与排查步骤

如果按下保存快捷键后代码没有任何变化，可以按照以下四个关键点进行排查：

1. 编辑器存在多个格式化器且未锁定默认值

若工作区中同时安装了 Beautify、ESLint、JS-CSS-HTML Formatter 等多个扩展，VS Code 会因为无法判断应该交给谁处理而放弃保存自动格式化。解决方法：在代码编辑区任意位置点击鼠标右键，选择“格式化文档...”，如果弹出格式化器选择列表，点击“配置默认格式化程序”，在弹出的列表中明确选中 Prettier - Code formatter。

2. 文件语言模式识别错误

查看 VS Code 窗口右下角状态栏。如果新建的文件没有保存后缀名，或者被误识别为 Plain Text（纯文本），针对 [javascript] 配置的格式化器将不会被唤醒。点击状态栏中的语言名称，手动将其切换为 JavaScript 即可。

3. 源码存在语法错误（SyntaxError）

Prettier 与基于正则匹配的简易替换工具不同，它必须先将 JavaScript 完整构建成抽象语法树（AST）。如果当前代码中有未闭合的括号、非法字符或严重语法错误，AST 解析将会失败。此时 Prettier 出于保护源码不被破坏的目的，会直接中止本次格式化操作并原样保留文本。只要将语法错误修正后再次保存即可恢复正常。

4. 根目录存在 .prettierignore 忽略文件

检查项目根目录是否存在 .prettierignore 文件。如果当前文件所在的路径（如 dist/、public/ 或特定测试目录）被写入了忽略名单中，Prettier 在收到调度请求后会自动跳过该文件。