【vscodeprettier配置】详解：从入门到高效实践

是什么？—— 理解VS Code Prettier

Prettier 是一个“有主见”的代码格式化工具。它的核心理念是：让所有代码都遵循统一的风格，减少关于代码风格的争论，从而提升开发效率和团队协作的顺畅度。当 Prettier 整合到 VS Code 编辑器中时（通常通过安装 Prettier 扩展实现），它能自动地格式化你的代码，确保你编写的每一行代码都符合预设的、一致的格式规范。

它不仅仅是简单地缩进或整理空白符，Prettier 会解析你的代码（支持 JavaScript、TypeScript、CSS、HTML、Vue、Angular、Markdown 等多种语言），然后重新按照自己的规则打印出来。这意味着，无论你最初的编写习惯如何，Prettier 都能将其“校正”为统一的、规范的格式。

为什么？—— 自动化格式化的价值

自动化代码格式化带来的好处是多方面的，它远不止于让代码看起来更整洁：

• 代码一致性： 确保整个项目中的所有代码都遵循相同的风格指南。无论有多少开发者参与，代码的视觉风格都保持统一，这极大地提升了项目的可维护性和可读性。
• 减少争论： 团队成员无需花费时间在代码风格的争论上。Prettier 强制执行一套规则，将这些琐碎的决策自动化，让开发者可以专注于业务逻辑和功能实现。
• 提升可读性： 统一且规范的格式让代码更容易被阅读和理解。当代码格式整齐划一，开发者可以更快地捕捉到代码结构和逻辑，减少认知负担。
• 简化代码审查： 在代码审查时，审查者可以更专注于发现潜在的逻辑错误和性能问题，而不是分散精力去指出格式上的不一致。由于 Prettier 已经处理了格式问题，提交的代码将更加“纯粹”。
• 减少合并冲突： 当多名开发者修改同一文件时，如果代码格式不一致，很容易引发因格式不同而导致的合并冲突。Prettier 强制统一格式，从而降低了这种“噪音”冲突的发生概率。
• 提高开发效率： 开发者无需手动调整代码格式，保存时自动格式化，使得开发流程更加流畅高效。

在哪里？—— Prettier配置文件的存放位置与优先级

Prettier 的配置可以存在于多个层面，并且它们之间存在优先级关系。理解这些位置和优先级对于管理你的代码格式至关重要：

1. VS Code 用户设置 (User Settings)

这是全局性的配置，对你在 VS Code 中打开的所有项目都生效。这些设置通常存储在操作系统的特定目录下，比如 macOS 上的 `~/Library/Application Support/Code/User/settings.json` 或 Windows 上的 `%APPDATA%\Code\User\settings.json`。

如何访问：

• 通过菜单：文件 (File) -> 首选项 (Preferences) -> 设置 (Settings)。
• 使用快捷键：Ctrl + , (Windows/Linux) 或 Cmd + , (macOS)。

在设置界面搜索“Prettier”可以找到相关的图形界面配置项，也可以点击右上角的“打开设置(JSON)”图标直接编辑 `settings.json` 文件。

2. VS Code 工作区设置 (Workspace Settings)

这些设置仅对当前 VS Code 工作区（通常是某个项目文件夹）生效。它们存储在项目根目录下的 `.vscode/settings.json` 文件中。

如何创建/访问：

• 在 VS Code 中打开一个项目文件夹。
• 如果 `.vscode` 文件夹不存在，手动创建一个。
• 在 `.vscode` 文件夹中创建或编辑 `settings.json` 文件。
• 也可以通过文件 (File) -> 首选项 (Preferences) -> 设置 (Settings)，然后选择顶部的“工作区”标签来编辑。

工作区设置优先级高于用户设置，这意味着如果同一个配置项在用户设置和工作区设置中都存在，工作区设置会覆盖用户设置。

3. Prettier 项目级配置文件 (Prettier Configuration Files)

这是 Prettier 自身识别的配置文件，位于项目根目录。这些文件是推荐用于定义项目特定格式规则的最佳实践，因为它们能够被版本控制系统跟踪，确保团队所有成员都使用相同的格式规范。

支持的文件名和格式：

• .prettierrc (JSON, YAML, INI等)
• .prettierrc.json
• .prettierrc.js (导出配置对象的 CommonJS 模块)
• prettier.config.js (导出配置对象的 CommonJS 模块)
• .prettierrc.yaml / .prettierrc.yml
• .prettierrc.toml
• 在 package.json 中添加 "prettier" 字段

