gh-local

gh-local 工具为开发人员提供了一个强大的本地环境，用于直接在本地执行和调试 GitHub Actions CI 工作流程。通过在 Docker 容器内利用 nektos/act 框架，您可以模拟 GitHub 通常托管的准确 CI 环境，从而在处理复杂的工作流程文件或排除 CI 故障时显著缩短反馈循环。此工具非常适合需要确保 YAML 配置、环境变量和 Shell 脚本在提交代码前按预期运行的软件工程师。

• 使用 catthehacker/ubuntu:act-latest 镜像执行特定作业或完整的工作流程套件，以确保与标准 GitHub 托管执行器的兼容性。

• 支持本地测试环境配置，通过 --container-architecture 标志确保在 Apple Silicon 和其他架构上的执行一致性。

• 提供实时进度监控与自动化日志追踪，直接向您的会话报告 npm 安装、构建阶段和测试执行等步骤的结果。

• 当工作流程失败时，提供对错误输出的深度检查，让您能在几分钟内在本地修改并重新测试配置。

• 在执行前请确保已安装并启动 Docker Desktop 与 act CLI；若缺少依赖项，系统将提供安装指南。

• 请注意，虽然 act 模拟了大多数操作，但它不支持 GitHub 的原生构建（artifact）上传；这些步骤可能会失败或被设计为跳过。

• 指定目标作业或工作流程文件以优化执行时间；若未指定，代理程序默认为 .github/workflows/ci.yml。

• 此工具尊重工作流程 YAML 中定义的环境变量，从而实现本地环境与远程环境之间的无缝对等。

• 使用此工具识别 CI 流水线中的脚本错误、缺少依赖项或路径问题，无需浪费 GitHub 的执行时间，也不会用反复试错的提交来污染您的提交历史。