Prettier 代码格式化工具 for Visual Studio Code

Prettier 是一款极具主见的代码格式化工具。它通过解析代码并按照自身规则重新排版，确保代码风格的一致性。这些规则会充分考虑最大行长度，在必要时自动换行。

JavaScript · TypeScript · Flow · JSX · JSON
CSS · SCSS · Less
HTML · Vue · Angular HANDLEBARS · Ember · Glimmer
GraphQL · Markdown · YAML
你喜爱的语言是否在列？

安装

通过 VS Code 扩展进行安装。搜索 Prettier - Code formatter

Visual Studio Code 市场：Prettier - Code formatter

也可在 VS Code 中安装：启动 VS Code 快速打开（Ctrl+P），粘贴以下命令，然后按回车键。

ext install esbenp.prettier-vscode

默认格式化程序

为确保此扩展优先于您可能已安装的其他扩展，请务必在 VS Code 设置中将其设为默认格式化程序。此设置可以针对所有语言或特定语言进行配置。

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

注意： VS Code 不支持为 editor.defaultFormatter 设置组合语言语法。你必须为每种语言单独设置格式化程序：

// ❌ This will NOT work
{
  "[javascript][typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

// ✅ Use separate blocks instead
{
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

如果你想在特定语言上禁用 Prettier，可以创建一个 .prettierignore 文件，或者使用 VS Code 的 editor.defaultFormatter 设置。

以下设置将对所有语言使用 Prettier，除了 JavaScript。

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "<another formatter>"
  }
}

以下将仅对 Javascript 使用 Prettier。

{
  "editor.defaultFormatter": "<another formatter>",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

此外，如果你不希望特定语言的代码被自动格式化，可以为这些语言禁用“保存时格式化”功能。

{
  "[javascript]": {
    "editor.formatOnSave": false
  }
}

Prettier 解析方式

此扩展将使用项目本地依赖中的 prettier（推荐方式）。当 prettier.resolveGlobalModules 设置为 true 时，扩展还可以尝试解析全局模块。如果项目的本地依赖或计算机的全局环境中均未安装 prettier，则将使用扩展自带的 prettier 版本。

如需在项目中安装 prettier 并固定其版本（正如推荐做法所述），请运行：

npm install prettier -D --save-exact

注意：系统会提示你确认是否允许扩展加载 Prettier 模块。这样做是为了确保你不会加载不受信任的模块或脚本。

Prettier 版本

此扩展默认捆绑了 Prettier 3.x。如果你的项目本地安装了 Prettier（位于 node_modules 中），则会使用该本地版本而非捆绑版本。这使你可以在项目中使用特定版本的 Prettier。

Prettier 2.x 兼容性：使用 Prettier 2.x 的项目仍然完全受支持。如果你的项目本地安装了 Prettier 2.x，扩展将自动使用该版本。

插件

当你使用本地或全局解析的 Prettier 版本时，此扩展支持 Prettier 插件。如果你的 package.json 中已注册了 Prettier 和某个插件，此扩展将尝试注册该语言，并为内置语言和插件语言提供自动代码格式化功能。

配置

有多种方式可为此扩展配置 Prettier。你可以使用 VS Code 设置、prettier 配置文件 或 .editorconfig 文件。VS Code 设置旨在作为备用选项，通常仅用于非项目文件。建议你始终在项目中包含一个 prettier 配置文件，指定项目的所有设置。 这样无论你是通过此扩展、命令行还是其他支持 Prettier 的 IDE 运行 prettier，都将应用相同的设置。

推荐使用 Prettier 配置文件 来设置格式化选项。系统会从正在格式化的文件开始向下递归搜索选项，因此如果你想将 prettier 设置应用于整个项目，只需在根目录中设置一个配置即可。也可以通过 VS Code 配置设置，但这些设置仅在运行扩展时生效，通过命令行运行 prettier 时则不生效。

配置默认选项

有些用户可能不希望为每个项目创建新的 Prettier 配置，也不想使用 VS Code 设置。若要设置默认配置，请设置 prettier.configPath。但请注意，一旦设置了该值，系统将始终使用此配置，而忽略本地配置文件。

Visual Studio Code 设置

您可以使用 VS Code 设置 来配置 prettier。设置的读取优先级如下（按优先级排序）：

1. Prettier 配置文件
2. .editorconfig
3. Visual Studio Code 设置（如果存在其他配置，则忽略此项）

注意：如果存在任何本地配置文件（例如 .prettierrc），则 不会 使用 VS Code 设置。

使用方法

使用命令面板（CMD/CTRL + Shift + P）

1. CMD + Shift + P -> Format Document
OR
1. Select the text you want to Prettify
2. CMD + Shift + P -> Format Selection

键盘快捷键

Visual Studio Code 提供了用于代码格式化的默认键盘快捷键。你可以在VS Code 文档中了解每个平台的这些快捷键。

如果你不喜欢默认快捷键，可以在 VS Code 的键盘快捷键菜单中重新绑定 editor.action.formatDocument 和 editor.action.formatSelection。

保存时格式化

遵循 editor.formatOnSave 设置。

你可以通过设置作用域，按语言单独开启保存时格式化功能：

// Set the default
"editor.formatOnSave": false,
// Enable per-language
"[javascript]": {
    "editor.formatOnSave": true
}

格式化选中内容

格式化选中内容功能支持多种语言，具体取决于 Prettier 本身支持的语言。目前支持以下语言：

javascript
javascriptreact
typescript
typescriptreact
json
graphql
handlebars

格式化文档（强制）

如果您想要格式化一个已配置为被 Prettier 忽略的文档（无论是因为它位于 .prettierignore 文件中，还是属于 node_modules 等通常被排除的位置），您可以运行 格式化文档（强制） 命令来强制格式化该文档。强制模式还会忽略 requirePragma 的任何配置，允许您在没有编译指示注释的情况下格式化文件。

与 linter 集成

与 linter 集成的推荐方式是让 Prettier 负责格式化，并将 linter 配置为不处理格式化规则。您可以在 Prettier 文档网站上找到如何配置各个 linter 的说明。然后，您可以像往常一样使用每个 linting 扩展。有关详细信息，请参阅 Prettier 文档。

在保存时使用代码操作

您可以使用 VS Code 的 editor.codeActionsOnSave 在其他格式化程序（如 ESLint）之前运行 Prettier。当您希望先使用 Prettier 格式化，然后再应用 ESLint 修复时，这非常有用。

// .vscode/settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.prettier": "explicit",
  },
}

