企业官网建设流程全解析

Prettier CI 集成实践：在 GitHub Actions 中自动修复代码格式

【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier

本文基于 Prettier 仓库的 docs/ci.md 文档，讲解如何在 GitHub Actions 中运行 Prettier 自动修复（autofix）流程，并结合仓库自身的 CI 工作流、package.json脚本与 CLI 实现，说明版本固定、--check/--write/--cache等关键参数在持续集成环境中的实际用法。读完本文，你可以为自己的仓库搭建一套“提交即检查、检查不过自动修复”的 Prettier CI 流水线，并理解 Prettier 官方仓库是如何组织这些检查步骤的。

核心方案：GitHub Actions + autofix.ci

Prettier 官方文档给出的 CI 集成方案由两部分组成：

1. autofix.ci GitHub App：安装到仓库后，当工作流运行prettier . --write产生文件变更时，它会自动把变更以 commit 形式提交回 PR，实现“自动修复”。
2. 一个最小化的 workflow 文件，内容如下（完整继承自 docs/ci.md）：

name: autofix.ci on: pull_request: push: permissions: {} jobs: prettier: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 - run: | yarn yarn prettier . --write - uses: autofix-ci/action@v1 with: commit-message: "Apply Prettier format"

逐行说明这个 workflow 的要点：

这个方案的关键在于：修复动作发生在 CI 侧并回写 PR，而不是在开发者本地，因此团队无需依赖每个人都配置好编辑器插件或 pre-commit 钩子，也能保证合入的代码符合 Prettier 格式。

为什么必须固定（pin）Prettier 版本

文档明确要求：仓库中必须安装一个固定版本的 Prettier。原因是 Prettier 是“有主见的格式化器”（opinionated formatter），不同版本对部分语法（如换行、空格策略）的判定可能存在差异。如果 CI 中使用浮动版本，格式结果会随版本漂移——今天--check通过的代码，明天 Prettier 升级后可能被判为“未格式化”，造成无意义的 CI 失败与来回修改。

Prettier 官方仓库本身就是版本固定的实践样板：

• 其开发依赖中 Prettier 被固定为精确版本3.9.7（见 package.json 的devDependencies），而仓库自身处于3.10.0-dev的开发状态——即用已发布的固定版本校验开发中代码的格式，避免“自己测自己”的版本漂移；
• 根 package.json 声明了packageManager: yarn@4.18.0与engines.node >= 22，CI 中的依赖安装步骤因此是可复现的；
• 仓库的 lint 工作流 在actions/setup-node步骤中同时固定了 Action 版本（通过 commit SHA 注释锁定v7.0.0/v7.0.1）和 Node 版本，并配合yarn --immutable安装依赖——--immutable会在校验yarn.lock未被篡改时才允许安装，进一步保证 CI 构建的可复现性。可以推断，把 Action、Node、依赖锁文件一并固定，是官方 CI 稳定的前提，而不只是固定 Prettier 一个版本号。

CI 中 Prettier 的常用命令与参数

docs/ci.md给出的--write是自动修复路径；而在“只检查、不修改”的 CI 门禁场景下，通常使用--check。两者在 Prettier 仓库中的用法可以直接从源码与配置中印证：

--check：CI 门禁模式

对 docs/cli.md 的说明，prettier . --check（或-c）会检查所有文件是否已符合 Prettier 格式，存在未格式化文件时以非零退出码结束，因此可以直接作为 CI 的阻塞步骤。

Prettier 仓库的 lint 工作流 正是这样做的：

- name: Lint Prettier run: yarn lint:prettier

该脚本在 package.json 中定义为：

"lint:prettier": "prettier . --check --cache"

它只对main、next、v*、patch-release分支的 push 以及 PR 触发（renovate 分支除外），与测试工作流 dev-test.yml 的触发分支保持一致，形成统一的门禁面。

工作流中还有一个更细粒度的例子，专门检查文档代码块的格式正确性：

- name: Lint docs code block run: yarn prettier "{docs,website/versioned_docs/version-stable}/**/*.md" --check env: # Make Prettier throws on embedded format PRETTIER_DEBUG: true

可以看到：在 CI 中按文件模式缩小--check的范围是常规操作；PRETTIER_DEBUG环境变量用于让 Prettier 在嵌入代码块（如 Markdown 中的 fenced code block）格式化出错时直接抛错，避免“静默跳过”造成漏检。

--write与--cache：修复与提速

