Xcode 16.4 + iOS 18 系统运行时崩溃：___cxa_current_primary_exception 符号丢失的原因与解决方案

news2025/6/6 19:59:35

在使用 Xcode 16.4 构建项目，运行到 iOS 18.3 或更早版本系统（包括模拟器）时，出现了如下的运行时崩溃：

dyld[22183]: Symbol not found: ___cxa_current_primary_exception
  Referenced from: /.../WidgetOn.app/WidgetOn.debug.dylib
  Expected in:     /usr/lib/libc++.1.dylib

本文将讨论一下这个运行时报错的解决方案。

问题背景

这是一个典型的 运行时动态链接失败（dyld） 错误，表面上是找不到 ___cxa_current_primary_exception 符号，实质上是 Swift 6.1 / Xcode 16.4 使用的 C++ ABI 运行时 与老版本 iOS 不兼容。

崩溃根因解析

在 iOS 18.4 及更高版本中，Apple 对 libc++ 动态库的内部结构做了修改：

一些 C++ 异常处理相关符号（如 ___cxa_current_primary_exception）原本只存在于 libc++abi.dylib 中；
在新系统中，这些符号被“重定向（indirect）”到 libc++.dylib，并不再直接暴露在 libc++abi.dylib；
编译器在链接时会以为这些符号来自 libc++.dylib；
但当 App 在旧版系统上运行时，libc++.dylib 并没有这些符号；
于是 dyld 报错：符号找不到，程序崩溃。

一句话就是Apple 在 iOS 18.4+ 系统中变更了 C++ ABI 符号分布，导致旧系统运行时找不到某些关键符号。

解决方案：强制链接顺序以确保兼容

为了解决这一兼容性问题，我们需要：

让链接器优先从 libc++abi.dylib中加载符号，而不是 libc++.dylib

方法：在项目的 Other Linker Flags（OTHER_LDFLAGS）中添加：

-Wl,-force_load,$(SDKROOT)/usr/lib/libc++abi.tbd
-Wl,-weak_library,$(SDKROOT)/usr/lib/libc++.tbd
-Wl,-weak_library,$(SDKROOT)/usr/lib/libc++.1.tbd

参数说明：

参数	说明
-Wl	将参数传递给底层链接器 ld
-force_load	强制包含指定库中的全部符号
-weak_library	链接为可选库，在旧系统不存在时不会报错
$(SDKROOT)	当前 Xcode 使用的 SDK 路径

出现问题的常见来源

可能会在以下场景中遇到该问题：

使用 C++ 混编或 Objective-C++；
引入某些广告 SDK、调试 SDK、动态注入工具（如 InjectionIII）；
系统调试工具在构建时注入 .debug.dylib；
.xcframework 或 binary-only pod 中静态链接了 libc++。

建议配置方式：使用 .xcconfig

推荐在工程中新建一个配置文件 CompatibilityFlags.xcconfig，写入：

// 在 iOS 18.4 及以上版本 中，很多原本只存在于 libc++abi.dylib 中的符号（例如 ___cxa_current_primary_exception），现在被间接定义到了 libc++.dylib 中；
// 但在 iOS 18.3 及以下版本 中，这些符号在 libc++.dylib 中根本就不存在，是“未定义”的。所以当你编译时链接的是 libc++.dylib 中的符号；运行时在老系统中找不到对应实现；
// 导致 dyld（动态链接器）报错，应用在启动时崩溃。
// 解决办法是 强制链接顺序：让 libc++abi.dylib 的链接优先于 libc++.dylib。编译器会把符号绑定到 libc++abi.dylib 而不是 libc++.dylib
OTHER_LDFLAGS = $(inherited) \
  -Wl,-force_load,$(SDKROOT)/usr/lib/libc++abi.tbd \
  -Wl,-weak_library,$(SDKROOT)/usr/lib/libc++.tbd \
  -Wl,-weak_library,$(SDKROOT)/usr/lib/libc++.1.tbd

然后在 Xcode 中为 Debug 或所有构建配置导入使用它。