本指南逐步介绍了如何安装、配置和使用 act 工具在本地运行 GitHub Actions 工作流。有关架构和组件的更详细信息，请参阅架构概览。
在您的系统上安装 act 有几种方法
从 GitHub 发布页面下载最新版本并将其放置在您的 PATH 中。
如果您想从源代码构建 act
要验证安装，请运行
这应该显示当前版本的 act（例如，0.2.76）。
来源: VERSION Makefile76-80
要在本地以默认配置运行 GitHub Actions 工作流
默认情况下，act 将运行由 push 事件触发的所有工作流。如果您的仓库只包含一种事件类型，act 将使用该事件作为默认值。
Workflow Execution Flow:
1. act scans .github/workflows/ directory
2. Determines which workflows to run based on the event
3. Creates and executes a plan of jobs and steps
4. Runs each job and step in Docker containers
5. Displays the output from each step
来源: cmd/root.go56-132 README.md7-10 pkg/runner/runner.go16-19
当您首次运行 act 时，它将提示您选择一个默认的 Docker 镜像大小
此选择将保存到您的配置文件 (~/.config/act/actrc) 中，以供将来使用。
下图说明了 act 如何处理和执行 GitHub Actions 工作流
来源: pkg/runner/runner.go107-208 cmd/root.go387-704
以下是一些常用的命令行选项
| 选项 | 描述 |
|---|---|
-e, --eventpath | 事件 JSON 文件的路径，用于触发工作流 |
-W, --workflows | 工作流文件的路径（默认：./.github/workflows/） |
-j, --job | 运行特定的作业 ID |
-l, --list | 列出可运行的工作流 |
-g, --graph | 绘制工作流执行图 |
-v, --verbose | 启用详细日志记录 |
-s, --secret | 将 Secrets 添加到容器环境 |
-w, --watch | 监视更改并重新运行工作流 |
-P, --platform | 指定要使用的平台镜像 |
-b, --bind | 将工作目录绑定到容器（默认：复制） |
要运行特定事件的工作流
这将运行所有由 pull_request 事件触发的工作流。
要运行工作流中的特定作业
这将只运行 ID 为 build 的作业。
您可以通过以下几种方式将 secrets 传递给工作流
secret 文件应包含 key=value 格式的 secrets，每行一个。
同样，您可以设置环境变量
来源: cmd/root.go76-78 cmd/root.go341-367
act 使用 Docker 运行 actions。您可以为不同的平台指定自定义镜像
下图显示了 act 如何与 Docker 交互
来源: cmd/root.go80-82 README.md16-18
act 支持配置文件来存储默认选项。配置文件按以下顺序在以下位置搜索
~/.config/act/actrc (XDG 配置路径)~/.actrc (主目录).actrc (当前目录)一个典型的配置文件可能如下所示
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=catthehacker/ubuntu:act-20.04
-P ubuntu-18.04=catthehacker/ubuntu:act-18.04
来源: cmd/root.go134-150 cmd/root.go275-298
act 支持矩阵作业，允许您使用不同配置组合运行工作流
来源: pkg/runner/testdata/matrix/push.yml12-15 cmd/root.go96 pkg/runner/runner.go157-196
您可以将 act 设置为监视您的仓库更改并自动运行工作流
这在开发期间非常有用，可以在您修改工作流文件时立即获得反馈。
来源: cmd/root.go68 cmd/root.go749-796
act 支持 Artifacts 和缓存
要启用 Artifact 支持
来源: cmd/root.go115-117 cmd/root.go669-680
如果您遇到问题，可以生成详细的错误报告
这将输出系统信息、Docker 配置以及其他有助于排查问题的详细信息。
Docker 连接问题
镜像问题
未找到工作流
act -l 列出可用工作流-W 检查您的工作流文件路径既然您已经熟悉了 act 的基本用法，您可能想进一步探索