VSCode + Prettier 终极配置指南：告别手动格式化，提升开发效率

每次看到同事提交的代码里，有的用双引号有的用单引号，有的行尾有分号有的没有，那种感觉就像走进了一个风格混乱的代码集市。更别提手动调整缩进和换行了，简直是开发流程中的“体力活”。如果你也厌倦了在代码风格上反复拉扯，想让编辑器在你敲下保存键的那一刻，就自动把代码整理得干净利落，那么今天这篇深度指南就是为你准备的。

我们将超越简单的配置步骤，深入探讨如何将 VSCode 和 Prettier 打造成一个无缝协作的“代码美容师”。无论你是刚接触前端的新手，还是追求极致效率的全栈工程师，这套方案都能帮你建立起一套坚固、可定制且团队友好的代码格式化工作流。告别无休止的代码评审争论，把精力真正聚焦在逻辑和业务上。

1. 理解核心工具：为什么是 Prettier？

在深入配置之前，我们有必要先理解 Prettier 的哲学和它解决的问题。市面上代码格式化工具不少，比如 ESLint 也具备一定的格式化能力，但 Prettier 选择了一条不同的路。

Prettier 的核心定位是“有主见的代码格式化器”。这意味着它提供了一套强制的、不可协商的代码风格规则。你无法配置“是否使用分号”，但你可以配置“使用分号”还是“不使用分号”。这种“有主见”的特性，恰恰是它的最大优势——它彻底终结了团队内部关于代码风格的争论。风格选项是有限的、明确的，要么接受，要么不用，没有中间地带。

相比之下，ESLint 等工具更侧重于代码质量和潜在错误（如未使用的变量、可能的错误），其格式化功能更像是附加品，且规则配置可以极其灵活，这反而容易导致规则冲突和配置膨胀。

一个高效的现代前端工作流，通常是让两者各司其职：

• Prettier：专职负责代码格式（缩进、引号、换行等）。
• ESLint：专职负责代码质量与最佳实践（变量使用、React Hooks 规则等）。

为了让它们和平共处，通常需要安装 eslint-config-prettier 来关闭 ESLint 中所有与格式冲突的规则，把格式化的权力完全交给 Prettier。

提示：如果你的项目已经配置了 ESLint，在引入 Prettier 后，务必检查并解决规则冲突，否则保存时可能会看到两种工具“打架”导致的反复格式化。

2. 从零开始：项目级与全局级配置策略

配置 Prettier 有两个层面：项目级和编辑器全局级。理解两者的区别和适用场景，是构建稳定环境的第一步。

2.1 项目级配置：团队协作的基石

项目级配置是首选且推荐的方式。通过在项目根目录创建配置文件（如 .prettierrc、prettier.config.js 或 package.json 中的 prettier 字段），你可以确保所有克隆该仓库的开发者，无论其个人 VSCode 设置如何，都能使用完全一致的格式化规则。这是保证代码库风格统一的根本。

配置文件格式选择： 目前最主流和清晰的方式是使用 .prettierrc 文件（JSON 或 YAML 格式）或 prettier.config.js（CommonJS）。原始内容中提到的 .cjs 扩展名，是针对特定模块规范问题的解决方案。

