现象
用 Xcode 27 编译主工程时,若本地 RN Runtime 仍是 Xcode 26.6 打的预编译包,链接阶段失败:
Undefined symbols for architecture arm64:
method descriptor for Cxx.CxxPair.first.getter
method descriptor for Cxx.CxxPair.second.getter
来源:NitroModules(AnyMap.o)
反向也成立:Xcode 27 的包拿到 Xcode 26.6 下去编,会缺另一组 Iterable / makeBorrowingIterator 相关符号。
结论(先看这个)
这不是某个编译参数(-fxxx / OTHER_SWIFT_FLAGS / BUILD_LIBRARY_FOR_DISTRIBUTION)能补丁过去的问题。
根因是:
Swift 6.3.3(Xcode 26.6) → Swift 6.4(Xcode 27)
系统自带的 Swift–C++ 互通层(Cxx overlay)里,CxxPair 协议的 ABI 变了。预编译的 NitroModules 已经写死了对「旧 method descriptor」的引用;消费端换编译参数,补不出这些符号。
因此:同一套预编译 RN Runtime,不能跨 Xcode 大版本混用。
官方有痕迹,但没有面向 App 开发者的点名预警。官方提前说的是「C++ 互通还在变,用兼容模式保源码」,没有提前说「Xcode 26 的 Swift–Cxx 预编译包不能给 27 链接」。这是语言演进的必然结果,不是未公开的私有变更;发行说明漏了二进制兼容这一层。
二进制证据(nm + demangle)
两套 NitroModules 对 Cxx.CxxPair 的「未定义符号」不同。关键变化:getter(vg) → read / borrow accessor(vr),属性访问从「经典 getter(返回拷贝)」变成了「borrowing _read」。
Overlay 源码变化(CxxPair)
Xcode 26.6 / Swift 6.3.3:
public protocol CxxPair<First, Second> {
associatedtype First
associatedtype Second
init(first: Self.First, second: Self.Second)
var first: Self.First { get set }
var second: Self.Second { get set }
}
Xcode 27 / Swift 6.4:
public protocol CxxPair<First, Second> : ~Copyable {
associatedtype First : ~Copyable
associatedtype Second : ~Copyable
init(first: consuming Self.First, second: consuming Self.Second)
var first: Self.First { get set }
var second: Self.Second { get set }
}
说明:
- 表面仍是
{ get set }; - 但协议与关联类型变成
~Copyable(非拷贝); - 编译器因此生成
borrowing _read(mangling:vr),不再生成旧的vggetter; AnyMap等走std::pair → CxxPair的代码,会把对应 descriptor 链进.o。
为什么改编译参数救不了
- 消费端参数改不了已进包的 relocation:undefined symbol 已经写在预编译的
AnyMap.o里。 - BUILD_LIBRARY_FOR_DISTRIBUTION / Library Evolution 帮不上:Swift–C++ 导入类型不支持稳定的 library evolution;Nitro 上游也明确过这一点。硬开反而更容易出 witness / 重复符号问题。
- 这不在「普通 Swift ABI 稳定」承诺范围内:平台 Swift 主路径相对稳定;Cxx overlay 仍在演进(这次就是 6.4 为 ownership / 非拷贝改了协议形态)。没有「编一次、跨大版本 Xcode 通用」的官方保证。文档里的 compatibility version 保的是重新编译,不是混链旧 xcframework。
和「pod install 不同步」要分开看
另一份日志里还有:
The sandbox is not in sync with the Podfile.lock
那是 CocoaPods Manifest 检查失败,几秒就停,还没到链接。和上面的 CxxPair ABI 问题不是一类。
另外注意:终端 xcode-select 可能指向 Xcode_26.6,而 GUI 打开的 Xcode.app 可能是 27.0。pod install / fetch 脚本若跟错工具链,会继续装到错误大版本的二进制。
可行方案
短期(推荐):按 Xcode 大版本分发两套预编译(26.x / 27.x),精确匹配优先,同大版本 fallback。这是和 ABI 现实一致的做法,不是偷懒。
中期(若想少打包):把会碰到 Swift–Cxx overlay 的部分(至少 NitroModules 的 Swift 侧)改为随宿主工具链源码编译;其余无 Swift interop 的 xcframework 仍可预编译共享。
不现实 / 不建议押宝:
- 指望一个编译 flag 打通 26↔27;
- 指望 Apple 短期内冻住 Cxx overlay ABI;
- 仅靠
BUILD_LIBRARY_FOR_DISTRIBUTION做跨版本二进制。
以后看 overlay 变更,优先查 swiftlang/swift 的 cxx-interop PR,以及 Swift Evolution 里 get vs _read 的 ABI 说明;不要只看 Xcode Release Notes 的 New Features。
名词补充
- Swift–C++ 互通(Cxx interop):Swift 直接导入和使用 C++ 类型 / 模板的能力,依赖一套叫 Cxx overlay 的标准库映射。overlay 仍在快速演进,是 ABI 不稳定的重灾区。
- CxxPair / ~Copyable:
CxxPair是 overlay 对std::pair的 Swift 协议表达;~Copyable(非拷贝类型,SE-0390/SE-0474)让类型可以禁止拷贝,yielding accessors(SE-0474)把属性访问从 getter 改成 borrowing_read,从而改变 mangling 与 ABI。 - BUILD_LIBRARY_FOR_DISTRIBUTION(BLFD):Swift 的 Library Evolution / Module Stability 开关,开启后输出
.swiftinterface以支持跨工具链导入;但 Swift–Cxx 导入类型不支持稳定的 library evolution,所以救不了本次问题。 - NitroModules:React Native 的新一代原生模块桥接框架,底层大量使用 C++ 模板与 Swift–Cxx 互通,因此首当其冲受 overlay ABI 变化影响。