企业官网建设流程全解析

直接以正文开始。先想清楚一件事：claude-code-action不是一个“把 Claude Code 跑在云端”的简单封装，它解决的是开发工作流自动化中最后一个没人愿意干的环节——让 AI 真正进入 CI/CD 管线，替人读代码、改代码、提 PR、补文档，而不是停留在聊天框里。

我第一次接触这个项目，是因为团队的 PR 审查流程实在太折磨人了。早上打开仓库，几十个 PR 等着看，Lint 报错、类型问题、注释缺失，这些一眼能看出的问题硬是要占用 reviewer 半小时。后来我把claude-code-action接进 GitHub Actions，让 Claude Code 在每次 Pull Request 打开时自动跑一遍检查，把问题直接评论在 PR 里，有些简单问题甚至直接生成修复提交。折腾了两周，reviewer 的工作量降了六成。

这篇文章就把我这个过程的完整踩坑记录整理出来，包括基础配置、关键参数、真实场景的 workflow 写法，以及我踩过的认证、并发、成本控制这些坑。如果你正在做类似的事情，可以直接抄作业。

1. 先搞清楚 claude-code-action 到底解决什么问题

1.1 从 Claude Code 说起

在聊 Action 之前，得先了解 Claude Code 本身。

Claude Code 是 Anthropic 出品的终端 AI 编程助手，它不像 ChatGPT 那样在网页里和你对话，而是直接跑在你的命令行里，能读写项目文件、执行命令、运行测试、提交代码。你给它一个任务，比如“修复这个模块里的内存泄漏”，它会自己去翻代码、定位问题、改代码、跑测试，最后把改动展示给你确认。

关键点在于：Claude Code 天然是为“干活”设计的，不是为“聊天”设计的。它有一套完整的工具调用体系，可以操作文件系统、执行 shell 命令、调用 git 操作。这意味着它非常适合被集成进自动化流程——只要给它一个环境、一个任务、一个允许执行的操作边界，它就能自主完成一整套代码工作。

1.2 Action 到底替我们省了哪些事

claude-code-action就是把 Claude Code 包装成 GitHub Actions 的一个标准组件。它在 GitHub 的 runner 上初始化一个完整的环境，安装 Claude Code，用你提供的 API Key 完成认证，然后按你配置的 prompt 执行任务。

这么说可能有点抽象，我直接说几个实际能办到的场景：

• 自动代码审查：每次 PR 打开，Action 自动 checkout 代码，让 Claude Code 审查变更，把发现的问题以评论形式发到 PR 里。
• 自动修复 lint 错误：前端项目最常见的场景。运行 ESLint 发现几个自动修复不了的错误，交给 Claude Code 分析并修改，然后推送修复 commit。
• 自动生成 PR 描述：根据 diff 内容自动生成结构化 PR 描述，包含改动概述、影响范围、测试建议。
• 自动重构模块：比如“把 utils 目录里所有 any 类型替换成具体类型”这种批量任务，丢给 Action 完成后直接提交 PR。
• 文档自动同步：接口变动后自动更新对应的 README 或 API 文档。

这些事以前要么靠人肉，要么靠写死规则的脚本。规则写少了不管用，写多了维护成本爆炸。而 Claude Code 的优势是能“理解”语义，面对没有固定模式的问题也能处理。

2. 核心原理与配置拆解

2.1 workflow 基础配置示例

先看一个最小可用的配置。创建一个.github/workflows/claude-review.yml文件，内容如下：

name: Claude Code Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest permissions: contents: write pull-requests: write issues: write steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: anthropics/claude-code-action@v1 with: claude-code-version: "latest" github-token: ${{ secrets.GITHUB_TOKEN }} max-failures: "0" prompt: | 请审查这个 PR 的所有代码变更。 重点关注： 1. 潜在的 bug 和逻辑错误 2. 类型安全问题 3. 业务逻辑一致性问题 4. 明显需要改进的地方 请以评论形式将发现的问题发布到 PR 上， 评论使用中文，按严重程度排序，每个问题注明文件和行号。