// .prettierrc 示例 (JSON)
{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

// prettier.config.js 示例 (CommonJS)
module.exports = {
  printWidth: 100,
  tabWidth: 2,
  useTabs: false,
  semi: false,
  singleQuote: true,
  trailingComma: 'es5',
  bracketSpacing: true,
  arrowParens: 'always',
  endOfLine: 'lf',
};

如果你在配置时遇到了类似 require of prettier.config.js ... to a dynamic import() 的错误，这通常是因为项目的 package.json 中设置了 "type": "module"，强制所有 .js 文件使用 ES 模块规范。此时，你有两个选择：

1. 将配置文件重命名为 .prettierrc.cjs，并使用 module.exports 语法。
2. 使用 .prettierrc（JSON格式）来彻底避免模块规范问题。我强烈推荐第二种方式，因为它最简单，兼容性最好。

2.2 全局配置与编辑器集成：个人效率的保障

项目配置确保了规则一致，而 VSCode 的集成则确保了自动化体验。我们需要在 VSCode 的设置中完成几个关键绑定。

首先，通过命令面板 (Ctrl+Shift+P) 或设置界面，确保以下核心设置生效：

设置项 (Setting)	推荐值	作用解析
editor.defaultFormatter	esbenp.prettier-vscode	将 Prettier 设为所有支持语言的默认格式化工具。
editor.formatOnSave	true	灵魂设置。保存文件时自动触发格式化，实现“保存即美化”。
editor.codeActionsOnSave	{ "source.fixAll.eslint": true }	如果项目有 ESLint，建议同时开启，保存时自动修复 ESLint 可自动修复的问题。
prettier.requireConfig	true	建议设置为 true，要求 Prettier 仅在找到配置文件时才运行，避免意外格式化。

注意：editor.formatOnSave 和 editor.codeActionsOnSave 可以同时工作。它们的执行顺序是：先进行 Prettier 格式化，再执行 ESLint 修复。这能完美实现格式与质量的“一键修复”。

有时，VSCode 可能无法自动探测到项目中的 Prettier 配置文件路径，尤其是当配置文件不在根目录或有自定义命名时。这时，可以在项目根目录下的 .vscode/settings.json 文件中进行显式指定：

{
  "prettier.configPath": "./.prettierrc"
}

这个项目级的 VSCode 设置文件，其优先级会高于用户的全局设置，非常适合用来固化项目的编辑器行为，进一步保证团队环境的一致性。

3. 深度解析：关键配置项与实战场景

仅仅复制粘贴配置是不够的。理解每个选项背后的逻辑和适用场景，才能做出符合项目需求的最佳决策。我们来深入剖析几个最核心也最容易产生困惑的配置。

3.1 行宽与换行策略：printWidth 与 proseWrap

printWidth 可能是最直观的配置。它定义了格式化后每行代码的“软”字符上限。Prettier 会尽量让代码保持在一行内，但当超出这个限制时，它会智能地将表达式、参数列表等换到下一行。

• 默认值 80：源于早期终端和打印机的限制，现在看可能有些狭窄。
• 常见值 100 或 120：更适合现代宽屏显示器，能减少不必要的换行，让代码看起来更紧凑。选择 100 是一个比较平衡的折中。
• 实战考量：这个值会影响代码的可读性。太宽需要左右滚动，太窄则会产生大量碎片化的短行。可以结合团队使用的显示器尺寸和代码评审习惯来决定。

proseWrap 主要针对 Markdown 等文本内容。“never” 表示不强制换行，保持原样；“always” 则在达到 printWidth 时强制换行；“preserve” 则基本不处理。对于技术文档，我通常设置为 “always”，以保证渲染出的段落美观。

3.2 引号与逗号：风格统一的关键

singleQuote: true 和 trailingComma: 'es5' 是现代 JavaScript/TypeScript 项目中非常流行的选择。

• 单引号 (singleQuote)：使用单引号可以减少一次 Shift 按键（在美式键盘上），并且当字符串中包含 HTML 或 JSON（通常使用双引号）时，无需转义引号，看起来更清晰。

  // singleQuote: true
  const name = 'World';
  const html = '<div class="container"></div>'; // 双引号无需转义
  
  // singleQuote: false
  const name = "World";
  const html = "<div class=\"container\"></div>"; // 需要转义
  

• 尾随逗号 (trailingComma)：设置为 ‘es5’ 或 ‘all’ 是极力推荐的做法。它在对象、数组的最后一项后面添加逗号。这样做有两个巨大好处：
  1. 更清晰的版本差异：当增删条目时，Git 的 diff 只会显示变化的那一行，而不是同时显示上一行的逗号变化。
  2. 便于重新排序：在调整条目顺序时，无需关心是否要添加或删除最后一个逗号。

3.3 框架特异性配置：Vue 与 JSX/TSX

对于 Vue 和 React 开发者，Prettier 提供了贴心的框架支持。

• Vue (vueIndentScriptAndStyle)：这个选项控制 <script> 和 <style> 块内的内容是否进行缩进。通常保持 true 即可，使单文件组件内的代码保持统一的缩进层级，结构更清晰。
• JSX (jsxSingleQuote, jsxBracketSameLine)：
  • jsxSingleQuote: 控制 JSX 属性使用单引号还是双引号。为了与 HTML 习惯保持一致，通常设为 false（使用双引号）。
  • jsxBracketSameLine: 这个选项在 Prettier v2.4.0 之后已被重命名为 bracketSameLine。它控制多行 JSX 元素的闭合标签 > 是否与最后一个属性在同一行。false（默认）会让闭合标签独占一行，视觉上更清晰，尤其是当元素有很多属性时。

4. 高级工作流与疑难排解

配置妥当后，我们来看看如何将其融入更高级的开发流程，并解决一些常见问题。

4.1 与 Git 集成：提交前自动格式化

仅仅在保存时格式化还不够。为了确保仓库中每一行代码都是格式化后的状态，可以在 Git 提交代码前自动执行格式化。这需要使用 Git Hooks 工具。

最流行的方案是 Husky 加 lint-staged。

1. Husky：让你能方便地使用 Git Hooks。
2. lint-staged：只对 Git 暂存区（staged）中的文件运行指定的命令，效率极高。

安装和配置步骤如下：

# 安装依赖 (项目本地安装)
npm install --save-dev husky lint-staged
# 初始化 Husky
npx husky init

然后在 package.json 中配置 lint-staged：

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,vue,md,json,css,scss}": [
      "prettier --write"
    ]
  }
}