• --write（-w）：把格式化结果写回文件，是 autofix 类工作流的核心命令。
• --cache：只格式化发生变化的文件。缓存键包含文件哈希，策略由--cache-strategy决定：metadata（默认，基于文件时间戳等元数据）或content（基于文件内容，见 docs/cli.md 与 src/cli/cli-options.evaluate.js 中的选项定义）。Prettier 仓库在lint:prettier脚本中直接启用了--check --cache，用缓存加速全仓检查。
• 默认缓存文件位于./node_modules/.cache/prettier/.prettier-cache，可用--cache-location指定自定义位置；不带--cache运行 Prettier 会删除旧缓存，更新插件后也建议清理缓存（插件版本不作为缓存键）。

对于在 CI 中使用缓存，需要注意一个前提：--cache的缓存文件位于node_modules下，而 CI 通常是全新检出 + 全新安装，缓存主要在本地开发循环（反复yarn lint:prettier）中收益最大；在 CI 中若想复用缓存，需要自行把--cache-location指向被 Actions 缓存的目录。

Prettier 仓库自身的 autofix 工作流

除了给读者的模板，Prettier 仓库自己也在用 autofix.ci，其工作流.github/workflows/autofix.yml完整内容非常精简：

name: autofix.ci # needed to securely identify the workflow on: pull_request: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true permissions: {} jobs: fix: name: Run automated fix uses: prettier/shared-workflows/.github/workflows/automated-fix.yml@c3ac99dd39893c2592fc5e6029420a1b90ad647b # main with: repository: prettier/prettier

与docs/ci.md模板相比，有几处值得注意的工程化细节：

• 复用共享工作流：实际逻辑放在prettier/shared-workflows的automated-fix.yml可复用工作流中，并以 commit SHA 固定（@c3ac99...，注释标明对应 main 分支），这正是“pin 版本”原则在 workflow 层的应用；
• concurrency取消旧运行：同一 PR 的新 push 会取消旧运行，节省 CI 配额，lint.yml 与 dev-test.yml 也都采用了相同的concurrency写法；
• permissions: {}：autofix 工作流不需要任何仓库权限——提交动作由 autofix.ci App 凭自己的 App 身份完成，与docs/ci.md模板中permissions: {}的设计意图一致。

与 pre-commit 钩子配合：本地兜底 + CI 兜底

CI 检查是团队级的最后一道防线，Prettier 官方文档同时提供了 Pre-commit Hook 方案作为本地兜底：

• lint-staged（+ husky）：适合与 ESLint、Stylelint 等工具共存，或需要支持部分暂存（git add -p）的场景；
• pretty-quick（+ simple-git-hooks）：只需对已暂存文件做整文件格式化时的轻量方案。

两者与 CI 检查的关系是互补的：本地钩子让开发者在提交前就拿到即时反馈；CI 中的prettier . --check或 autofix 工作流则保证即使绕过了本地钩子（如直接 push、合并策略差异），合入的代码仍然格式合规。对于已经部署了 autofix.ci 的团队，还可以在 PR 模板中约定“优先接受自动格式修复 commit”，减少人工来回。

小结：搭建 Prettier CI 检查清单

综合 docs/ci.md 模板与 Prettier 仓库自身的 CI 实践，为仓库接入 Prettier CI 时可以按以下清单落地：

1. 固定版本：在devDependencies中安装精确版本的 Prettier，并固定 Node 版本与依赖锁文件（参考 package.json 与 lint.yml 的写法）；
2. 准备配置：确认仓库根目录的格式配置（如本仓库的 prettier.config.js，其中按文件类型覆盖 parser）与忽略规则.prettierignore正确无误——CI 会以同样的配置执行；
3. 门禁或自动修复二选一（或并用）：
   • 门禁：在 CI 中运行prettier . --check（可加--cache），失败即阻塞合并；
   • 自动修复：按docs/ci.md模板安装 autofix.ci App 并创建.github/workflows/prettier.yml，运行prettier . --write后由autofix-ci/action提交修复；
4. 本地体验配套：用 pre-commit 钩子 让开发者在提交前完成大部分格式化；
5. 细节优化：对文档代码块等特定范围用带PRETTIER_DEBUG的--check做补充检查，并为工作流配置concurrency与最小化permissions。

以上内容均以当前仓库（Prettier 3.10.0-dev，engines.node >= 22）的实际文档与工作流为准；若你在不同 Prettier 版本或 CI 平台上使用，建议以对应版本的 CLI 文档 与平台官方 Action 版本为准做相应调整。

【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier