VS Code中配置Prettier自动格式化JavaScript代码

在编写 JavaScript 项目时，团队成员往往有着不同的代码格式习惯，缩进不均、分号遗漏或引号风格不一不仅影响可读性，还会在代码评审中造成不必要的争论。在 Visual Studio Code 中集成 Prettier 扩展并配置保存时自动格式化，可以让编辑器在按下 Ctrl + S（或 macOS 上的 Cmd + S）的瞬间自动对代码完成标准化排版，在完全不改变代码语义的前提下维持统一、干净的代码风格。

一、操作全流程与核心步骤

实现保存自动格式化主要分为四个紧密相连的步骤：安装 Prettier 扩展、配置默认格式化程序、开启保存触发机制，以及在项目中按需引入自定义规则文件。理解这一链路有助于在环境变化或出现异常时准确定位原因。

二、安装与基础配置

1. 安装官方 Prettier 扩展

打开 VS Code 侧边栏的扩展面板（快捷键 Ctrl + Shift + X 或 Cmd + Shift + X），在搜索框中输入 Prettier - Code formatter。认准由官方 Prettier 团队发布的插件（唯一标识符为 esbenp.prettier-vscode），点击“安装”按钮完成安装。

2. 修改 settings.json 配置文件

虽然 VS Code 提供了图形界面的首选项设置，但直接在 settings.json 文件中声明配置更精准、更易于跨设备复制与备份。按下 Ctrl + Shift + P（macOS 为 Cmd + Shift + P）调出命令面板，输入 Preferences: Open User Settings (JSON) 并回车。

在打开的 JSON 根对象中加入以下针对 JavaScript 语言的作用域配置：

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

  // 将 Prettier 指定为全局默认格式化工具
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // 针对 JavaScript 单独强化绑定，确保不受其他语言插件干扰
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

三、配置层级与优先级关系

在日常开发中，可能既有个人通用的代码排版习惯，又有特定团队项目的规范要求。VS Code 的 Prettier 扩展通过一套清晰的层级顺序解析配置，项目根目录中的配置文件永远优先于编辑器的全局用户设置。

四、在项目中定制 .prettierrc 规则

为了保证团队协作时无论哪位开发者克隆项目，保存时都能得到一致的格式，强烈建议在项目根目录下创建 .prettierrc 或 .prettierrc.json 文件。这也是现代前端工程的标准做法。

{
  "semi": true,             // 每行语句末尾强制添加分号
  "singleQuote": true,      // 优先使用单引号包裹字符串
  "tabWidth": 2,            // 缩进级别使用 2 个空格
  "useTabs": false,         // 禁止使用 Tab 制表符缩进，统一使用空格
  "trailingComma": "es5",   // 在 ES5 兼容的语法结构中（对象、数组）保留尾随逗号
  "printWidth": 80,         // 单行最大字符宽度，超过 80 字符时自动折行
  "bracketSpacing": true,   // 对象字面量括号内部保留空格，例如 { foo: bar }
  "arrowParens": "always"   // 箭头函数单一参数时始终保留小括号，例如 (x) => x
}

忽略特定文件：.prettierignore

某些自动构建生成的中间产物、打包结果或第三方库不需要格式化。可以在项目根目录下创建 .prettierignore 文件，排除这些路径：

node_modules/
dist/
build/
coverage/
*.min.js

五、格式化效果验证与对比

完成上述配置后，可以通过一段常见的混杂 JavaScript 代码来测试保存效果。Prettier 并不只是机械地添加空格，而是通过将代码解析为抽象语法树（AST），然后按照设定的规则重新计算换行与缩进。

六、与 ESLint 协同运作

很多工程中会同时引入 ESLint 和 Prettier。两者的定位存在明显分工：

• ESLint 专注于代码质量与潜在逻辑漏洞（例如未声明变量、禁止不安全的比较、无用导入等）。
• Prettier 专注于纯外观排版与代码格式（例如换行、缩进、逗号位置、分号与引号）。

当 ESLint 中包含部分格式校验规则时，可能会与 Prettier 的保存排版发生冲突（例如 Prettier 改为单引号后，ESLint 又标红提示需要双引号）。解决这一冲突的标准方案是借助 eslint-config-prettier 关闭 ESLint 中所有与格式相关的样式规则，将纯粹的排版工作完全交给 Prettier。

在项目中执行安装命令：

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

随后在 ESLint 配置文件（如 .eslintrc.json）的 extends 数组最末尾添加 prettier：

{
  "extends": [
    "eslint:recommended",
    "prettier" // 必须放在最后，用于关闭与 Prettier 冲突的规则
  ]
}

七、保存未自动格式化的排查清单

如果按下保存后代码没有任何排版变化，请对照以下四个检查点逐项排查：

1. 确认当前文件的语言模式：查看 VS Code 右下角状态栏。如果当前新建的文件尚未保存，或者被识别为了“纯文本 (Plain Text)”，针对 [javascript] 的规则就不会激活。点击该文字将其切换为 JavaScript。
2. 显式重置默认格式化程序：在 JavaScript 代码编辑器内右键，选择“格式化文档方式... (Format Document With...)”，在弹出列表中点击底部的“配置默认格式化程序... (Configure Default Formatter...)”，明确选中“Prettier - Code formatter”。这一操作会覆盖可能发生冲突的隐式设定。
3. 排查是否存在语法解析错误：Prettier 的排版引擎基于抽象语法树。如果当前文件中存在未闭合的双引号、括号不匹配等语法错误（SyntaxError），Prettier 会选择放弃格式化以保护源代码不被错误破坏。修正报错语法后再次保存即可恢复正常。
4. 检查日志输出：在 VS Code 底部面板切换到“输出 (Output)”选项卡，在右侧下拉菜单中选择“Prettier”。如果配置解析失败或插件崩溃，输出面板中会打印详细的错误堆栈信息，可依此快速定位问题原因。