Claude Code 中的 Prettier 配置实战指南

使用 Claude Code 写代码时，格式问题不能只当成“最后再整理”的小事。一次任务可能同时改组件、测试、JSON、Markdown 和 CI 配置。如果缩进、引号、换行、尾随逗号都混在同一个 diff 里，review 的注意力会被格式噪音抢走，真正的行为变化反而不容易看清。

Prettier 是一个代码格式化工具。更直白地说，它负责把代码的外观统一起来，例如空格、换行、缩进、引号和逗号，而不是判断业务逻辑是否正确。Claude Code 适合处理实现，但项目应该用明确的配置告诉它“这个仓库的格式标准是什么”。

这篇文章会从零搭好一套适合 Claude Code 的 Prettier 配置：安装 Prettier、编写 .prettierrc、维护 .prettierignore、添加 npm scripts、配置 VS Code、接入 CI、只格式化 staged files，并把规则写进 Claude Code 的项目指令。示例都按常见 npm + TypeScript 项目来写，可以直接复制后微调。

整体流程

不要把 Prettier 当成偶尔手动运行的清理命令。更稳的做法是，把它放进开发流程的几个关键节点。

flowchart LR
  A["Claude Code 修改文件"] --> B[".prettierrc 定义规则"]
  B --> C["VS Code 保存时格式化"]
  C --> D["npm run format:check"]
  D --> E["lint-staged 处理 staged files"]
  E --> F["CI 阻止未格式化代码"]

.prettierrc负责团队格式规则，.prettierignore负责哪些文件不能被改，package.json scripts 负责让人、Claude Code 和 CI 使用同一套命令。VS Code 负责写代码时的即时反馈，lint-staged 负责提交前只处理本次提交的文件，CI 负责最后拦住漏掉的格式问题。

Claude Code 不是不能理解“保持格式统一”，但这种要求不应该只存在于聊天记录里。把规则写进仓库，才能让每次会话、每个成员、每个 CI 环境都得到一致结果。

本地安装 Prettier

Prettier 应该安装在项目本地，而不是依赖全局版本。官方的 Prettier Install 建议使用本地安装并固定版本，这样开发者机器、Claude Code 环境和 CI 都会使用同一个格式化器。

npm install --save-dev --save-exact prettier

第一次引入时，可以先跑一次全量格式化。

npx prettier . --write

如果是已经上线的项目，请把这次全量格式化单独做成一个 commit 或 PR。不要把它和功能修改混在一起。否则几百行格式变化会遮住真正的业务变更，回滚和排查也会变麻烦。

编写 .prettierrc

Prettier 支持多种配置文件，例如 .prettierrc、prettier.config.mjs，以及 package.json 里的 prettier 字段。官方的 Configuration File 说明，Prettier 会从被格式化文件所在目录向上查找配置，并且不支持全局配置，这样项目复制到另一台机器后仍能得到同样结果。

团队刚开始使用时，JSON 格式的 .prettierrc 最容易读。

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "all",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "proseWrap": "always"
      }
    },
    {
      "files": ["*.yml", "*.yaml"],
      "options": {
        "singleQuote": false
      }
    }
  ]
}

printWidth不是硬性的最大长度，而是 Prettier 判断是否换行的参考值。endOfLine: "lf"可以减少 Windows、macOS、Linux 和 CI 之间的换行差异。trailingComma: "all"通常能让以后新增数组项或对象字段时 diff 更小。

如果项目大量使用 Tailwind CSS，可以之后考虑 prettier-plugin-tailwindcss。但一开始不要把插件加太多。先让基础 Prettier 稳定运行，再根据真实需求增加插件，排错会容易很多。

用 .prettierignore 保护不该改的文件

.prettierignore 用来告诉 Prettier 哪些文件不要格式化。构建产物、缓存、生成代码、压缩文件、包管理器维护的锁文件，都不应该因为一次普通代码修改而被重写。

node_modules
dist
build
coverage
.next
.nuxt
.astro
.vercel
.cache
*.min.js
package-lock.json
pnpm-lock.yaml
yarn.lock

Prettier 在同一执行目录下也会参考 .gitignore，但两者目的不同。.gitignore 说明哪些文件不进 Git，.prettierignore 说明哪些文件不应该被格式化。生成物最好在 .prettierignore 中明确写出来，这样 Claude Code 也更容易理解边界。

常见失败例是忘记忽略自动生成的 API client。Claude Code 只改了一个页面，prettier . --write 却把 src/generated/ 下几千行都改了。生成代码应该改源 schema 后重新生成，而不是让格式化器随手重排。

添加 npm scripts

npm 官方文档把 scripts 定义为 package 中可运行命令的入口。对 Claude Code 来说，这一点很重要，因为你可以让人、代理和 CI 都说同一种语言。

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

本地修复用写入命令，自动化环境用检查命令。

npm run format
npm run format:check

format 会修改文件，format:check 只检查是否已经格式化。CI 中建议只跑 format:check，不要让 CI 悄悄改文件。失败后回到本地运行 npm run format，再提交新的 diff，团队更容易理解发生了什么。

配置 VS Code