这个配置里核心就三件事：加载代码、启动 Action、让它干活。claude-code-version指定 Claude Code 版本，github-token让 Action 有权限发布评论，prompt是任务指令。

2.2 关键参数逐项拆解

我实际使用中验证过比较重要的参数有这么几个：

claude-code-version

指定 Claude Code CLI 的版本。默认是latest，但生产环境我不建议追新。Claude Code 迭代很快，有时候新版会调整工具调用格式，可能导致已有的 prompt 表现不稳定。我目前固定在某个经过验证的版本上，比如1.0.24。等新版本发布一周、社区反馈稳定后再升级。

github-token

这个参数的作用是让 Action 能在 GitHub 上留下痕迹——发布评论、创建 commit、开 PR。它填secrets.GITHUB_TOKEN就行，这是 GitHub 自动生成的临时凭证。注意，使用这个 token 创建的 commit 会被标记为github-actions[bot]的提交，而非你的个人账号。如果想以个人身份提交，得用个人 access token（PAT）创建 secret 再传进去，比如secrets.MY_PAT。

max-failures

Claude Code 执行过程中如果出错，最多容忍几次。默认是 0，意思是第一次出错就停止。我建议保持默认，因为一次执行失败往往意味着 prompt 或环境有问题，连续重试只会浪费 token。

model

指定要使用的模型，比如claude-sonnet-4-5或claude-opus-4-1。选型逻辑很简单：普通的 lint 修复、代码审查用 sonnet 就够，性价比高；碰到复杂逻辑分析、跨模块重构，我会上 opus。你可以按任务类型拆分成不同的 workflow，分别指定模型。

system-prompt

给 Claude Code 设定身份和行为边界。比如“你是资深前端工程师，你审查代码时重点关注性能和可访问性”，这样能显著提升输出质量。这个参数在实践中非常有用，几乎每个稳定运行的 workflow 都配了。

run-command

默认情况下，Action 会执行claude -p --output-format stream-json来跑 prompt。你可以覆盖这个命令，传入claude -p ...形式的自定义指令。适合需要添加额外参数（比如--allowedTools白名单）的场景。

2.3 为什么用“单次执行”而不是“长时间对话”

用过 Claude Code 的同学可能会问：为什么不在 Action 里启动一个长期的交互式会话，让它不断执行多轮任务？

这个问题的答案和 GitHub Actions 的运行机制有关。一个 runner 实例有超时时间（通常是 6 小时），而且每次执行逻辑越复杂，越难排查问题。claude-code-action走的是“单次执行”模式：每次 Action 运行，启动一个干净的 Claude Code 会话，执行完 prompt 就退出，结果通过文件输出或 GitHub API 反馈回来。

这个设计的优势是可重复性和可调试性。一次运行就是一个黑盒，跑完看日志就能知道发生了什么。如果任务需要多轮处理，应该在 workflow 的层面编排，比如 job A 跑完代码修复，触发 job B 跑测试，而不是寄希望于单个 Claude Code 会话里执行几十个步骤。

3. 实操：从零搭建一个自动代码审查流水线

3.1 搭建前的准备

第一步，准备 API Key。

登录 Anthropic 控制台，创建一个 API Key。注意，这个 Key 的文本只会完整显示一次，创建后赶紧复制保存。把它添加到仓库的 Settings -> Secrets and variables -> Actions 里，命名成ANTHROPIC_API_KEY。

顺带说明一下计费。Claude Code 按 token 计费，日常代码审查每次大约消耗 1 万到 3 万 token，具体取决于代码量和模型。用 sonnet 级别模型的话，一次完整的 PR 审查成本大概是几美分。但如果每个 PR 都跑，一个月累积下来也是笔不小的数字。我的经验是在团队项目里只对特定 label 的 PR 自动审查，或者只在 draft 转 ready 的时候触发一次。

第二步，确认仓库权限设置。

在 GitHub 仓库的 Settings -> Actions -> General -> Workflow permissions 里，确保选择了Read and write permissions，否则 Action 没有权限推送 commit 和创建评论。

第三步，建立基础目录结构。

