工作流一片红，编译、测试还是打包环节出了问题却不清楚。
最快解法：先固定 runner 标签并保存失败步骤、架构和工具链证据，再按架构、工具链、依赖、测试与产物逐项排查；不要先盲目重装依赖。
维护 macOS 原生科研应用或跨平台科研软件 CI 的开发者，可以按本文缩小故障范围。
依赖 Homebrew、原生扩展或架构敏感库的研究生和科研开发者，可以用它区分环境问题与代码问题。
负责实验室 CI 和发布交付的高校技术人员，可以据此建立可复核的故障记录。
先分清工作流、构建、测试和交付故障
Actions 任务显示失败，并不等于 macOS 26 不兼容。先看失败发生在哪个 step：runner 初始化、依赖安装、编译、测试、签名，还是产物上传；失败命令和日志位置比红色状态本身更能说明问题。GitHub 说明，具体一次任务使用的镜像版本与预装软件版本，应以工作流日志中的 Set up job 信息核对，而不能只根据当前镜像说明推断。镜像信息可在 GitHub 官方 runner-images 仓库核对，但仓库内容会随镜像更新而变化。
macOS 26 runner 已正式可用，并提供 arm64 与 x64 标签；因此，runs-on: macos-26 本身不能当作“Intel 环境”的代称。GitHub 的公告列出了各标签对应的架构，标签选择应与被测目标相符。macOS 26 runner 正式可用公告
遇到失败时，先保留提交版本、工作流运行记录、失败 step 的完整日志和 runner 标识。若普通日志无法看出任务准备阶段出了什么问题，可按 GitHub 的调试日志说明开启 runner 或 step 诊断日志；日志可能包含路径、环境变量或内部地址，分享前要脱敏。
runner 架构不匹配时，先确认实际执行环境
同一个科研项目可能有不同的依赖二进制、原生扩展或编译选项。配置文件中的标签能说明你请求什么 runner，任务日志才适合用于确认这一轮实际用了什么镜像；建议将架构显式写进诊断输出：
- name: Record runner and toolchain
run: |
uname -m
sw_vers
xcode-select -p
xcodebuild -version
clang --version
brew --prefix
macOS 26 的官方标签及架构可概括如下，使用前仍应核对 GitHub 官方 macOS 26 镜像清单和当次日志。镜像预装软件会更新，清单不能替代单次任务记录。
| 工作流标签示例 | 官方列出的架构 | 适合用来验证什么 |
|---|---|---|
macos-26 |
arm64 | Apple Silicon 目标及 arm64 原生依赖 |
macos-26-intel |
x64 | Intel 目标及 x64 兼容性 |
macos-26-large |
x64 | 大型 x64 runner 上的构建路径 |
macos-26-xlarge |
arm64 | 大型 arm64 runner 上的构建路径 |
实际排查时，不要将不同架构的任务混成一个结果：给 arm64 与 x64 任务设置清楚的名称，分别安装并记录依赖，再比较失败是否只出现在一条架构路径上。runner 标签和实际输出不一致时，先查工作流继承的默认值、矩阵变量和 job 级覆盖；在身份确认前，不要据此修改项目源代码。
通过标准： 日志中的机器架构符合本次任务的目标，依赖及产物的架构也与之相符。
停止条件： 如果实际架构与预期不同，先修正 runner 选择并重跑最小任务，不要把由标签或矩阵配置造成的差异判成代码缺陷。
Xcode、SDK 和默认工具链变化要与代码错误分开
macOS 镜像可能预装多个工具版本，而项目若依赖未固定的系统默认值，镜像更新后就可能使用不同的 Xcode、SDK 或编译器。runner-images 仓库提供 macOS 26 软件清单，但具体版本应以该次 job 的镜像信息和 xcodebuild -version、xcode-select -p 输出为准；清单不应被当作永久固定的版本承诺。
| 日志证据 | 更可能的排查方向 | 低风险动作 |
|---|---|---|
| 编译器或 SDK 报错，且版本与项目基线不同 | 镜像工具链变更或默认版本漂移 | 记录当前版本，用项目支持的 Xcode 与 SDK 单独复测 |
| 同一工具链下出现可复现的源代码诊断 | 代码、条件编译或 API 使用 | 保存完整编译命令与报错上下文，缩小到最小重现 |
| 工作流没有指定工具版本，失败随镜像更新出现 | 隐式使用默认工具链 | 明确选择项目支持版本，评估是否需要暂缓升级 runner |
如果固定到项目已验证的工具链后构建通过，而切换新工具链就稳定失败，证据更支持环境兼容问题；如果两边使用同一编译器、SDK 和依赖仍出现相同源代码错误，再调查代码改动。不要一边升级系统、一边改依赖、一边改构建参数，否则复测成功也难以说明是哪项调整起作用。
评分对比（越适合当前任务越高）： 显式锁定 Xcode 与 SDK，在可复现性上为「高」、维护成本为「中」；完全依赖镜像默认版本，可复现性为「低」、维护成本为「低」；新旧 runner 双轨运行，可复现性为「高」、维护成本为「高」。这里的评分是排障取舍，不是官方性能或成功率数据。
Homebrew 和原生依赖故障要从来源与缓存查起
Apple Silicon 与 Intel 上的 Homebrew 默认安装路径不同：Apple Silicon 使用 /opt/homebrew，Intel 使用 /usr/local。当工作流恢复了旧缓存、环境变量指向另一套安装位置，或扩展链接到错误架构的库时，就可能出现找不到包、链接失败或运行时加载错误；对应路径可参考 Homebrew 官方 FAQ。
逐项记录 brew --prefix、brew config、依赖版本、安装来源和锁定文件。对于 Python、Ruby、R 或其他包含原生扩展的科研项目，也记录实际解析出的包版本与二进制架构；包管理器显示“已安装”并不等于扩展与当前 runner 架构匹配。优先在临时分支或隔离任务中关掉缓存、重新安装，再与原任务比较，避免直接更改全组权限或清空所有共享缓存。
缓存命中只表示找到了符合匹配规则的缓存，并不能单独证明其中的库与当前架构兼容。GitHub 的缓存文档说明，缓存键和 restore key 会影响恢复结果，也建议用依赖文件参与缓存键设计；核对 依赖缓存的匹配规则，再决定是否按架构、工具链或锁定文件区分缓存。
若干净安装仍然失败，查项目依赖的官方安装说明和支持平台范围；不要因为某个包在另一台 Mac 上可用，就推断它一定支持当前系统、架构或 SDK。通过标准： 干净环境按锁定文件得到预期依赖，并成功完成链接或导入。停止条件： 依赖没有目标架构构建，或项目官方文档明确排除当前环境时，记录为支持边界，先维持受支持的构建路径。
构建成功后，还要分别验收测试与交付产物
“Build”通过、测试通过和产物能在目标机器运行，是不同的验收结论。数值分析应比较预期结果与可容忍误差；图形、外设和硬件相关测试要确认 runner 是否具备对应条件；签名、打包和运行失败则要检查实际生成文件、架构、链接库和交付步骤。不要把 CI 中未执行的硬件测试写成已通过。
用不含敏感研究数据的最小样本运行失败用例，并保存预期输出、测试报告和产物校验依据。GitHub 的 workflow artifacts 文档说明，构建文件、测试报告和日志等可以作为工作流产物保存；按高校的数据制度审查上传内容，切勿把参与者信息、未公开样本、访问令牌或内部服务地址直接放入 artifacts 或缓存。
通过标准： 能确认 CI 验证的是预期提交生成的文件，产物架构和运行环境匹配，并且最小样本的结果符合项目验收要求。停止条件： 缺少硬件、图形或真实数据条件时，应标注“CI 未覆盖”，安排合规的专用环境复测，而不是将其标为通过。
按清单决定继续、双轨验证还是改用 Mac 复测
- [ ] 保存失败 step、提交标识、runner 标签、镜像版本和架构输出。
- [ ] 记录 Xcode、SDK、编译器及依赖锁定文件对应的实际版本。
- [ ] 用隔离任务验证依赖是否来自正确架构，并比较干净安装与缓存恢复结果。
- [ ] 分开记录编译、测试、产物签名、打包和目标设备运行的结果。
- [ ] 移除研究数据、凭据、内部地址等敏感信息后，再分享日志与产物。
- [ ] 根据能否稳定复现和依赖支持范围，选择保留旧路径、双轨验证或固定 Mac 环境。
| 当前证据 | 建议路径 | 何时停止或回退 |
|---|---|---|
| 故障只在一个标签或架构出现，且可稳定复现 | 保留现有稳定 runner，同时建立目标架构验证任务 | 目标架构依赖缺失时，先回退到依赖支持的平台 |
| 工具链差异能解释失败，固定已验证版本后恢复 | 固定工具链并单独评估升级 | 新版本尚未完成项目验收时，不要移除旧构建路径 |
| CI 通过，但真实 Mac、图形或外设相关测试未覆盖 | 增加真实 Mac 复测并保存独立验收记录 | 无法满足数据制度或硬件条件时，标记未验收 |
| 同一问题在匹配架构的 Mac 上也能稳定复现 | 依据最小重现调查代码、依赖或系统行为 | 在证据不足前，不要把问题简单归为 runner 故障 |
macOS 科研软件 CI 的“绿灯”只代表已执行的任务通过，不能证明整个科研流程、真实设备和结果复核均已验收。遇到需要真实 Apple Silicon 环境确认的故障，先按实验室的数据管理要求准备脱敏样本与最小依赖，再选择临时复测还是保留长期设备；稳定、持续的高负载或必须连接实体设备的场景，应先评估自购设备或实验室现有 Mac，而不是默认租用。
如果问题需要隔离环境短期复现，SSHMac 的远程 Mac 租赁方案可作为额外的复测选项；开始前核对项目对架构、数据存放和访问方式的要求，并通过远程 Mac 的 VNC 连接说明确认交互方式是否适合你的验收流程。远程 Mac 不能替代 GitHub Actions 的重复构建，也不适合必须接入本地物理外设或需要长期稳定满载的项目；真正复现后，仍应将环境信息、测试结果和产物校验记录归档。
常见问题 FAQ
为什么 macOS 26 任务找不到 arm64 依赖？
先确认实际 runner 架构，而不是只看 YAML 标签；日志可打印 uname -m 和 brew --prefix。Apple Silicon 与 Intel 的 Homebrew 默认前缀分别为 /opt/homebrew 和 /usr/local，缓存或环境变量混用时尤其值得检查。隔离缓存并按锁定文件干净安装；若依赖没有目标架构版本，按项目支持边界回退，不要用权限修改掩盖问题。
Apple Silicon runner 上编译失败，怎样定位到具体环节？
将失败 step 的编译命令、编译器版本、SDK、目标架构和依赖解析结果保存到同一条记录。先比较最近一次成功运行，再用不恢复缓存的隔离任务复测；头文件或库路径错误优先查架构与安装来源，明确的源代码诊断则在工具链对齐后调查代码。一次只改变一个变量，避免重装、升级和修改编译参数同时发生。
macOS 26 runner 与本地 Mac 结果不一致怎么办？
对齐芯片架构、Xcode、SDK、依赖锁文件和缓存状态，再用同一提交与最小样本复测。分别保留两边的完整日志和产物信息；若差异只在某一环境出现，逐项隔离工具链、环境变量或硬件条件。图形、外设和真实数据相关的测试还需单独核实 CI 是否具备对应条件，不能仅凭本地通过判定 CI 有缺陷。
Actions 测试通过，产物却无法运行，应从哪里查？
先确认被下载和启动的文件，确实是本次任务生成并上传的产物；再检查其架构、链接依赖、签名和打包路径。用目标 Mac 上的脱敏最小样本执行启动验证，并记录预期输出、错误日志及产物校验值。测试通过只覆盖实际执行的测试范围，不等于目标设备兼容或完整科研流程验收；未覆盖的项目应明确标记并补做复测。