优先级： Prettier 项目级配置文件拥有最高的优先级。它们会覆盖 VS Code 用户设置和工作区设置中与 Prettier 相关的配置。这是最推荐的方式，因为它确保了项目的格式化规则与编辑器的配置分离，并可以随项目代码一起分发。

4. Prettier 忽略文件 (.prettierignore)

这个文件用于告诉 Prettier 哪些文件或文件夹应该被忽略，不进行格式化。它通常也放在项目根目录。

优先级： .prettierignore 文件独立于配置优先级，它仅仅是定义了哪些文件不应被处理。

配置优先级总结：

1. Prettier 项目级配置文件 (例如 .prettierrc.json, prettier.config.js) – 最高优先级。
2. VS Code 工作区设置 (.vscode/settings.json) – 其次。
3. VS Code 用户设置 (全局 settings.json) – 最低优先级。

这意味着，如果你在 .prettierrc.json 中设置了 "semi": false，即使你的 VS Code 工作区或用户设置中配置了 "prettier.semi": true，Prettier 依然会遵守 .prettierrc.json 的规则，不在语句末尾添加分号。

多少？—— 配置复杂性与成本考量

配置 Prettier 的“多少”可以从几个维度来理解：配置的复杂度、维护成本以及学习曲线。

配置的复杂度

Prettier 的设计理念是“有主见”，这意味着它提供的配置选项相对较少。这正是其优势所在——避免无休止的风格争论。因此，配置本身并不复杂。

• 入门级： 仅安装 VS Code Prettier 扩展并启用“保存时格式化”功能，几乎无需任何额外配置，即可获得基本的格式化能力。这是“极少量”配置。
• 中级： 根据团队或个人偏好，调整少数几个核心选项，如单引号/双引号、分号、行宽、逗号样式等。这通常涉及在 .prettierrc.json 中添加几十行配置。
• 高级： 结合 ESLint 等代码质量工具，并处理它们之间的潜在冲突。这可能需要额外的插件和更复杂的配置调整，但仍然在可控范围内。这属于“中等量”配置，但一次性配置后收益巨大。

维护成本

一旦配置完成并集成到项目中，Prettier 的维护成本极低：

• 自动化： 格式化过程是自动进行的，开发者无需手动介入。

• 一致性： 减少了因代码风格不一致引发的返工和争论，从长远来看节省了大量时间和精力。

• 更新： 随着 Prettier 自身版本迭代，偶尔可能需要更新依赖或微调配置，但这种情况不频繁且通常有清晰的升级指南。

学习曲线

对于新接触的开发者，学习曲线非常平缓：

• 安装与启用： 几分钟内即可完成。
• 核心配置： Prettier 的主要配置选项很少，通过官方文档或社区示例，很快就能掌握。
• 理解优先级： 掌握上述“在哪里”部分提到的配置优先级，可以有效解决配置冲突问题。

总而言之，Prettier 的配置成本非常低，而其带来的收益（代码质量、团队效率）却非常可观。它是投入产出比极高的工具之一。

如何？—— 详细的配置步骤与示例

本节将详细指导你如何在 VS Code 中配置 Prettier，并提供具体的代码示例。

1. 安装 VS Code Prettier 扩展

首先，你需要在 VS Code 中安装 Prettier 扩展。

1. 打开 VS Code。
2. 点击左侧的“扩展”视图图标 (Ctrl+Shift+X 或 Cmd+Shift+X)。
3. 在搜索框中输入“Prettier”。
4. 找到名为“Prettier – Code formatter”的扩展（通常作者是 Esben Petersen），点击“安装”。

2. 配置 VS Code 编辑器行为 (用户/工作区设置)

这些设置决定了 VS Code 如何与 Prettier 扩展协同工作。

打开你的用户设置或工作区设置 (settings.json)，并添加或修改以下关键配置：

2.1 设定默认格式化器

确保 Prettier 被设置为你期望的语言的默认格式化器。这可以避免与其他格式化工具（如 Beautify）产生冲突。

{
    // 将 Prettier 设置为所有支持语言的默认格式化器
    "editor.defaultFormatter": "esbenp.prettier-vscode",

    // 可以为特定语言指定默认格式化器
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[typescript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[vue]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[html]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[css]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[scss]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[less]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[json]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[jsonc]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[markdown]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
}

2.2 开启保存时格式化

强烈建议开启此功能，它会在你保存文件时自动应用 Prettier 格式化。

{
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        // 如果同时使用 ESLint 和 Prettier，此配置非常重要
        // 它会在保存时自动修复 ESLint 错误，并配合 Prettier 进行格式化
        "source.fixAll.eslint": true
    }
}