我习惯在 repo 根目录放一个.claude文件夹，里面放settings.json和commands.md。settings.json可以配置环境变量，commands.md用来定义自定义指令。比如：

/pod-review 你是资深 DevOps 工程师。请审查这个 PR 中所有与 Kubernetes 部署相关的文件， 重点关注镜像标签是否正确、资源限制是否合理、健康检查配置是否完整。 如果发现问题，在 PR 评论中逐条列出，并说明修复方案。

这样一来，workflow 里的 prompt 就不用写大段内容，直接引用自定义指令，干净很多。

3.2 完整配置一个审查工作流

下面是我目前生产环境中在用的一个比较完善的配置，加了开关、模型选择和提交反馈机制：

name: claude-code-review on: pull_request: types: [opened, synchronize, reopened] branches: [main, develop] jobs: claude-review: if: contains(github.event.pull_request.labels.*.name, 'ai-review') runs-on: ubuntu-latest timeout-minutes: 30 permissions: contents: write pull-requests: write issues: write steps: - name: Checkout code uses: actions/checkout@v4 with: fetch-depth: 0 - name: Run Claude Code Review uses: anthropics/claude-code-action@v1 env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} with: claude-code-version: "1.0.24" github-token: ${{ secrets.GITHUB_TOKEN }} model: "claude-sonnet-4-5" max-failures: "0" prompt: | 请审查这个 PR 的代码变更，并重点关注以下方面： 1. 逻辑错误和潜在的运行时异常 2. 类型安全问题，尤其是 `any` 的滥用 3. 数据库操作是否有性能隐患（N+1 查询等） 4. 错误处理是否完备，是否存在吞异常的情况 5. 初级的代码问题，比如未使用的变量、死代码、硬编码 审查结果请以评论形式发布到 PR 上。要求： - 每条评论必须包含具体文件和行号 - 按严重程度从高到低排序 - 每个问题附带一句简单的修复建议 - 如果代码没有问题，请回复一句话说明一切正常 - 使用中文回复

这里有两个设计要点。

一是加了if条件限制。只有带有ai-reviewlabel 的 PR 才会触发审查。为什么不所有 PR 都跑？因为成本还是次要的，主要原因是噪声。不是每个 PR 都值得 AI 看一遍，比如文档改动、配置文件调整，审查意义不大。控制触发范围，接口的评论质量会高很多。

二是用了timeout-minutes: 30。Claude Code 处理一个中等规模的 PR 大概需要 3 到 5 分钟，但有些 PR 改动特别多，或者仓库很大，耗时会飙到十几分钟。设置 30 分钟阀值，可以避免异常情况下 runner 长时间占用的费用问题。

3.3 运行过程会发生什么

工作流触发后，可以到仓库的 Actions 页面看到运行日志。正常情况下日志会显示 Claude Code 正在初始化，然后开始调用工具读取代码。每一步操作都有输出，包括读取了哪些文件、执行了什么命令、最终生成的内容。

第一次跑我强烈建议盯着日志看一遍。你会看到 Claude Code 怎么在代码库中定位相关信息。比如你让它审查登录模块，它会先搜索路由定义，找到 login 相关的 controller 和 service 文件，然后逐个打开阅读。这个过程中的每一步都对应了一次工具调用。熟悉这个过程后，你再写 prompt 就会有的放矢，知道怎么引导它更快地找到重点。

运行结束后，Action 会调用 GitHub API 把结果发布成 PR 评论。你可以直接在 PR 页面看到结构化的问题列表，每条都带着文件和行号。

4. 常见问题与避坑指南

4.1 认证和权限问题集锦

我踩过的最基础的坑是ANTHROPIC_API_KEY没有正确配置。第一次配置 Action 时，贪方便直接写在 YAML 文件里，先不管安全性，纯粹为了验证流程。结果 GitHub 直接拒绝运行，提示包含敏感的硬编码密钥。后面改成 secrets 配置后一切正常。所以千万别图省事，secrets 是唯一正解。

还有一个坑是关于GITHUB_TOKEN的权限范围。如果你在 workflow 里配置了permissions块，但只写了pull-requests: read，那么 Action 发布评论时会收到 403 错误。日志里会显示类似Resource not accessible by integration的信息。解决方法是把permissions配置成全，尤其是pull-requests: write和contents: write不能少。