保存时自动格式化可以把问题拦在 commit 之前。建议把配置放进仓库的 .vscode/settings.json，而不是依赖每个人自己的编辑器偏好。

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.requireConfig": true,
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[mdx]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

prettier.requireConfig 设置为 true 后，只有存在 Prettier 配置的项目才会启用 Prettier。经常切换多个仓库的开发者尤其应该打开它，避免在不使用 Prettier 的项目中产生意外格式变化。

在 CI 中检查格式

GitHub Actions 的最小配置如下。

name: format

on:
  pull_request:
  push:
    branches: [main]

jobs:
  prettier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run format:check

当 Claude Code 帮你改 PR 时，这个检查很有价值。reviewer 看到代码前，CI 就会先挡住未格式化文件。若还需要质量规则，可以继续结合 Claude Code ESLint 配置指南，但建议把格式检查和 lint 检查分开，失败原因会更清楚。

只格式化 staged files

大型项目每次都跑 prettier . --write 会比较慢，也可能带出历史格式债。用 Husky 和 lint-staged 可以只处理本次 git add 的文件。完整 pre-commit 流程可以参考 Husky + lint-staged 配置指南，这里只给 Prettier 的最小配置。

npm install --save-dev --save-exact husky lint-staged
npm pkg set scripts.prepare="husky"
npx husky init

在 package.json 中添加：

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,css,md,mdx,json,yml,yaml}": "prettier --write"
  }
}

.husky/pre-commit 保持简单即可。

npx lint-staged

这样 Claude Code 改了 3 个文件，提交前也只会格式化这 3 个文件。既能保证质量，又不会突然把旧文件全部重排。

让 Claude Code 遵守格式规则

Claude Code 的项目规则建议写进 CLAUDE.md。官方 Claude Code memory 文档 说明，./CLAUDE.md 或 ./.claude/CLAUDE.md 可以保存团队共享的项目指令，例如构建命令、编码规范和常用工作流。

## Formatting

- Read `.prettierrc` and `.prettierignore` before formatting files.
- Do not reformat unrelated files while implementing a feature.
- After changing JavaScript, TypeScript, CSS, Markdown, JSON, or YAML, run `npm run format:check`.
- Keep formatter-only changes separate from behavior changes.

如果想进一步自动化，可以使用 Claude Code hooks。官方 hooks guide 提供了在 Edit|Write 之后运行 Prettier 的示例。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

这个 hook 很方便，但依赖 jq 和 shell 环境。Windows 团队可以先只写 CLAUDE.md，要求 Claude Code 在任务结束时运行 npm run format:check。等大家环境一致后，再把 hook 加进共享配置。

三个实用场景

场景	Prettier 的价值	给 Claude Code 的提示
TypeScript 产品应用	组件、测试、类型工具的 diff 更干净	修改后运行 npm run format:check
Astro 或 MDX 内容站	frontmatter、Markdown、代码块和 JSON 风格一致	确认 MDX code fence 没有损坏
团队 PR review	reviewer 可以专注功能变化	不要把纯格式化 diff 混进功能修改

我最常见的收益来自 MDX 文章。一个文件里有正文、frontmatter、命令行、JSON 和 JSX 片段，手写或让 Claude Code 改都容易出现格式摇摆。Prettier 稳定后，review 的重点会回到文章准确性和示例是否可运行。

常见坑

第一，不安装 Prettier，只临时用 npx prettier . --write。如果依赖里没有固定版本，npx 可能临时下载当前最新版，导致某天格式结果突然变化。

第二，让 ESLint 和 Prettier 管同一件事。Prettier 管格式，ESLint 管潜在 bug 和质量规则。若 ESLint 中还保留大量格式规则，可以考虑 eslint-config-prettier 来关闭冲突项。

第三，在功能 PR 里顺手全量格式化。旧项目最好先做一次 formatter-only 变更，再开始业务改动。这样 Claude Code 后续产生的 diff 更容易读。

第四，.prettierignore 写得太宽。比如忽略 src/**，就等于放弃主要代码的格式一致性。只忽略生成物、缓存、大文件和外部工具维护的文件。

变现提示

如果你把 Claude Code 用在多个项目里，真正可复用的不只是 .prettierrc，而是整套协作流程：CLAUDE.md、检查命令、review checklist、PR 模板和交接规则。ClaudeCodeLab 在产品页面整理了这些模板，可以把本文配置扩展成团队标准。

总结

Prettier 是 Claude Code 工作流里的基础设施。先本地安装并固定版本，再用 .prettierrc 定义规则，用 .prettierignore 排除不该改的文件，用 format 和 format:check 暴露命令，然后接入 VS Code、lint-staged 和 CI。最后把同样的要求写进 CLAUDE.md，让 Claude Code 的输出和团队习惯保持一致。

实际测试结果：把这套配置应用到一个小型 TypeScript/MDX 项目后，第一次全量格式化建立了干净基线，之后 npm run format:check 可以稳定通过。Claude Code 修改文章和组件后的 diff 明显更容易 review，尤其是忽略生成物和区分 format 与 format:check 这两点最有帮助。