你也可以将 Prettier 与 ESLint 结合使用：

// .vscode/settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.prettier": "explicit",
    "source.fixAll.eslint": "explicit",
  },
}

注意： source.fixAll.prettier 代码操作会遵循你的 editor.defaultFormatter 设置。如果你已设置了其他默认格式化程序（例如，带有 Prettier 插件的 ESLint），则 Prettier 代码操作不会运行，除非你通过 "source.fixAll.prettier": "explicit" 或 "source.fixAll.prettier": "always" 显式启用它。这可以防止在使用 eslint-plugin-prettier 等设置时出现双重格式化的情况。

工作区信任

此扩展利用了 VS Code 的 工作区信任 功能。当此扩展在不受信任的工作区上运行时，它将仅使用内置版本的 Prettier。不支持任何插件、本地或全局模块。此外，某些设置也会受到限制——详情请参见各个设置说明。

设置

Prettier 设置

所有 Prettier 选项都可以直接在此扩展中进行配置。当你的项目中没有配置文件时，这些设置将作为回退选项，有关更多详细信息，请参阅本文档的 配置 部分。有关选项的参考，请参阅 Prettier 文档。

这些配置的默认值与 Prettier 3.0 的默认值一致。与 Prettier 2.x 相比的显著变化：trailingComma 现在默认为 "all"，而不是 "es5"。

prettier.arrowParens
prettier.bracketSpacing
prettier.endOfLine
prettier.htmlWhitespaceSensitivity
prettier.insertPragma
prettier.singleAttributePerLine
prettier.bracketSameLine
prettier.jsxBracketSameLine
prettier.jsxSingleQuote
prettier.printWidth
prettier.proseWrap
prettier.quoteProps
prettier.requirePragma
prettier.semi
prettier.singleQuote
prettier.tabWidth
prettier.trailingComma
prettier.useTabs
prettier.vueIndentScriptAndStyle
prettier.embeddedLanguageFormatting
prettier.experimentalTernaries
prettier.objectWrap
prettier.experimentalOperatorPosition

语言特定格式化

上述所有 Prettier 选项均支持语言特定的覆盖配置。这使你能够直接在 VS Code 设置中为不同文件类型设置不同的格式化规则，这些设置可轻松在多台机器和环境之间同步。

要配置语言特定设置，请在 VS Code 的 settings.json 中使用 [language] 语法：

