VS Code怎么配置Prettier实现保存时自动格式化JS

一、Prettier 自动格式化的运行机制

了解 VS Code 是如何调度 Prettier 的，能够帮助我们在配置和后续排查问题时做到心中有数。在未做定制时，VS Code 自带了一套基础的 JavaScript 格式化能力，同时社区也存在多种格式化插件。

当用户触发保存动作（快捷键 Ctrl + S 或 macOS 上的 Cmd + S）时，VS Code 会派发保存前事件（onWillSave）。编辑器在此刻拦截文件写入流程，检查当前文件类型是否开启了 editor.formatOnSave。若开启，编辑器会查找对应语言绑定的 editor.defaultFormatter，唤起 Prettier 插件进程。Prettier 解析当前代码生成抽象语法树（AST），依据配置文件的规范生成重新对齐的代码字符串，最后交还给编辑器完成落盘。

二、四步完成保存自动格式化操作

为了让配置条理清晰且不受其他全局插件干扰，建议遵循以下四个标准操作阶段。

第 1 步：在扩展商店安装 Prettier 扩展

打开 VS Code，使用快捷键 Ctrl + Shift + X（macOS 为 Cmd + Shift + X）进入左侧扩展视图。在搜索框中输入 Prettier - Code formatter。

在搜索结果中，确认插件作者为 Prettier，唯一标识符（Identifier）为 esbenp.prettier-vscode。点击“Install / 安装”按钮，安装完成后插件会自动处于启用状态，无需重启编辑器。

第 2 步：在 settings.json 中注入格式化参数

虽然可以通过 VS Code 的图形设置界面逐项勾选，但直接在用户配置文件 settings.json 中编写不仅快捷，还能直观看到各层级的生效范围。

1. 按下快捷键 Ctrl + Shift + P（macOS 为 Cmd + Shift + P）调出命令面板。
2. 在输入框中键入 Preferences: Open User Settings (JSON) 并回车，进入全局用户设置文件。
3. 在 JSON 对象中添加以下针对 JavaScript 语言的作用域配置：

{
  // 开启全局保存时自动格式化
  "editor.formatOnSave": true,

  // 将 Prettier 指定为通用默认格式化程序
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // 针对 JavaScript 文件的专属精细化作用域配置（推荐）
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },

  // 若同时编写 JSX / React 代码，建议一并加入配置
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

第 3 步：在工程根目录建立 .prettierrc 规范文件

尽管可以在 VS Code 的 settings.json 中直接写入 "prettier.singleQuote": true 等偏好，但在团队协作中，每个成员的本地编辑器设置各不相同。最佳实践是在项目根目录创建专用配置文件 .prettierrc 或 .prettierrc.json。

Prettier 插件具有明确的规则加载优先级：它会首先在当前打开的文件目录向上查找项目级 .prettierrc，一旦找到，就会优先采用其中的规则，忽略编辑器中的个人默认偏好。

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

上述关键配置项代表的含义如下：

• semi: true：在语句末尾统一自动添加分号。
• singleQuote: true：优先将 JavaScript 中的双引号转换为单引号（JSX 属性除外）。
• tabWidth: 2：缩进单位统一为 2 个空格。
• trailingComma: "es5"：在 ES5 允许的结构（对象、数组等）的多行末尾保留逗号，减少 Git 提交冲突。
• printWidth: 80：单行代码建议最大字符长度，超出阈值时 Prettier 会自动换行。
• arrowParens: "always"：箭头函数参数始终添加小括号，例如 (x) => x + 1。

第 4 步：快捷键保存与效果验证

在项目中新建一个测试文件 test.js，输入一段故意写乱的代码：

const getUserInfo = ( name ,age )=>{
const msg = "Hello " +name ;
  return { name:name,age:age, status:"active" }
}

按下保存快捷键 Ctrl + S（macOS 为 Cmd + S），观察文件内容。如果配置成功，代码会瞬间被 Prettier 自动重排为结构严谨、规范统一的形式：

const getUserInfo = (name, age) => {
  const msg = 'Hello ' + name;
  return { name: name, age: age, status: 'active' };
};

三、配置层级覆盖与 ESLint 协同规范