最后，Husky 会在 .husky/pre-commit 钩子中调用 npx lint-staged。这样，每次执行 git commit 时，被提交的文件都会先经过 Prettier 格式化，保证进入仓库的代码风格完美统一。

4.2 常见问题与解决方案

即使配置正确，偶尔也会遇到一些“小脾气”。这里有几个我踩过坑的常见问题：

• 格式化不生效或使用了错误规则：

  • 检查 VSCode 右下角状态栏：打开一个文件，查看右下角显示的语言模式和格式化工具。确保它显示为“Prettier”而不是其他（如“Vetur”对于 Vue 文件）。
  • 检查输出面板：在 VSCode 中打开输出面板 (Ctrl+Shift+U)，选择“Prettier”频道。这里会显示 Prettier 扩展运行的详细日志和任何错误信息，是排查问题的第一现场。
  • 配置文件优先级与冲突：Prettier 会从当前文件所在目录向上查找配置文件。确保没有更上级目录（如你的用户主目录）的配置文件覆盖了项目配置。同时，检查 VSCode 的 settings.json 中是否有与 Prettier 配置项同名的设置（如 prettier.singleQuote），这些设置会覆盖文件配置。

• 与 ESLint 冲突： 这是最常见的问题。症状是保存时代码格式在两种风格间来回跳动。根本解决方案是使用 eslint-config-prettier。

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

  然后在你的 ESLint 配置文件（如 .eslintrc.js）中，将 prettier 添加到 extends 数组的最后：

  module.exports = {
    extends: [
      'eslint:recommended',
      // ... 其他配置
      'prettier' // 一定要放在最后！
    ],
  };
  

  这行配置会关闭所有与 Prettier 冲突的 ESLint 规则。

• 忽略特定文件或代码块： 有时你确实不希望某些文件（如压缩后的资源、自动生成的代码）或某段代码被格式化。Prettier 提供了 .prettierignore 文件（语法类似 .gitignore）来忽略整个文件。对于代码块，可以使用特殊的注释来禁用：

  // prettier-ignore
  const matrix = [
    1, 0, 0,
    0, 1, 0,
    0, 0, 1,
  ]; // 这段数组将保持原样，不会被格式化成多行
  

折腾完这一整套，从项目配置、编辑器集成到 Git 工作流，你会发现代码风格从此不再是团队内耗的议题。它变成了一种安静、可靠的基础设施，就像呼吸一样自然。我现在已经无法想象没有 formatOnSave 的编码生活了，它节省的那些微不足道却又累积起来无比可观的时间与心力，最终都转化为了对产品逻辑更深层次的思考。如果你在配置过程中遇到了上面没覆盖的奇怪问题，不妨去看看 Prettier 扩展的输出日志，或者检查一下项目里是不是藏着另一套陈旧的格式化配置，大多数时候，问题就藏在这些细节里。