技能使用指南

act-local-testing（act本地测试技能）Skill 是什么？怎么用？

act-local-testing 技能帮你在本地用 act 运行与调试 GitHub Actions 工作流：生成命令、配置 Docker 镜像与秘密文件、排查报错，提交前即可验证 CI。了解安装步骤、使用流程与竞品对比，快速提升工作流调试效率。

act本地测试技能Skillact-local-testing
8 个章节 约 17 分钟阅读 AI 智能生成

act本地测试技能Skill：把 GitHub Actions 工作流搬回本地跑，CI 调试不用再靠“推上去看结果”

  • 一句话定位：这是一款服务于 act 的 AI 技能，帮助你在本地机器上运行、验证和调试 GitHub Actions 工作流，把 CI 反馈周期从“提交—推送—等队列—看日志”缩短为“改完即跑”。
  • 能力范围：覆盖 act CLI 命令、Docker 运行器镜像配置、.actrc / .secrets / .env 配置文件管理、详细日志与交互式分步调试、矩阵测试、常见故障排查与 CI/CD 集成。
  • 技术依赖：需要本地具备 Docker 环境与一个含 .github/workflows/ 目录的仓库，act 本体支持 macOS、Linux、Windows 与源码安装。
  • 适用人群：频繁维护 GitHub Actions 的开发者、DevOps/平台工程师、给开源项目提 PR 的贡献者，以及正在学习 Actions 语法的新人。
  • 核心价值：无需把半成品工作流推送到远端即可验证，减少无效提交与云端 CI 资源消耗。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 act本地测试技能Skill
技能英文名 act-local-testing
技能ID 13992
底层工具 nektos/act（开源命令行工具）
技能可调用的工具能力 读取、写入、编辑、Bash、Grep、Glob

它解决什么问题

GitHub Actions 的默认调试方式是“推上去看结果”：改一行 YAML，提交一次，等云端排队，跑完再翻日志。这个过程在维护多工作流仓库、调试矩阵构建、排查只在特定镜像里才出现的依赖错误时尤其低效。该技能把这段链路前移到本地——通过 act 在 Docker 容器中模拟 GitHub 的运行器，让工作流在提交前就能被执行、被观察、被修改。

同时，它解决的是“知道要本地跑，但不知道怎么配”的问题：用哪个镜像、秘密怎么传、为什么某个 action 跑不起来、Docker 权限报错怎么修——这些都在技能覆盖范围内，并且技能具备读取与编辑项目文件的能力，可以直接查看 .github/workflows/ 下的文件、生成 .actrc、核对 YAML 结构。

一键安装 AI 技能的思路与步骤

第一步，确认安装前提：

  1. 本地已安装并启动 Docker（可用 docker ps 验证）；
  2. 目标仓库中存在 .github/workflows/ 目录及工作流 YAML 文件；
  3. 使用的 AI 编程客户端支持技能（Skill）机制。

第二步，安装技能本体。在客户端提供的技能市场或技能管理入口中，以技能名称 act-local-testing（技能ID 13992）检索并安装，具体入口路径、安装命令与是否需要登录账号，以官方说明为准。

第三步，安装底层工具 act（以下命令来自技能文档，可直接使用）：

macOS：

brew install act

Linux：

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Windows：

choco install act-cli
# 或
scoop install act

从源码安装：

go install github.com/nektos/act@latest

第四步，验证是否生效。安装完成后，在仓库根目录执行：

act -l

若能列出检测到的工作流与作业列表，说明 act 已正确识别项目；再执行 act --dryrun 做一次不实际执行的语法级验证，若返回正常，则说明技能所需的运行条件已经齐备。随后在 AI 对话中提出“帮我在本地跑一下这个 workflow”，即可进入技能协作流程。

该技能的主要功能和特点

  • 工作流执行命令生成：支持运行全部工作流（act）、指定事件（act pull_request、act workflow_dispatch、act repository_dispatch -e event.json）、指定工作流文件（-W .github/workflows/ci.yml）与指定作业（-j build）。
  • 工作流清单与可视化：act -l 列出所有工作流与作业，act -g 输出工作流图形结构，act pull_request -l / -g 可按事件过滤，帮助快速理解陌生仓库的 CI 结构。
  • 安全的前置验证：act --dryrun、act -n 在不执行的前提下显示将要运行的内容，避免“不知道会做什么就直接跑”。
  • Docker 运行器镜像分层配置：从默认的最小镜像，到 catthehacker/ubuntu:act-latest 中等镜像，再到 catthehacker/ubuntu:full-latest 高兼容镜像，可按兼容性需求逐级提升；支持通过 .actrc 固化平台映射，也支持命令行临时覆盖。
  • 容器复用与清理：--reuse 在多次运行间复用容器以加快迭代，--rm 在运行后自动清理，兼顾速度与磁盘卫生。
  • 秘密与变量管理：支持 .secrets 文件配合 --secret-file、内联 -s KEY=VALUE、按环境区分 .secrets.dev / .secrets.prod，以及 --env 与 --env-file 注入环境变量。
  • 调试能力组合：-v / -vv 输出详细与调试级日志，--watch 进入每个步骤前暂停的交互模式，--reuse 配合 docker exec -it <container-id> /bin/bash 进入容器内部检查，--bind / -b 绑定挂载本地目录。
  • 矩阵测试定向执行：--matrix os:ubuntu-latest --matrix node:20 可只跑指定矩阵组合，无需全量执行。
  • 故障排查知识库：覆盖 Docker 未运行、镜像未拉取、Linux 下的 Docker 权限（usermod -aG docker $USER）、镜像缺少工具、工作流未找到、动作兼容性等典型问题。
  • CI/CD 集成范式：提供 pre-push 钩子脚本与 Makefile 目标示例，把本地验证固化为团队流程。
  • 性能与缓存优化：--reuse、必要时 --no-recurse、简单测试改用小镜像，并说明 act 会尊重 actions/cache，主机缓存位于 ~/.cache/act/。