关于 fork 类 PR，这里有个很微妙的限制。从 fork 仓库发来的 PR，默认情况下无法访问仓库的 secrets，这是 GitHub 的安全机制。所以如果你做开源项目，外部贡献者的 PR 是没有办法用这个 Action 跑 Claude Code 审查的，至少不能直接跑。我现在的做法是，对于 fork 的 PR，在评论里用/ai-review这种 slash 命令手动触发一个 workflow_dispatch 事件来运行审查，这需要额外配置一个监听 issue_comment 事件的 workflow。

4.2 成本控制的几个技巧

成本是这类 Action 落地最大的阻力，也是最容易被忽略的。我第一次全量跑了一个中型后端项目的所有 PR，一周下来账单让我吃了一惊。

控制成本的第一步是控制触发范围，我前面已经说过了。第二步是限定模型，同一套代码，opus 的执行成本大概是 sonnet 的三到四倍，普通功能开发项目完全用不到 opus。第三步是限制 Claude Code 的行动边界。

关于行动边界，这里有一个关键参数值得展开：--allowedTools。如果不限制，Claude Code 可以执行任何 shell 命令、读写任何文件。在 CI 环境里这问题不大，runner 是临时的，但成本上会出问题——它可以因为一个简单的类型错误把整个测试套件跑一遍，甚至尝试安装依赖。这会浪费大量 token。

我现在的做法是，在 workflow 里显式限定工具白名单。比如审查任务只允许读文件和发布评论，不允许执行命令：

run-command: "claude -p --allowedTools Read Write Edit --output-format stream-json"

注意，Edit是必要的，否则它无法修改代码。但像Bash这种工具就不给了。这样一来任务聚焦，token 消耗能减少一半。

还有一个技巧是缓存机制没有意义，别浪费时间研究这个方向。每个 runner 都是全新的环境，Claude Code 的依赖安装是每次跑都要执行的。缓解的办法是接受这个现实，或者干脆用自建的 repository runner，让环境的启动速度快一些。

4.3 稳定性与 Prompt 调优的实战心得

Claude Code 在 CI 环境里的表现和你本地终端里不太一样。没有交互式反馈，它一旦理解偏差就会沿着错误的方向跑下去。这时候 prompt 的质量就无比关键。

我在实践中总结出三条 prompt 调优原则：

原则一：明确输出格式。不说明输出格式，Claude Code 可能输出一段散文，而不是结构化的问题列表。我一般在 prompt 末尾加上“使用列表输出，每条包含文件路径和行号”。有了这个约束，结果提取和处理都方便很多。

原则二：给定判断依据。单纯说“检查代码质量”太模糊。我会说明具体的检查项，比如“检查是否存在内存泄漏”、“检查错误处理是否吞掉异常”、“检查 SQL 是否有 N+1 查询”。给它明确的检查清单，相当于帮它划定了重点，准确率明显提升。

原则三：提供正反示例。在系统提示里放一小段“好代码”示例和“坏代码”示例，效果立竿见影。这其实是在用少样本学习的方式引导它的判断标准，和人们带新人时给范例是一个道理。

稳定性方面，还有一个绕不开的问题是 API 限流。Anthropic API 有速率限制，如果团队同时有多个 PR 触发审查，可能遇到 429 错误。我在 workflow 里加了continue-on-error: false，同时在 Action 运行前加了一个等待步骤，用sleep做一个简单的随机退避。虽然不是最优雅的方案，但有效。

5. 场景扩展：把 claude-code-action 真正用起来

5.1 自动修复 Lint 错误并推送修复提交

这个场景是我用得最多的，特别好用。

工作流触发时机是：PR 打开时，先跑一遍npm run lint，如果失败，把失败的输出作为 prompt 的一部分传给 Claude Code，让它修复eslint/tsc报告的错误，然后自动提交修复 push 到当前分支。