2.3 Prettier 扩展特有的 VS Code 配置项

这些是 Prettier 扩展提供的一些自身行为的配置，它们会影响扩展如何读取 Prettier 项目级配置文件以及如何处理某些特殊情况。

{
    // 是否启用 Prettier 扩展
    "prettier.enable": true,

    // 是否在检测到格式错误时弹出通知
    "prettier.requireConfig": false, // 设置为 true 则只有在有 Prettier 配置文件时才格式化

    // 针对特定文件类型的路径通配符，告诉 Prettier 哪些文件应该被格式化
    // 通常无需修改，因为 Prettier 会自动检测
    "prettier.documentSelectors": [
        "**/*.{js,jsx,ts,tsx,json,css,scss,less,html,vue,svelte,md,yaml,yml,graphql}"
    ],

    // 是否在保存时显示 Prettier 状态栏图标
    "prettier.showIcon": true,

    // 是否在工作区中寻找 Prettier 模块
    "prettier.resolveGlobalModules": false, // 通常应设为 false，使用项目依赖
    "prettier.configPath": "", // 指定 Prettier 配置文件的路径，通常留空让 Prettier 自动寻找
    "prettier.prettierPath": "", // 指定 Prettier 模块的路径，通常留空让 Prettier 自动寻找
}

注意：
在 VS Code 的 `settings.json` 中，prettier.useTabs、prettier.semi 等直接对应的 Prettier 配置项，现在通常推荐直接在项目级的 Prettier 配置文件（如 .prettierrc.json）中进行配置。这样做的好处是，这些规则随项目代码一起版本控制，保证团队协作的一致性，且不受个人 VS Code 设置影响。

3. 创建 Prettier 项目级配置文件 (推荐方式)

在你的项目根目录下创建 .prettierrc.json 文件，并添加你想要的配置选项。

这是一个包含常见配置项的示例：

// .prettierrc.json
{
    "printWidth": 100,           // 单行代码的最大字符数，超出则换行
    "tabWidth": 4,               // 每个缩进的空格数
    "useTabs": false,            // 使用空格而不是制表符进行缩进
    "semi": true,                // 在语句末尾添加分号
    "singleQuote": true,         // 使用单引号而不是双引号
    "quoteProps": "as-needed",   // 对象属性的引用方式：
                                 // "as-needed": 仅在需要时（如属性名包含特殊字符）加引号
                                 // "consistent": 保持一致，要么都加要么都不加
                                 // "preserve": 保持用户输入
    "jsxSingleQuote": false,     // JSX 中使用双引号而不是单引号
    "trailingComma": "all",      // 在多行语句中的逗号结尾
                                 // "es5": ES5 (对象、数组等)
                                 // "none": 不加
                                 // "all": 尽可能加 (函数参数等)
    "bracketSpacing": true,      // 在对象字面量的大括号之间添加空格
                                 // 例如：{ foo: bar } 而不是 {foo: bar}
    "jsxBracketSameLine": false, // JSX 元素的'>'是否与属性在同一行
                                 // 例如：
 而不是 

    "arrowParens": "always",     // 箭头函数参数的括号：
                                 // "always": 始终包含括号 (x) => x
                                 // "avoid": 仅在需要时包含 (x => x, (x, y) => x + y)
    "rangeStart": 0,             // 只格式化文件的一部分，通常用于集成其他工具
    "rangeEnd": Infinity,        // 同上
    "filepath": "index.js",      // 用于指定解析的文件路径，通常由 Prettier 自动处理
    "requirePragma": false,      // 不需要文件顶部包含特殊的 @prettier 标记才能格式化
    "insertPragma": false,       // 不在文件顶部插入特殊的 @prettier 标记
    "proseWrap": "preserve",     // Markdown 和文本文件的换行方式
                                 // "always": 始终按 printWidth 换行
                                 // "never": 从不换行
                                 // "preserve": 保持原有换行
    "htmlWhitespaceSensitivity": "css", // HTML 空白敏感度
                                        // "css": 遵循 CSS display 属性的默认值
                                        // "strict": 所有标签之间的空格都被认为是重要的
                                        // "ignore": 所有标签之间的空格都不重要
    "vueIndentScriptAndStyle": false, // 是否在 Vue 文件中缩进 <script> 和 <style> 标签内的代码
    "endOfLine": "lf",           // 行尾序列：
                                 // "lf": Line Feed (\n) - Linux/macOS
                                 // "crlf": Carriage Return + Line Feed (\r\n) - Windows
                                 // "cr": Carriage Return (\r) - 旧版 Mac
                                 // "auto": 保持现有行尾序列
    "embeddedLanguageFormatting": "auto" // 是否格式化内嵌代码块 (如 Markdown 中的 JS 代码)
}