和普通工具相比强在哪：普通做法是你自己翻 act 的帮助文档再手写命令；该技能把“命令选型 + 配置生成 + 报错归因 + 文件读写”串成一条链路，可以直接读取仓库里的工作流文件、发现 YAML 结构问题、生成 .actrc 与 .gitignore 条目，并给出下一步该跑哪条命令。

如何使用该技能？

步骤 1：确认环境

docker ps

若报错说明 Docker 未运行，这是 act 无法工作的第一原因。

步骤 2：让技能梳理工作流清单

输入示例：“列出这个仓库里所有 GitHub Actions 工作流和作业。”

期望输出：act -l 对应的结果，以及各工作流的触发事件与作业名，便于你决定跑哪一个。

步骤 3：先干跑再真跑

act --dryrun

用于验证 YAML 语法与工作流结构；确认无误后再进入下一步。

步骤 4：按需选择镜像

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

镜像越大兼容性越好但拉取和启动越慢。首次使用建议中等镜像，遇到“缺少工具”再升级到 full 镜像。

步骤 5：把配置固化到 .actrc

在项目根目录创建 .actrc：

-P ubuntu-latest=catthehacker/ubuntu:act-latest
--reuse
--secret-file .secrets
--env-file .env

这样后续所有 act 命令都会继承同一套配置，团队协作时行为一致。

步骤 6：准备秘密文件

创建 .secrets：

GITHUB_TOKEN=ghp_your_token_here
NPM_TOKEN=npm_your_token_here

并立刻把 .secrets 与 .env 加入 .gitignore。运行：

act --secret-file .secrets

步骤 7：定向跑单个作业，加快迭代

act -j test

修改工作流后再跑一次，配合 --reuse 可显著减少容器启动开销。

步骤 8：遇到失败时进入调试模式

act -vv

仍无法定位时，另开终端进入容器：

docker ps
docker exec -it <container-id> /bin/bash

步骤 9：处理 GitHub 专属 action

在工作流中做条件跳过：

- name: GitHub-only action
  if: ${{ !env.ACT }}
  uses: github/some-action@v1

步骤 10：把验证固化为提交前检查

在 .git/hooks/pre-push 中写入验证逻辑，或在 Makefile 增加 test-workflows 目标，让“本地先验证”成为默认习惯。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
act-local-testing（本技能） AI 技能 + act CLI 的组合方案 生成 act 命令、配置 Docker 镜像、管理秘密与变量文件、调试与排错、CI 集成建议 需安装 AI 技能客户端、act 与 Docker；对 Docker 概念有基本了解 频繁维护工作流、需要快速本地迭代的开发者 优势：把命令选择、配置生成与报错归因一起解决，可直接读写项目文件；不足：依赖本地 Docker 资源，镜像体积较大
直接使用原生 act CLI 开源命令行工具，自行查阅文档 完整的本地工作流执行能力 需自行记忆参数组合与排错路径 熟悉 act 的资深用户 优势：无额外依赖、完全可控；不足：学习曲线陡，遇错需自行搜索
GitHub Actions 云端运行 GitHub 官方托管执行 与生产环境一致的运行器、原生支持全部 action 只需推送代码，无需本地环境 最终验收、需要与线上完全一致的场景 优势：兼容性最好；不足：反馈链路长、消耗 Actions 分钟数、无法在提交前验证
本地脚本 / Makefile 自建流程 通用自动化手段 执行编译、测试、lint 等本地任务 需自行编写与维护 与 CI 无强关联的本地检查 优势：轻量灵活；不足：无法模拟 GitHub 运行器环境与 action 生态，与工作流 YAML 脱节

选型建议：日常迭代用本技能配合 act，最终验收交给云端 Actions，两者互补而非替代。

该技能的典型应用场景与实际体验情况

场景一：后端开发者在推送前自检工作流

