Prettier 完全指南：统一代码格式化的最佳实践

Prettier 是 JavaScript、TypeScript、HTML、CSS、JSON、Markdown 等语言中使用最广泛的固执己见的代码格式化工具。它通过解析代码并按自己的规则重新输出来强制一致的代码风格，消除了代码审查中关于格式的争论。Prettier 每周 npm 下载量超过 5000 万次，已成为现代开发工具链的重要组成部分。本指南涵盖从基本设置和配置到 ESLint 集成、编辑器插件、预提交钩子、CI/CD 强制执行、自定义插件等高级主题。

什么是 Prettier，为什么要使用它？

Prettier 是一个固执己见的代码格式化工具，它移除所有原始样式并确保所有输出代码符合一致的风格。与报告问题让你修复的 Linter 不同，Prettier 接收你的代码，将其解析为抽象语法树（AST），然后根据其格式化规则从头重新输出。

Prettier 的关键洞察是：争论代码格式是浪费时间。通过采用配置选项最少的固执己见的格式化工具，团队消除了代码审查中的风格争论，将精力集中在逻辑、架构和设计决策上。

Prettier 不同于传统格式化工具，因为它在做格式化决策时考虑整个程序结构。它理解行长度预算，会将长行拆分为多行，同时尊重语言特定的语法规则。

安装和设置 Prettier

Prettier 可以作为项目依赖安装或全局使用。推荐做法是在每个项目中作为 devDependency 安装，以确保所有团队成员使用相同版本。

# Install Prettier as a dev dependency
npm install --save-dev prettier

# Or with yarn
yarn add --dev prettier

# Or with pnpm
pnpm add --save-dev prettier

# Or with bun
bun add --dev prettier

安装后，你可以从命令行运行 Prettier。最常用的命令是就地格式化文件、检查文件是否已格式化，以及格式化特定文件类型。

# Format all files in the current directory
npx prettier --write .

# Check if files are formatted (no changes made)
npx prettier --check .

# Format specific file types
npx prettier --write "src/**/*.{ts,tsx,js,jsx}"
npx prettier --write "**/*.{css,scss,less}"
npx prettier --write "**/*.{json,md,yaml,yml}"

# Format a single file
npx prettier --write src/app.tsx

# Output formatted code to stdout (no file changes)
npx prettier src/app.tsx

使用 .prettierrc 配置

Prettier 设计为以最少的配置工作。不过它提供了一组可自定义的选项来匹配团队偏好。配置可以在多种文件格式中指定：.prettierrc（JSON 或 YAML）、.prettierrc.json、.prettierrc.yml、.prettierrc.toml、.prettierrc.js 或 package.json 中的 prettier 键。

以下是最常用的 Prettier 选项及其默认值。大多数团队只需要更改其中 3 到 5 个选项。

// .prettierrc (JSON format - most common)
{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

# .prettierrc (YAML format)
printWidth: 100
tabWidth: 2
useTabs: false
semi: true
singleQuote: true
trailingComma: all
bracketSpacing: true
arrowParens: always
endOfLine: lf

// prettier.config.mjs (ES module format)
/** @type {import("prettier").Config} */
const config = {
  printWidth: 100,
  tabWidth: 2,
  singleQuote: true,
  trailingComma: "all",
  arrowParens: "always",
  plugins: ["prettier-plugin-tailwindcss"],
};

export default config;

完整选项参考

使用 .prettierignore 忽略文件

.prettierignore 文件与 .gitignore 工作方式完全相同。它告诉 Prettier 跳过哪些文件和目录。默认情况下，Prettier 忽略 node_modules 中的文件。你还应该忽略构建输出、生成的文件和其他工具管理的文件。

# .prettierignore

# Build output
dist/
build/
.next/
out/

# Dependencies
node_modules/

# Lock files
package-lock.json
yarn.lock
pnpm-lock.yaml

# Generated files
*.min.js
*.min.css
*.generated.*
coverage/

# Environment files
.env
.env.*

# Public assets
public/
static/

你也可以使用特殊注释忽略文件内的特定行或块。这对于必须保持特定格式的代码很有用。

// prettier-ignore - ignores the next node
const matrix = [
  // prettier-ignore
  [1, 0, 0,
   0, 1, 0,
   0, 0, 1],
];

/* In HTML: */
<!-- prettier-ignore -->
<div   class="custom-alignment"   data-value="keep"  >
  Content here
</div>

/* In CSS: */
/* prettier-ignore */
.my-class    { color:   red; }

/* In Markdown: */
<!-- prettier-ignore-start -->
| Column 1    | Column 2    | Column 3    |
| ----------- | ----------- | ----------- |
| Aligned     | Content     | Here        |
<!-- prettier-ignore-end -->

与 ESLint 集成

Prettier 和 ESLint 服务于不同目的。ESLint 捕获代码质量问题，而 Prettier 处理格式化。挑战在于 ESLint 也有格式化规则可能与 Prettier 冲突。解决方案是 eslint-config-prettier，它禁用所有与 Prettier 冲突的 ESLint 规则。

2026 年推荐的设置使用 ESLint 扁平配置配合 eslint-config-prettier，确保 ESLint 处理代码质量而 Prettier 处理格式化。

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

// eslint.config.js - ESLint + Prettier (flat config)
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import prettierConfig from "eslint-config-prettier";

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,

  // Custom code quality rules
  {
    rules: {
      "no-unused-vars": "warn",
      "prefer-const": "error",
      "no-console": ["error", { allow: ["warn", "error"] }],
    },
  },

  // MUST be last: disables formatting rules that conflict with Prettier
  prettierConfig,
];

