7万 Star！用 act 本地跑 GitHub Actions

原创于 2026-08-19 18:20:35 发布 · 175 阅读

本内容遵循CC 4.0 BY-SA版权协议

一、项目背景及简介

每个 CI/CD 工程师都经历过这样的噩梦：在 GitHub 上 push 一个 workflow 修改，等待 3 分钟 Runner 启动，然后发现 yaml 语法写错了。再 push，再等。一天下来，20 次提交，15 次在调试 CI。

💡 如果能在本地跑 GitHub Actions，像调试本地代码一样调试 workflow，那该多好？

nektos/act 正是来解决这个问题的。它让你在本地运行 GitHub Actions，无需 push 到远程仓库，就能验证 workflow 的正确性。项目在 GitHub 上已获得 71,000+ Star，是 DevOps 工具链中最热门的开源项目之一。

act 的核心理念就是它的 slogan：**"Think globally, act locally"**——把 CI 的调试从云端拉回本地，把反馈周期从几分钟缩短到几秒。

二、技术栈解析

act 的技术选型非常务实：

语言：Go（高性能、跨平台、单二进制分发）
运行时：Docker API（通过容器模拟 GitHub Runner 环境）
架构：读取 .github/workflows/ 下的 yaml 文件，解析 Action 依赖关系，用 Docker 执行每个步骤

Go 语言的跨平台编译能力让 act 可以轻松在 macOS、Linux、Windows 上运行，单二进制分发让安装异常简单。

⚠️ 底层依赖 Docker Desktop 或 Docker Engine，因为 act 本质上是在本地容器中模拟 GitHub Runner 的执行环境。

三、核心功能

act 提供了 GitHub Actions 的本地仿真环境：

本地执行 workflow：完全解析 .github/workflows/ 目录下的所有 yaml 文件
支持所有 Action 类型：Docker 容器 Action、JavaScript Action、复合 Action
环境变量模拟：自动配置 GitHub 标准的 CI 环境变量
事件触发模拟：支持 push、pull_request、issue_comment 等事件
日志实时输出：彩色日志，和 GitHub Actions 的日志格式一致

🎯 杀手级功能：act 不仅是调试工具，还能当本地任务运行器用——替代 Makefile 来做本地自动化！

四、项目优势

极速反馈：本地运行，无需等待 GitHub Runner 启动
零成本调试：不用 push 20 次来调试一个缩进错误
离线可用：没有网络也能验证 workflow
VS Code 集成：配合 GitHub Local Actions 插件，在编辑器里直接运行
精准模拟：环境变量、文件系统、网络配置都对齐 GitHub 标准

选型建议：

✅ 推荐：所有使用 GitHub Actions 的团队，尤其是 CI 频繁变更的项目
❌ 不推荐：不使用 GitHub Actions 或 CI 已经稳定的项目

五、安装使用

安装 act 非常简单：

# macOS（Homebrew）
brew install act

# Linux / macOS（脚本安装）
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# 验证安装
act --version

六、代码示例

在项目根目录运行默认 workflow（push 事件）：

# 模拟 push 事件，运行所有匹配的 workflow
act

# 指定事件类型
act push
act pull_request

# 指定 job 名称，只运行特定 job
act -j build

# 使用自定义 GitHub Token（如需访问私有仓库）
act -s GITHUB_TOKEN=your_token_here

实际调试场景：

# 模拟 issue 被创建的事件
act issue_created -e .github/issue-event.json

# 查看详细日志
act --verbose

# 列出所有可用的 workflow
act -l

七、应用场景及案例说明

act 在以下场景中特别有用：

CI 调试：修改 workflow 后本地验证，减少无效 push ⚡️
新人上手：团队成员无需 push 就能学习 GitHub Actions 的工作方式
本地任务自动化：用 GitHub Actions 替代 Makefile 运行本地任务
离线开发：在没有网络的环境下开发和测试 CI 流程

很多团队在 CI 流程中引入 act 后，workflow 的迭代速度提升了 3-5 倍，因为每次调试的等待时间从 1-3 分钟降到了 5-10 秒。

八、总结

act 解决了一个非常具体但又极其普遍的问题——CI 调试太慢。它用"本地化"的思路，让 GitHub Actions 的开发体验从"提交-等待-失败-再提交"变成了"本地运行-调试-提交-通过"。

适用边界：act 是开发调试利器，但不适合替代生产环境的 CI 运行。它无法完全模拟 GitHub Runner 的所有特性（如自托管 Runner 的特定硬件环境）。

落地建议：在团队中推行"本地先验证，再 push 到远程"的 workflow 开发流程，把 act 集成到开发文档中，作为 CI 开发的标准工具。

你的团队还在用"提交-等待"的方式调试 CI 吗？试试 act，评论区聊聊你的体验 🚀

项目地址：https://github.com/nektos/act

标签

#github #junit #typescript #javascript #AI编程