角色：维护一个多作业 CI（lint、test、build）的后端工程师。痛点：每次改 YAML 都要推上去才知道是否写错，一个缩进错误可能浪费一轮队列等待。使用方式：先 act --dryrun 验证结构，再 act -j test 只跑测试作业。实际体验：上手难度低，最大的门槛是首次拉取 Docker 镜像耗时较长；一旦镜像就位，--reuse 让后续迭代明显更快。注意事项：首次运行前务必确认 Docker 已启动。

场景二：平台工程师维护多条工作流

角色：负责组织内多个仓库 CI 的平台工程师。痛点：不同项目的运行器版本、秘密配置各不相同，容易互相污染。使用方式：为每个仓库编写独立 .actrc，秘密按环境拆分为 .secrets.dev 与 .secrets.prod。实际体验：.actrc 的价值在于“一次配置、处处一致”，团队新人克隆仓库后无需再记参数。注意事项：.secrets 与 .env 必须进 .gitignore，这是文档中反复强调的红线。

场景三：开源贡献者给陌生仓库提 PR

角色：想给某开源项目提交修复的外部贡献者。痛点：不熟悉对方 CI 结构，PR 因工作流问题被打回。使用方式：act -l 摸清作业清单，act -g 看清依赖关系，再针对受影响作业定向运行。实际体验：可视化与清单能力对陌生仓库的帮助最大。注意事项：部分 action 只允许在 GitHub 环境运行，需通过 if: ${{ !env.ACT }} 跳过，不要误判为本地环境有问题。

场景四：新人学习 GitHub Actions

角色：刚接触 CI/CD 的开发者。痛点：YAML 语法与执行顺序抽象，难以建立直观理解。使用方式：act --watch 进入交互模式，在每个步骤执行前暂停观察，配合 -vv 查看详细过程。实际体验：把抽象配置变成可观察的逐步执行，理解成本明显下降。注意事项：--watch 会拖慢执行节奏，适合学习而非日常批量运行。

该技能能为用户带来的价值

缩短反馈回路：把“提交—推送—排队—看日志”的多步往返压缩为本地一条命令，改动与验证之间几乎没有等待，尤其适合 YAML 语法、依赖缺失、脚本路径这类高频小错误。

降低使用门槛：act 的参数组合与镜像体系对新手并不友好，-P、--secret-file、--env-file、--matrix、--reuse 等选项需要经验才能组合正确。技能把这些选择转化为可执行的建议，并直接落到项目文件里。

减少无效提交与云端消耗：在本地拦截明显会失败的工作流，意味着更少的失败构建记录与更少的 Actions 分钟数占用（具体计费规则以 GitHub 官方说明为准），对按用量计费的团队尤其有意义。

提升配置的可维护性：.actrc、.secrets、.env 与 pre-push 钩子构成一套可版本化、可复用的本地 CI 基础设施，新人接入成本随团队规模扩大而下降。

长期价值：形成“本地先验证、云端再验收”的双层流程，工作流文件从“改完就推”的黑盒变成可以像普通代码一样被调试和重构的工程资产。

常见问题 FAQ

Q1：这个技能怎么安装？需要先装什么？

需要三步：在 AI 客户端技能入口安装 act-local-testing（技能ID 13992，具体入口以官方说明为准）；按操作系统安装 act（macOS 用 brew install act，Linux 用官方安装脚本，Windows 用 choco install act-cli 或 scoop install act，也可用 go install github.com/nektos/act@latest）；确保 Docker 已安装并运行。验证方式是在仓库根目录执行 act -l 能列出工作流。

Q2：使用这个技能收费吗？

技能文档中未涉及定价信息。技能本体的费用取决于所在平台的规则，底层工具 nektos/act 属于开源命令行工具。具体的收费方式与许可条款请以官方说明为准。

Q3：本地 act 跑通就等于 GitHub 上一定能跑通吗？

不等于。act 通过 Docker 镜像模拟运行器环境，与真实 GitHub 运行器仍有差异，部分 action 依赖 GitHub 专属环境。文档建议通过 if: ${{ !env.ACT }} 在工作流中跳过这类步骤，并把本地验证视为“提前发现问题”的手段，最终仍需以云端运行为准。

Q4：工作流里报“命令不存在”或“工作流未找到”怎么办？

前者通常是镜像精简导致工具缺失，可升级到 catthehacker/ubuntu:full-latest 镜像，或在工作流中显式安装依赖；后者先用 ls -la .github/workflows/ 确认文件存在，再用 yamllint 校验 YAML 语法，最后用 act -l 确认检测结果。

Q5：这个技能适合谁用？和直接用 act 怎么选？

适合经常维护 GitHub Actions 的开发者、需要统一团队 CI 配置的平台工程师、给开源项目提 PR 的贡献者以及 Actions 学习者。如果已经非常熟悉 act 的参数体系，直接使用原生 CLI 即可；如果你更希望“说清目标就得到可执行命令与配置”，并需要有人帮你定位报错原因，本技能的价值更明显。