PAYATHON 2026

Xcode 26 构建的 App 为何在 iOS 17 启动时因 RealityKit 符号缺失崩溃？

数据阿明

结论

崩溃发生在 dyld 加载 XXX.framework 时。日志显示，该 framework 引用了 RealityFoundation.framework 中不存在的符号：ShapeResource.generateConvex(from:) 的异步、抛错变体。代码中的 await 与缺失符号名里的 async 标记相符。generateConvex 可能还有更早引入的其他变体，但这不能证明该异步变体在 iOS 17 上可用。

if #available 和辅助方法上的 @available 通常用于限制 API 调用的执行条件。当前日志显示，应用启动时 dyld 就无法解析 framework 中的符号引用。如果这个引用在最终二进制中是强引用，即使对应代码没有执行，应用也可能无法启动。要判断原因是 API 可用性声明、编译器或链接器行为，还是 framework 中的其他调用引入了该引用，需要检查实际构建产物。

先确认缺失的是哪个变体

日志中的符号来自这一行：

return try! await ShapeResource.generateConvex(from: model.mesh)

await 表明这里调用的是异步接口。缺失的可能是这个异步签名，而不是整个 generateConvex API。以当前错误为准：运行设备上的 iOS 17 RealityFoundation.framework 没有日志列出的符号。

处理步骤

  1. 检查最低系统版本兼容的 API 签名。 查阅当前 Xcode SDK 的接口声明或编译器补全，确认 iOS 17 是否提供不带 async 的兼容变体。如果有，而且满足调用需求，可以改用该变体并去掉 await。方法名相同，或 API 的其他变体较早引入，都不能证明异步变体也兼容。

  2. 检查最终 framework 是否仍引用该符号。 查看构建产物中的未定义符号及其导入属性，例如用 nm 检查 XXX.framework/XXX，并查看链接信息。确认该引用是否为 weak import，以及其他文件或依赖 framework 是否也调用了这个异步接口。还可以检查链接命令和 SDK 接口声明中的可用性信息。

  3. 确认保护条件覆盖实际调用。 如果必须保留该调用，应将它放在 if #available(iOS 18.0, *) 分支中，并确保 iOS 17 可达的代码路径不会直接或间接引用它。你已尝试使用条件判断并标记辅助方法。如果二进制仍保留强符号引用，继续添加同类标注未必能解决加载失败。

  4. 若工具链仍生成无法在 iOS 17 加载的引用，隔离这段实现。 确认链接结果后，可以将依赖该符号的代码放入只在受支持系统上加载的独立模块，或为旧系统提供不引用该符号的实现。如果采用动态加载方案，还需要处理模块加载失败。可用性判断不会自动将强链接变成弱链接。

注意事项

try! 会在异步调用本身抛错时触发运行时陷阱，但这不是本次 dyld 启动错误的直接原因。当前失败发生在方法调用执行之前。改用 try 后，可以单独处理运行期间的生成错误。

报错显示引用来自 XXX.framework，因此检查范围应包括该 framework 及其依赖，不能只看 App target 中显示的调用位置。仅凭这段日志无法判断是哪项构建设置导致强引用，也无法确认目标 SDK 中替代接口的具体签名。应以接口声明和最终二进制检查结果为准。

备注：内容仅供参考。