在 package.json 中配置

你也可以将 Prettier 配置直接写入 package.json 文件中：

// package.json
{
    "name": "my-project",
    "version": "1.0.0",
    "prettier": {
        "printWidth": 100,
        "tabWidth": 4,
        "useTabs": false,
        "semi": true,
        "singleQuote": true,
        "trailingComma": "all"
    }
}

4. 配置忽略文件 (.prettierignore)

在项目根目录下创建 .prettierignore 文件，列出你不想让 Prettier 格式化的文件或目录。语法类似于 .gitignore。

# .prettierignore

# 忽略构建输出目录
/dist/
/build/
/out/

# 忽略日志文件
*.log

# 忽略 node_modules 目录
/node_modules/

# 忽略特定文件
src/some-legacy-file.js
package-lock.json

# 忽略点文件（配置文件除外）
.*
!.prettierrc.json
!.prettierignore

# 忽略测试报告
/coverage/

5. 结合 ESLint 使用 (高级配置)

当 Prettier 与 ESLint 同时使用时，可能会出现格式化规则冲突（例如，ESLint 可能有一个规则要求使用双引号，而 Prettier 配置使用单引号）。为了解决这个问题，你需要安装并配置一些特定的 ESLint 插件。

1. 安装相关包：

   在你的项目目录中运行：

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

   或

   yarn add --dev eslint-config-prettier eslint-plugin-prettier
           

   • eslint-config-prettier：禁用所有与 Prettier 冲突的 ESLint 规则。
   • eslint-plugin-prettier：将 Prettier 格式化作为 ESLint 规则来运行，这样 ESLint 就能报告 Prettier 发现的格式问题。
2. 配置 .eslintrc.js 或 .eslintrc.json：

   在你的 ESLint 配置文件中，按以下顺序配置 extends 和 plugins：

   // .eslintrc.js
   module.exports = {
       extends: [
           // ...你的其他 ESLint 配置，例如 'eslint:recommended', 'plugin:vue/essential' 等
           'plugin:prettier/recommended' // 这一行应该放在最后！
       ],
       plugins: [
           // 'prettier' 插件通常会被 'plugin:prettier/recommended' 自动引入
           // 但如果需要手动引入，可以放在这里
       ],
       rules: {
           // 你可以在这里覆盖 Prettier 插件的默认规则，
           // 但通常不推荐，因为它可能会引入新的格式冲突。
           // 'prettier/prettier': 'error', // 这条规则通常由 'plugin:prettier/recommended' 自动添加
           // 'arrow-body-style': 'off',
           // 'prefer-arrow-callback': 'off'
       }
   };
           

   'plugin:prettier/recommended' 是一个复合配置，它等同于：

   • extends: ['prettier'] (即 eslint-config-prettier，禁用冲突规则)
   • plugins: ['prettier'] (即 eslint-plugin-prettier，将 Prettier 作为 ESLint 规则)
   • rules: { 'prettier/prettier': 'error', 'arrow-body-style': 'off', 'prefer-arrow-callback': 'off' } (启用 prettier/prettier 规则并将一些 ESLint 自身规则设置为 ‘off’ 以避免与 Prettier 冲突)
3. 在 VS Code 设置中启用保存时修复 (如果尚未设置)：

   确保你的 `settings.json` 中包含：

   {
       "editor.codeActionsOnSave": {
           "source.fixAll.eslint": true
       }
   }
           

这样配置后，保存文件时：

1. ESLint 会首先运行，修复它能自动修复的问题（包括 Prettier 规则发现的格式问题）。
2. 然后，Prettier 扩展会再次运行，确保代码完全符合 Prettier 的格式规范。

这个流程确保了格式化的一致性，并将格式问题视为 ESLint 错误报告出来，方便在 CI/CD 流程中进行检查。

6. 快捷键格式化

除了保存时自动格式化，你也可以手动触发格式化：

• Windows / Linux: Shift + Alt + F
• macOS: Shift + Option + F

如果你想格式化选中的代码块，可以先选中代码，然后按上述快捷键。

