act本地运行GitHub Actions的10大常见坑与解决方案镜像选择、M芯片架构、dryrun验证排障清单【免费下载链接】actRun your GitHub Actions locally 项目地址: https://gitcode.com/GitHub_Trending/ac/actact是一款强大的开源工具让你在本地直接运行 GitHub Actions 工作流无需提交推送即可获得快速反馈。但新手使用 act 本地调试时常常踩进这些坑runner 镜像选错、Apple M 芯片架构不匹配、忘记 dryrun 验证导致反复报错。本文整理 10 大高频问题与官方排障方案帮你一次配通。坑1Runner 镜像选错缺 Python 直接报 command not foundact 默认的ubuntu-latest实际映射到精简的node:16-buster-slim镜像不预装 Python很多 Action 会直接失败。解决方案用-P参数为平台指定完整镜像。act -P ubuntu-latestcatthehacker/ubuntu:act-latest平台到镜像的默认映射逻辑可参考 cmd/platforms.go可选镜像清单含体积对比详见官方文档 IMAGES.md。坑2Apple 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-architecturelinux/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。坑7Secrets 没传进来Action 里读到空值act 的 secrets不区分大小写且会自动转大写。以下写法中token会被存成TOKENact -s tokenghp_xxx批量注入建议用--secret-file默认读取.secrets文件多行值用 YAML 格式书写完整规则见 cmd/secrets.go 与示例 cmd/testdata/secrets.yml。⚠️ 切勿使用--insecure-secrets它会在日志中明文打印所有密钥。坑8工作流里调 API 报 401GITHUB_TOKEN 为空act 会自动从本机ghCLI 读取 GitHub Token注入为GITHUB_TOKEN逻辑见 cmd/root.go。如果本地没装gh或未gh auth login所有需要鉴权的步骤都会 401。解决方案先登录 gh或手动注入act -s GITHUB_TOKENghp_xxx坑9容器里改的文件传不到工作区或垃圾文件被带进容器act 默认把本地工作区复制进容器大仓库或需要双向同步时很慢。解决方案用-b绑定挂载bind mount替代复制修改实时可见默认会按.gitignore过滤文件如需把 node_modules 等忽略目录也带进容器加--use-gitignorefalse需要跨次运行保留容器状态时加-rreuse。三个开关的定义见 cmd/root.go。坑10Docker 连不上报 Couldnt 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。 排障速查清单症状一行解决找不到 python/node 版本不对act -P ubuntu-latestcatthehacker/ubuntu:act-latestM 芯片启动告警/架构错误--container-architecture linux/amd64工作流语法存疑act -ndryrun 只校验不执行事件判断失效-e pull_request或-e event.jsongithub.ref 错误--defaultbranch mainsecrets 为空-s KEYVALUE或--secret-file .secretsAPI 调用 401先gh auth login或-s GITHUB_TOKEN...大仓库同步慢加-b绑定挂载docker 连接失败--container-daemon-socket socket路径把这套清单存下来配合.actrc固化常用参数act 本地调试就能稳定起飞 【免费下载链接】actRun your GitHub Actions locally 项目地址: https://gitcode.com/GitHub_Trending/ac/act创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考