以前有些团队使用 eslint-plugin-prettier 将 Prettier 作为 ESLint 规则运行。现在不推荐这种方式，因为它更慢且产生嘈杂的输出。推荐将 ESLint 和 Prettier 作为独立工具运行。

// package.json - Run ESLint and Prettier as separate scripts
{
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint --fix src/",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "check": "npm run lint && npm run format:check"
  }
}

编辑器集成

Prettier 与所有主流代码编辑器集成。保存时格式化是最高效的工作流程：每次保存文件时，Prettier 自动格式化它。

VS Code

Prettier VS Code 扩展拥有超过 4000 万次安装。从 VS Code 扩展市场安装并配置保存时格式化。

// .vscode/settings.json
{
  // Set Prettier as the default formatter
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // Format on save
  "editor.formatOnSave": true,

  // Per-language formatter overrides
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

JetBrains IDE（WebStorm、IntelliJ）

JetBrains IDE 内置 Prettier 支持。在设置 > 语言和框架 > JavaScript > Prettier 中启用，勾选保存时和重新格式化时复选框。

// JetBrains Prettier settings path:
// Settings > Languages & Frameworks > JavaScript > Prettier
//
// Configuration:
// - Prettier package: ~/project/node_modules/prettier
// - Run for files: **/*.{js,ts,jsx,tsx,css,scss,json,md,yaml,yml,html}
// - [x] On Save
// - [x] On Reformat Code (Ctrl+Alt+L / Cmd+Opt+L)

Vim / Neovim

使用 neoformat 插件或内置 formatprg 选项来集成 Prettier。

-- Neovim with conform.nvim (recommended)
-- ~/.config/nvim/lua/plugins/formatting.lua
return {
  "stevearc/conform.nvim",
  opts = {
    formatters_by_ft = {
      javascript = { "prettier" },
      typescript = { "prettier" },
      typescriptreact = { "prettier" },
      css = { "prettier" },
      html = { "prettier" },
      json = { "prettier" },
      yaml = { "prettier" },
      markdown = { "prettier" },
    },
    format_on_save = {
      timeout_ms = 3000,
      lsp_fallback = true,
    },
  },
}

使用 Husky 和 lint-staged 的预提交钩子

编辑器集成在开发过程中捕获大多数格式问题，但预提交钩子提供安全网。它们确保仓库中的每次提交都正确格式化。标准方式使用 husky 处理 Git 钩子，lint-staged 仅在暂存文件上运行 Prettier。

# Step 1: Install husky and lint-staged
npm install --save-dev husky lint-staged

# Step 2: Initialize husky
npx husky init

# Step 3: Update the pre-commit hook
echo "npx lint-staged" > .husky/pre-commit

// package.json - lint-staged configuration
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "prettier --write",
      "eslint --fix"
    ],
    "*.{css,scss,less}": [
      "prettier --write"
    ],
    "*.{json,md,yaml,yml,html}": [
      "prettier --write"
    ]
  }
}

此设置在每个匹配模式的暂存文件上运行 Prettier。如果 Prettier 更改了文件，lint-staged 自动将更改添加到提交中。

CI/CD 管道集成

虽然预提交钩子在本地捕获大多数格式问题，CI/CD 提供最终的强制层。prettier --check 命令验证所有文件是否已格式化，而不修改它们。

# .github/workflows/format-check.yml
name: Format Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci

      - name: Check formatting
        run: npx prettier --check .

      - name: Run ESLint
        run: npx eslint src/

在 CI 中运行 Prettier 确保即使开发者跳过预提交钩子（使用 git commit --no-verify），格式化要求仍在代码合并前强制执行。

# GitLab CI - .gitlab-ci.yml
format-check:
  stage: test
  image: node:22
  cache:
    paths:
      - node_modules/
  script:
    - npm ci
    - npx prettier --check .
    - npx eslint src/

Prettier 插件

Prettier 的插件系统扩展了语言支持和功能。插件可以添加新语言、修改现有格式化行为或添加全新功能。最受欢迎的社区插件包括 Tailwind CSS 类排序、SQL 格式化和 PHP 格式化。

# Install popular Prettier plugins

# Tailwind CSS - sorts Tailwind classes automatically
npm install --save-dev prettier-plugin-tailwindcss