7. 禁用 Prettier (临时或永久)

• 临时禁用：

  打开命令面板 (Ctrl+Shift+P 或 Cmd+Shift+P)，输入“Format Document With…”，然后选择“Configure Default Formatter…”，再选择“None”。这会临时禁用当前文件的默认格式化器。

• 文件级别禁用：

  在文件顶部添加 Prettier 的忽略注释：

  // prettier-ignore
  function myFunction() {
      // 这段代码将不会被 Prettier 格式化
  }
  
  /* prettier-ignore */
  const someVar = "Hello";
          

  或者使用块级注释禁用特定区域：

  // prettier-ignore-start
  function complexCode() {
      // ...
  }
  // prettier-ignore-end
          

• 全局或工作区禁用：

  在你的用户或工作区 settings.json 中设置：

  {
      "prettier.enable": false
  }
          

  或者移除 editor.defaultFormatter 配置。

怎么？—— 实践与故障排除

在实际使用中，你可能会遇到一些问题。以下是一些常见的实践建议和故障排除技巧：

1. 确保 Prettier 扩展已启用且是最新的

定期检查 VS Code 扩展是否有更新，保持 Prettier 扩展为最新版本。如果遇到问题，可以尝试禁用再重新启用扩展。

2. 检查输出面板

如果 Prettier 没有按预期工作，打开 VS Code 的“输出”面板 (Ctrl+Shift+U 或 Cmd+Shift+U)，然后从下拉菜单中选择“Prettier”或“ESLint”。这里会显示 Prettier 和 ESLint 在格式化过程中遇到的错误或警告信息，这对于定位问题非常有帮助。

3. 理解配置优先级

回顾“在哪里？”部分提到的优先级。如果你的代码格式不符合预期，很可能是某个更高优先级的配置覆盖了你的设置。

• 如果你设置了 .prettierrc.json，VS Code 扩展会自动读取它。
• 如果你在 settings.json 中直接配置了 "prettier.singleQuote": true，但 .prettierrc.json 中是 "singleQuote": false，那么 .prettierrc.json 的设置会生效。

4. 确保项目安装了 Prettier 包

虽然 VS Code 扩展自带了 Prettier，但最佳实践是在你的项目中局部安装 Prettier 包：

npm install --save-dev prettier

或

yarn add --dev prettier

这样做可以确保项目使用特定版本的 Prettier，避免不同开发者之间因为 Prettier 版本差异导致格式化结果不一致。同时，像 ESLint 这样的工具也需要项目本地安装的 Prettier 模块来运行。

5. 检查文件类型关联

确保你的文件类型被 Prettier 正确识别并格式化。例如，如果你有一个自定义的文件扩展名，你可能需要在 settings.json 中配置：

{
    "files.associations": {
        "*.myjs": "javascript" // 将 .myjs 文件识别为 javascript
    }
}

6. 与其他 VS Code 扩展的冲突

有时，其他格式化或代码辅助扩展可能会与 Prettier 产生冲突。尝试临时禁用其他相关扩展，以排除它们是问题来源的可能性。

7. 使用 Prettier CLI 进行调试

你可以在命令行中直接运行 Prettier，以验证配置是否生效，这对于排除 VS Code 扩展层面的问题很有用。

# 检查某个文件是否符合 Prettier 规范（不修改文件）
npx prettier --check "src/App.js"

# 格式化某个文件
npx prettier --write "src/App.js"

# 检查所有文件
npx prettier --check .

# 格式化所有文件
npx prettier --write .

如果命令行工具能够正确格式化，但 VS Code 不能，那么问题可能出在 VS Code 扩展配置上。

8. 统一团队配置

对于团队项目，将 .prettierrc.json 和 .prettierignore 文件提交到版本控制系统（如 Git）是非常重要的。这确保了所有团队成员在保存代码时都使用相同的格式化规则，从而维护代码库的一致性。

建议在项目的 package.json 中添加脚本来执行 Prettier 检查（例如在 CI/CD 流程中）：

// package.json
{
    "scripts": {
        "format": "prettier --write .",
        "check-format": "prettier --check ."
    }
}

然后团队成员可以运行 npm run format 来格式化整个项目，或在 CI 中运行 npm run check-format 来确保提交的代码符合格式规范。

结语

通过上述详细的配置和实践指南，你应该能够全面掌握 VS Code Prettier 的使用。它将成为你和团队提升代码质量、减少摩擦的利器。投入少量时间进行配置，将为你带来长期的代码一致性、开发效率和团队协作收益。