症状：Xcode 27 Beta 构建时，XCFramework 报目标不兼容、找不到架构或链接失败。 最快解法：先确认包里有与当前构建目标匹配的平台变体，再检查该变体的架构切片和实际链接文件；不要先用 Rosetta 启动 Xcode，也不要盲目合并二进制。
谁该看：维护 Apple 平台 SDK 或二进制依赖、需要分发 XCFramework 的开发者。 本机能构建、远程 Mac CI 却在链接阶段失败的工程师。 需要判断错误来自依赖包、构建目标，还是 CI 节点环境的 Apple 平台团队。
截至 2026 年 10 月 6 日，Apple 的发行说明列出 Xcode 27 Beta 6，同时也列出 Xcode 26.6 等版本；Xcode 27 Beta 仍是 Beta，不应当作稳定正式版处理。Beta 6 要求运行于 macOS Tahoe 26.4 或更高版本的 Mac。把 Beta 版本、宿主系统和具体报错一并记录，避免把工具链差异误判成依赖架构问题。可核对 Apple 的 Xcode 发行说明目录和 Xcode 27 Beta 6 发行说明。
先按故障阶段缩小范围
“架构错误”不是单一故障类型。先看完整日志中的失败 Target、构建 Destination 和出错阶段：编译时报模块或头文件不可用，链接时报找不到目标架构或库，运行时报动态库加载失败，三者的排查路径不同。
| 观察到的现象 | 优先检查 | 暂时不要做 |
|---|---|---|
| 编译或模块导入失败 | 目标平台、模块名、Headers 与当前 SDK 的匹配关系 | 先改 ARCHS |
| 链接时报平台或架构不匹配 | XCFramework 变体清单、二进制架构、实际链接路径 | 把设备库与模拟器库合并 |
| 构建成功但启动时报库加载错误 | 动态 framework 的嵌入位置、签名和运行时依赖 | 把运行错误归类为编译器故障 |
| 只有远程 Mac CI 失败 | Xcode 选择、依赖解析结果和产物版本 | 直接清缓存后宣告修复 |
快速诊断评分
以下评分是按“该检查对定位原因的直接程度”做的排障优先级判断，不是故障发生率或修复成功率。
| 检查动作 | 定位直接性 | 适用情况 |
|---|---|---|
| 核对目标平台变体 | ★★★★★ | 模拟器、设备、macOS 或 Mac Catalyst 目标不明确 |
| 检查被选中二进制的架构 | ★★★★★ | 日志明确提到架构不支持或找不到切片 |
| 对照实际链接路径和包内清单 | ★★★★☆ | 清单看似正确，但链接器仍报错 |
| 本机与远程 Mac CI 做同提交对照 | ★★★★☆ | 只有远程节点复现，或两端结果不同 |
| 先改架构排除项或通过 Rosetta 重试 | ★☆☆☆☆ | 可能掩盖依赖缺片问题，不作为首轮修复 |
核对 XCFramework 平台变体
把当前 Destination 写清楚，再和包中声明的变体逐项核对。iOS 真机、iOS Simulator、macOS 和 Mac Catalyst 是不同目标；即使两个二进制都带有 arm64，也不能据此认定它们能互换。Apple 的创建指南为不同平台分别指定归档目标，并支持为 Mac Catalyst 指定独立变体。
| 项目实际目标 | 必须匹配的变体 | 最容易误判的地方 |
|---|---|---|
| iOS 真机 | iOS 设备变体 | 只看到 arm64 就认为模拟器也能用 |
| iOS Simulator | iOS Simulator 变体 | Apple Silicon Simulator 与 iOS 真机平台标签不同 |
| macOS | macOS 变体 | 将 Catalyst 产物当成原生 macOS 产物 |
| Mac Catalyst | Mac Catalyst 变体 | 只检查 CPU 架构，漏看变体类型 |
Info.plist，确认 AvailableLibraries 中列出的标识、平台和可选平台变体，能否对应当前目标。创建 XCFramework 时应为各支持平台分别创建 archive，再组合成包；不要只靠手工指定 -arch 和 -sdk 推断目标正确。
检查目标变体内的架构切片
平台变体正确，不代表里面一定有当前构建所需的架构。先从 XCFramework 清单找到当前 Destination 对应的 LibraryIdentifier 和二进制路径，再检查实际文件，而不是检查另一份同名 framework。
plutil -p MySDK.xcframework/Info.plist
file MySDK.xcframework/<LibraryIdentifier>/MySDK.framework/MySDK
lipo -archs MySDK.xcframework/<LibraryIdentifier>/MySDK.framework/MySDK如果包里是静态库，检查对应的 .a 文件。检查结果要和当前 Destination 对照，不能因为另一变体包含相同架构名，就认定所选产物适用。
对于 Apple Silicon Simulator，检查的是 iOS Simulator 平台变体里的架构切片，而不是只问二进制是否出现 arm64。如果只有设备变体，或 Simulator 变体不含所需切片，应更新依赖、从源代码重建，或联系供应方提供兼容产物。Apple 的 TN3117 架构错误说明建议重建库或向供应方获取更新的预编译库；不应把通过 Rosetta 启动 Xcode 当成这类错误的通用修复。
注意：不要把面向 iOS 设备和 iOS Simulator 的架构片段用
lipo合成一个文件来绕过平台差异。架构检查可以帮助诊断，但“架构相同”不等于“平台兼容”；设备与模拟器应保留各自的变体。
对照包内声明和实际链接文件
当清单显示目标变体存在、架构看起来也匹配，下一步是确认构建系统实际链接的是否就是那份二进制。仓库里可能存在旧版本副本、重复依赖、手工指定的 framework 搜索路径，或者包更新后未同步的构建产物。
- 从链接日志中找到实际参与链接的 framework 或 library 路径。
- 将该路径与 XCFramework
Info.plist中对应变体的LibraryPath对照。 - 对实际链接文件运行
file，必要时再用lipo -archs检查架构。 - 检查它是
.framework还是.a：创建包时应按文件类型使用对应的 framework 或 library 参数；静态库还需提供 headers。不要把.a错装成省略扩展名的 framework。 - 如果通过 Swift Package Manager 分发远程二进制，确认包清单中的 URL 和 checksum 对应当前发布的 ZIP；checksum 不匹配时，Xcode 会报告错误。
比较本机与远程 Mac CI 环境
同一提交在本机通过、远程 Mac CI 失败，并不能单独证明是 CI 节点故障。两端可能选择了不同 Xcode、解析到不同依赖版本、采用不同构建设置，或从缓存与制品库取得了不同二进制。
按以下顺序做可重复对照：
- 固定提交、scheme、构建配置和 Destination；记录完整失败日志。
- 分别记录本机与 CI 的
xcodebuild -version、xcode-select -p输出，确认实际使用的 Xcode，而不只看机器上安装了什么。 - 对照依赖锁定文件、二进制包 URL、checksum 和解析日志，确认两端取到同一版本产物。
- 导出
xcodebuild -showBuildSettings的相关设置，重点比较ARCHS、EXCLUDED_ARCHS、SDK、SDKROOT 和 framework 搜索路径。 - 清理后在 CI 重跑一次，但同时保留清理前后日志和依赖身份信息；单次成功只能说明该次构建通过，不能证明依赖获取与目标选择问题已消除。
ARCHS 等设置的含义。先比较两端实际生效的值，再决定是否需要修改；不要用全局 EXCLUDED_ARCHS 隐藏缺少切片的依赖。
如果团队缺少可重复的远程 Apple 平台验证环境，可以先从 MACGPU 的远程 Mac 环境入口了解可用方案；是否适合你的项目，仍要按所需 Xcode、目标平台和依赖复测流程判断。
用真实构建目标验收修复
修复不能只看“错误消失”。至少用项目实际支持的设备与模拟器 Destination 分别构建，并确认链接日志显示预期 XCFramework 变体。Xcode 27 Beta 6 附带 Swift 6.4 和 27 系列 Apple 平台 SDK；复测时应同时记录工具链与目标环境，避免不同版本的成功结果混在一起比较。
按结果作决策：
- 平台变体缺失：让依赖供应方提供对应变体；如果有源代码，则按 Apple 的平台归档方式重建 XCFramework。
- 变体存在但缺架构：获取包含所需切片的新产物，或重建依赖；不要把设备库与模拟器库合并。
- 包声明和实际文件不一致：修正打包路径、版本引用或制品发布流程，并重新核对实际链接文件。
- 只有 CI 解析结果不同：固定依赖解析与产物校验；保存提交、Xcode 版本、Destination、依赖身份和完整构建日志，作为后续回归基线。
- 仍无法确定来源：暂缓升级该依赖，保留当前可复现构建，并把最小复现日志交给依赖供应方。