# Sort imports
npm install --save-dev @trivago/prettier-plugin-sort-imports

# PHP formatting
npm install --save-dev @prettier/plugin-php

# XML formatting
npm install --save-dev @prettier/plugin-xml

# SQL formatting
npm install --save-dev prettier-plugin-sql

插件作为 npm 包安装，在 .prettierrc 文件中使用 plugins 数组配置。

// .prettierrc - with plugins configured
{
  "printWidth": 100,
  "singleQuote": true,
  "trailingComma": "all",
  "plugins": [
    "prettier-plugin-tailwindcss",
    "@trivago/prettier-plugin-sort-imports"
  ],
  "importOrder": [
    "^react",
    "^next",
    "<THIRD_PARTY_MODULES>",
    "^@/(.*)$",
    "^[./]"
  ],
  "importOrderSeparation": true,
  "importOrderSortSpecifiers": true
}

固执己见的格式化哲学

Prettier 故意提供极少的配置选项。这不是限制，而是核心设计决策。Prettier 团队观察到更多选项导致更多争论、更多不一致，以及更多时间花在配置而非编写代码上。

当团队采用 Prettier 时，他们同意接受其决策。初始适应期很短：大多数开发者几天后就不再注意格式化。好处是永久的：不再讨论制表符还是空格、括号放在哪里。

• 更少的选项意味着更少的配置时间和更多的编码时间。
• 项目中所有文件的一致格式化，无论谁编写。
• 代码审查中没有格式讨论，可以专注于逻辑和架构。
• 新团队成员可以立即开始编码，无需学习风格指南。
• 多个项目使用相同的最小 Prettier 配置时的跨项目一致性。

按文件和按语言覆盖

Prettier 允许使用 .prettierrc 中的 overrides 字段为特定文件或文件类型应用不同的配置选项。这在项目不同部分需要不同格式化规则时很有用。

// .prettierrc - with per-file overrides
{
  "printWidth": 80,
  "singleQuote": true,
  "trailingComma": "all",
  "overrides": [
    {
      "files": "*.html",
      "options": {
        "printWidth": 120
      }
    },
    {
      "files": "*.md",
      "options": {
        "proseWrap": "always",
        "printWidth": 80
      }
    },
    {
      "files": ["*.json", "*.jsonc"],
      "options": {
        "tabWidth": 4
      }
    },
    {
      "files": "*.css",
      "options": {
        "singleQuote": false
      }
    }
  ]
}

Prettier 与其他格式化工具对比

了解 Prettier 与其他格式化工具的对比有助于为项目选择合适的工具。

Prettier 在 2026 年仍是行业标准，因为其广泛的语言支持、插件生态和通用编辑器集成。Biome 对于只需 JS/TS 格式化且追求速度的团队是一个强有力的替代方案。

将项目迁移到 Prettier

在现有项目中采用 Prettier 需要一次性格式化提交，会涉及很多文件。推荐方式是在一次提交中格式化整个代码库，然后配置预提交钩子和 CI/CD。

# Step 1: Install Prettier
npm install --save-dev prettier

# Step 2: Create minimal config
echo '{ "singleQuote": true, "trailingComma": "all" }' > .prettierrc

# Step 3: Create .prettierignore
echo "dist/\nbuild/\nnode_modules/\npackage-lock.json" > .prettierignore

# Step 4: Format entire codebase
npx prettier --write .

# Step 5: Commit the formatting change
git add -A
git commit -m "style: format codebase with Prettier"

为了减少迁移提交对 git blame 的影响，使用 .git-blame-ignore-revs 文件配置 git 忽略格式化提交。

# .git-blame-ignore-revs
# Prettier initial formatting
abc123def456789...

# Tell git to use this file
git config blame.ignoreRevsFile .git-blame-ignore-revs

# GitHub automatically reads .git-blame-ignore-revs
# so the formatting commit is hidden in blame views

最佳实践

遵循以下建议从 Prettier 中获得最大价值。

• 在每个项目中将 Prettier 作为 devDependency 安装，而非依赖全局安装。
• 保持 .prettierrc 最小化。自定义的选项越少，越接近社区标准。
• 在编辑器中使用保存时格式化，这是 Prettier 提供的最具影响力的工作流改进。
• 使用 husky 和 lint-staged 设置预提交钩子作为安全网。
• 在 CI/CD 管道中添加 prettier --check 作为最终的格式化强制层。
• 使用 .prettierignore 跳过生成的文件、构建输出和第三方代码。
• 迁移现有项目时，在一次提交中格式化所有内容并添加到 .git-blame-ignore-revs。
• 将 Prettier 和 ESLint 作为独立工具运行，不要使用 eslint-plugin-prettier。
• 在 package.json 中固定 Prettier 版本以避免意外的格式变更。
• 使用 .prettierrc 中的 overrides 字段为需要不同格式规则的文件配置，而不是完全禁用 Prettier。

常见问题