在实际项目开发中，常常会遇到配置没有按照预期表现的问题，或者保存时代码被不同工具反复修改。理解配置的覆盖优先级以及 Prettier 与 ESLint 的分工边界至关重要。

1. 三级配置覆盖顺序

Prettier 在执行格式化时，遵循“就近原则”与“明确规则优先”：

1. 最高优先级（项目级规则）：位于项目根目录的 .prettierrc、.prettierrc.json 或 package.json 中的 prettier 字段。
2. 次高优先级（工作区设置）：项目目录下的 .vscode/settings.json，限定只对当前工程窗口生效。
3. 基础兜底（用户全局设置）：个人电脑操作系统的 VS Code 用户配置，仅在未找到前两项时作为默认兜底。

2. Prettier 与 ESLint 的职责分工

很多开发者容易混淆 ESLint 与 Prettier 的功能，导致在同一个项目中两者规则冲突：

为了防止在按下保存时，ESLint 自动修复把单引号改成双引号，而 Prettier 又改回单引号，推荐在项目中安装官方提供的 eslint-config-prettier：

npm install --save-dev eslint-config-prettier

然后在项目的 .eslintrc.json 的 extends 数组最后一位添加 "prettier"，它会自动关闭所有 ESLint 中可能与 Prettier 产生冲突的纯排版规则，确保代码外观全权交由 Prettier 在保存时处理。

四、保存未生效的常见排查步骤

如果按照步骤配置后，按下保存快捷键代码没有任何变化，可以按照以下诊断决策流程进行快速排查定位。

1. 检查是否存在 JavaScript 语法错误

这是保存未格式化最常见的原因。Prettier 的工作原理依赖于解析出完整的语法树。如果代码中缺少右大括号、存在未闭合的模板字符串或拼写语法错误，解析器会抛出 SyntaxError。

为了保证源码安全，避免因错误推断破坏未写完的业务逻辑，Prettier 会在检测到语法错误时主动静默终止格式化。检查代码中是否有红色波浪线报错，修复语法错误后再次保存即可。

2. 检查默认格式化程序是否被抢占

如果在编辑器中同时安装了 Beautify、JS-CSS-HTML Formatter 或其他框架插件，VS Code 在执行 formatOnSave 时可能处于冲突未决状态，或调用了错误的格式化器。

1. 在当前编辑的 .js 文件空白处单击鼠标右键。
2. 在上下文菜单中选择 使用...格式化文档 (Format Document With...)。
3. 如果底部弹出了格式化程序选择列表，点击最下方的 配置默认格式化程序... (Configure Default Formatter...)。
4. 在列表中明确点击选中 Prettier - Code formatter。

完成后，VS Code 会自动在设置中锁定该映射关系，解除抢占冲突。

3. 查看底部状态栏图标与输出日志

在 VS Code 窗口底部的状态栏右侧，找到名为 Prettier 的图标：

• 若显示为对勾（Prettier ✓），说明插件已正确识别当前文件并处于就绪状态。
• 若显示为感叹号或双中括号，说明插件在解析规则或执行过程中抛出异常。
• 点击该图标，VS Code 会直接切换到“输出 (Output)”面板并自动定位到 Prettier 日志通道。在日志中可以直观查看到具体的错误原因（如 .prettierrc 格式写错、未安装依赖解析器等）。

4. 检查忽略文件与文件语言关联

如果只有某个特定文件或文件夹无法格式化，检查项目根目录是否存在 .prettierignore 文件，确认当前文件路径是否无意中命中了忽略通配符规则。

另外，注意核对 VS Code 右下角显示的文件语言模式是否确为 JavaScript。如果被误识别为 Plain Text（纯文本），则针对 [javascript] 的格式化规则将无法触发，只需点击并将其重新切换为 JavaScript 即可。

五、总结

在 VS Code 中实现 JavaScript 保存时自动格式化，核心是构建一条清晰的联动链路：通过 "editor.formatOnSave": true 打开保存监听总开关，通过 "editor.defaultFormatter": "esbenp.prettier-vscode" 明确执行主体，再通过项目根目录的 .prettierrc 固化代码排版标准。

配置好这一套流程后，不仅免去了手动调整缩进和补齐标点的重复劳动，更能保证多人协作时代码仓库风格的一致性。