企业官网建设流程全解析

act本地运行GitHub Actions的10大常见坑与解决方案：镜像选择、M芯片架构、dryrun验证排障清单

【免费下载链接】actRun your GitHub Actions locally 🚀项目地址: https://gitcode.com/GitHub_Trending/ac/act

act是一款强大的开源工具，让你在本地直接运行 GitHub Actions 工作流，无需提交推送即可获得快速反馈。但新手使用 act 本地调试时，常常踩进这些坑：runner 镜像选错、Apple M 芯片架构不匹配、忘记 dryrun 验证导致反复报错。本文整理 10 大高频问题与官方排障方案，帮你一次配通。

坑1：Runner 镜像选错，缺 Python 直接报 command not found

act 默认的ubuntu-latest实际映射到精简的node:16-buster-slim镜像，不预装 Python，很多 Action 会直接失败。

解决方案：用-P参数为平台指定完整镜像。

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

平台到镜像的默认映射逻辑可参考 cmd/platforms.go，可选镜像清单（含体积对比）详见官方文档 IMAGES.md。

坑2：Apple M 芯片未指定架构，容器跑不起来

在 M1/M2/M3 等 Apple Silicon 上运行 act 时，官方会在启动时主动打印警告：

⚠ You are using Apple M-series chip and you have not specified container architecture

警告逻辑位于 cmd/root.go。解决方案：显式指定 x86 架构：

act --container-architecture linux/amd64

该参数依赖 Docker Engine API 1.41+，详细说明见 cmd/root.go。

坑3：不写 .actrc，每次都要重复敲一长串参数

官方推荐把常用参数写入.actrc配置文件（示例见 cmd/testdata/simple.actrc）：

--container-architecture=linux/amd64 --action-offline-mode

注意加载优先级（高→低）：XDG 配置路径 → 用户主目录~/.actrc→ 当前目录.actrc，见 cmd/root.go。很多人改了当前目录的.actrc却不生效，就是被主目录的旧配置覆盖了。

坑4：跳过 dryrun 验证，工作流写完就跑报错满天飞

act 提供--dryrun（-n）参数：不创建任何容器，仅校验工作流正确性。校验上下文实现见 pkg/common/dryrun.go。

act -n

最佳实践：修改完.github/workflows/后先act -n快速验证，通过后再真正执行，能省掉大量"拉镜像→失败"的循环。

坑5：事件类型不对，github.event_name 判断全部失效

本地运行时若不指定事件，工作流里if: github.event_name == 'pull_request'之类的判断会意外跳过。

解决方案：用-e指定事件类型，或提供事件 JSON 文件：

act -e pull_request act -e .github/workflows/event.json

事件解析逻辑在 pkg/runner/run_context.go。仓库内测试样例 pkg/runner/testdata/pull-request/event.json 可直接参考格式。

坑6：默认分支名不一致，github.ref 拿到错误值

本地克隆的分支名与仓库实际默认分支不一致时，github.ref会算错。

解决方案：显式指定：

act --defaultbranch main

分支与 ref 的推导逻辑见 pkg/model/github_context.go。

坑7：Secrets 没传进来，Action 里读到空值

act 的 secrets不区分大小写且会自动转大写。以下写法中token会被存成TOKEN：

act -s token=ghp_xxx

批量注入建议用--secret-file（默认读取.secrets文件），多行值用 YAML 格式书写，完整规则见 cmd/secrets.go 与示例 cmd/testdata/secrets.yml。

⚠️ 切勿使用--insecure-secrets，它会在日志中明文打印所有密钥。

坑8：工作流里调 API 报 401，GITHUB_TOKEN 为空

act 会自动从本机ghCLI 读取 GitHub Token注入为GITHUB_TOKEN（逻辑见 cmd/root.go）。如果本地没装gh或未gh auth login，所有需要鉴权的步骤都会 401。

解决方案：先登录 gh，或手动注入：

act -s GITHUB_TOKEN=ghp_xxx

坑9：容器里改的文件"传不到"工作区，或垃圾文件被带进容器

act 默认把本地工作区复制进容器；大仓库或需要双向同步时很慢。

解决方案：

• 用-b绑定挂载（bind mount）替代复制，修改实时可见；
• 默认会按.gitignore过滤文件，如需把 node_modules 等忽略目录也带进容器，加--use-gitignore=false；
• 需要跨次运行保留容器状态时加-r（reuse）。

三个开关的定义见 cmd/root.go。

坑10：Docker 连不上，报 "Couldn't get a valid docker connection"

使用远程 Docker 主机（如 OrbStack、Colima、云服务器）时，act 需要显式告知 daemon 位置：

act --container-daemon-socket unix://~/.docker/run/docker.sock

连接探测逻辑在 pkg/container/docker_socket.go，启动时的连接输出可参考 cmd/root.go。

📋 排障速查清单

把这套清单存下来，配合.actrc固化常用参数，act 本地调试就能稳定起飞 🚀

【免费下载链接】actRun your GitHub Actions locally 🚀项目地址: https://gitcode.com/GitHub_Trending/ac/act