- name: Run lint check run: npm run lint || true - name: Fix lint errors with Claude uses: anthropics/claude-code-action@v1 env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} with: github-token: ${{ secrets.GITHUB_TOKEN }} model: "claude-sonnet-4-5" prompt: | 运行 `npm run lint` 检查代码，修复所有报告的错误。 修复完成后运行测试确保没有破坏现有功能。 最后提交并推送所有修改。

这里有个小心机：npm run lint || true。这样即使 lint 失败，后面的 steps 也能继续执行。因为 Claude Code 接手后自然会处理这些问题，粗暴中断反而不利于流程推进。

不过要注意，自动修复 lint 和自动提审有本质区别。lint 修复结果是可预期的，由工具规范化，所以让 AI 自主提交不会有太大风险。但涉及业务逻辑的修改，一定要保留在“生成 patch + 人工确认”的模式，不要让它直接 push。

5.2 自动生成 PR 描述

很多人写 PR 描述像挤牙膏，要么不写，要么用一句“Update”糊弄。这个场景非常适合用 Claude Code 处理，因为它的输出天然就是给你看的内容。

配置其实简单到不可思议：直接用actions/checkout拿到 diff，再传给 Claude Code，让它根据 diff 生成描述，通过 API 更新 PR。我的配置是这样的：

- name: Generate PR description uses: anthropics/claude-code-action@v1 env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} with: github-token: ${{ secrets.GITHUB_TOKEN }} prompt: | 请根据当前 PR 的代码变更，生成一个结构清晰的 PR 描述。 包括： - 本次改动的背景和目的 - 核心设计思路 - 关键改动点，按模块分类 - 影响范围评估 - 需要 reviewer 重点关注的代码位置 格式使用 GitHub 风格的 Markdown。

这个方法一句话总结就是“把写 PR 描述的成本从开发者转移到 AI，让不该花时间的人去写代码，让 AI 去写文档”。实测下来，生成的质量普遍高于团队 70% 成员手写的内容，至少结构上完全可用。

5.3 文档自动更新

API 改了忘更新文档，是团队协作中最常见的摩擦点之一。Claude Code 可以做这件事。

思路是在代码合并到 main 后触发 workflow，让 Claude Code 对比上一次 release 版本的 API 定义与当前代码的差异，找到对应的文档文件，更新并推送 commit。和 lint 修复类似，这一步完全可以在无人值守下跑通。

但有一点必须注意：文档改动涉及很多上下文，比如设计决策、历史背景，这些信息不在代码里。所以这个流程更适合给“机械动作”兜底，比如函数签名变更、参数增减、返回类型调整这类硬性变更，不适合做大篇幅的设计文档重写。

6. 聊聊我的一些习惯和建议

最后分享一个我用了一段时间之后形成的习惯：每个用 claude-code-action 的任务，都先在本地跑一遍同样的 prompt 再进 CI。

Claude Code 本来就是本地工具。你在仓库里claude -p "你的 prompt"跑一次，消耗的是你的本地资源，验证 prompt 的效果后在推给 CI。这比每次都在 GitHub Actions 里等 5 分钟看结果要高效得多。

还有一个小习惯是关于日志的。Action 跑完以后，我会把 stdout 日志保存下来，按日期归档。这不是为了审计，而是为了调 prompt。当某个流程的效果退化或者突然翻车时，翻出之前正常时的日志对比，能快速找到是在哪一步开始偏离的。这个习惯帮我避免过至少三次“大改 prompt 结果全部变差”的灾难。

你可能也注意到了，这类工具强大的同时带来的核心问题，其实是信任边界。它能写代码、能提 PR、能操作任何它能接触到的系统。GitHub Action 本身提供了权限隔离，但你得自己定义好边界。我的底线是：任何涉及生产环境的操作，AI 只能生成建议，不能直接执行。这个原则从来没有变过。

claude-code-action并不复杂，它做的事情用官方的描述来说是“把 Claude Code 装进 GitHub Actions”，但真正用好它的关键，不在于 YAML 怎么写，而在于你怎么定义问题、怎么控制边界、怎么把任务拆到“AI 能胜任”和“必须留给人类”之间那条清晰的分割线。希望这篇实践记录能帮你少走点弯路。