{
  "[html]": {
    "prettier.printWidth": 180
  },
  "[typescript]": {
    "prettier.printWidth": 120,
    "prettier.tabWidth": 4,
    "prettier.semi": false
  },
  "[json]": {
    "prettier.printWidth": 80,
    "prettier.tabWidth": 2
  }
}

此功能在多语言项目中，或者当不同语言有不同的格式约定时特别有用。特定语言的设置在格式化该语言类型的文件时，会覆盖 Prettier 的全局设置。

扩展设置

这些设置是 VS Code 特有的，需要在 VS Code 设置文件中进行配置。有关操作方法，请参阅文档。

prettier.enable（默认值：true）

控制是否启用 prettier。更改此设置后，必须重启 VS Code。

prettier.requireConfig（默认值：false）

要求使用 prettier 配置文件来格式化文件。即使此选项设置为 true，未命名文件仍将使用 VS Code Prettier 配置进行格式化。

prettier.ignorePath（默认值：.prettierignore）

指定忽略文件的路径，例如 .gitignore 或 .prettierignore。 匹配的文件将不会被格式化。设置为 null 则不读取忽略文件。

注意，如果设置了此选项，将始终使用该值，并且会忽略本地忽略文件。

在不受信任的工作区中禁用

prettier.configPath

指定 prettier 配置文件的自定义路径。

注意，如果设置了此选项，将始终使用该值，并且会忽略本地配置文件。设置全局默认值的更好方法是在主目录中放置一个 ~/.prettierrc 文件。

在不受信任的工作区中禁用

prettier.prettierPath

指定 prettier 模块的自定义路径。此路径应指向模块文件夹，而非 bin/脚本路径。例如，./node_modules/prettier，而不是 ./bin/prettier。

在不受信任的工作区中禁用

prettier.resolveGlobalModules（默认值：false）

启用后，如果无法解析本地模块，此扩展将尝试使用全局 npm 或 yarn 模块。

注意：此设置可能会对性能产生负面影响，尤其是在 Windows 系统上连接了网络驱动器时。仅在必须使用全局模块时才启用此选项。建议尽可能始终使用本地模块。

注意：在父文件夹中禁用已启用的语言将阻止格式化，而不是让其他格式化程序运行

在不受信任的工作区中禁用

prettier.documentSelectors

用于注册 Prettier 格式化程序的 glob 模式列表。通常，这些模式的格式为 **/*.abc，用于告知此扩展将自身注册为所有具有 abc 扩展名的文件的格式化程序。当你在配置文件中设置了覆盖以将自定义扩展名映射到解析器时，此功能非常有用。

你可能还需要更新你的 prettier 配置。例如，如果我单独注册以下文档选择器，Prettier 仍然不知道如何处理该文件。我要么需要一个能够格式化 .abc 文件格式的 Prettier 扩展，要么需要配置 Prettier。

{
  "prettier.documentSelectors": ["**/*.abc"]
}

要告诉 Prettier 如何格式化 .abc 类型的文件，我可以在 prettier 配置中设置一个覆盖规则，让该文件类型使用 babel 解析器。

{
  "overrides": [
    {
      "files": "*.abc",
      "options": {
        "parser": "babel"
      }
    }
  ]
}

在不受信任的工作区中禁用

prettier.useEditorConfig（默认值：true）

解析配置时是否考虑 .editorconfig。有关详细信息，请参阅 prettier.resolveConfig 文档。

在不受信任的工作区中禁用（始终为 false）

prettier.withNodeModules（默认值：false）

是否处理 node_modules 文件夹中的文件。

在不受信任的工作区中禁用

故障排除

有关常见问题的帮助，请参阅 故障排除指南，包括：

• Prettier 未格式化文件
• 意外的格式化结果
• 性能问题
• 插件问题
• 配置问题

常见错误消息

无法加载模块。如果您的 package.json 中引用了 prettier 或插件，请确保已运行 npm install

当项目中存在 package.json 且其中包含 prettier、插件或 linter 库时，此扩展将尝试从您的 node_module 文件夹加载这些模块。如果看到此错误，很可能意味着您需要运行 npm install、yarn install、pnpm install 等命令来安装 package.json 中的包。

您的项目配置使用的 prettier 版本已过时，无法与此扩展一起使用。请升级到最新版本的 prettier。

您必须升级到更新版本的 prettier。

此工作区不受信任。正在使用捆绑版本的 prettier。

您必须信任此工作区才能使用插件以及本地/全局模块。请参阅：工作区信任