react-native-payments 导致 iOS 构建出现 Undefined symbol

2026-10-10支付阿杰

结论

Undefined symbol: _OBJC_CLASS_$_RCTConvert 说明 react-native-payments 的原生 iOS 代码已经参与编译，但在链接阶段，React Native 中提供 RCTConvert 的模块没有被正确链接。

问题通常不在 Apple Pay、Stripe 或 PassKit.framework 本身。常见解决办法包括重新安装 CocoaPods、确认依赖已加入正确的 iOS target，以及修正旧版 react-native-payments 对 React Native 原生依赖的声明。

重新安装 iOS 依赖

在项目根目录执行：

cd ios
pod install --repo-update

如果项目使用 Bundler：

cd ios
bundle exec pod install

安装完成后，请使用 .xcworkspace 打开项目，不要打开 .xcodeproj：

open YourProject.xcworkspace

然后在 Xcode 中执行：

Product → Clean Build Folder

清理后重新构建。

较新的 React Native 项目通常使用自动链接，不需要手动将 react-native-payments 添加到 Xcode 的 Libraries 中。如果自动链接和手动链接同时存在，可能导致依赖重复或链接配置冲突。

检查 Podfile 的 target

确认 React Native Pods 和支付模块位于应用实际使用的 target 中。例如：

target 'YourApp' do
  config = use_native_modules!

  use_react_native!(
    :path => config[:reactNativePath]
  )

  # 其他 Pods
end

修改后重新安装：

cd ios
pod install

如果项目包含多个 target，例如正式版、测试版或扩展 target，还要确认当前构建的应用 target 中也包含 React Native 相关 Pods。

检查包是否声明 React Native 依赖

部分旧版 react-native-payments 可能没有适配当前 React Native 的 CocoaPods 结构。它的 .podspec 应声明对 React Native 核心模块的依赖。对于采用 React-Core 拆分结构的 React Native 版本，通常需要类似配置：

Pod::Spec.new do |s|
  # 其他配置省略

  s.dependency 'React-Core'
end

不要把直接修改 node_modules 作为长期方案，因为重新安装依赖后，这些改动会消失。确认修改有效后，可以通过以下方式保留：

升级到已经修复 .podspec 的包版本；
使用仍在维护的 fork；
使用 patch-package 保存补丁；
在自己的 fork 中添加 s.dependency 'React-Core'。

具体的依赖名称取决于项目使用的 React Native 版本。很旧的 React Native 工程可能使用完整的 React Pod，而不是 React-Core，因此不能不区分版本就同时添加两者。

旧版 React Native 项目的处理方式

如果项目仍采用手动链接，而不是 CocoaPods 自动链接，需要确认应用 target 的链接配置中包含：

react-native-payments 生成的原生库；
React Native 对应的原生库；
支付功能所需的系统 framework，例如 PassKit.framework。

在 Xcode 中检查：

Target → Build Phases → Link Binary With Libraries

不过，_RCTConvert 来自 React Native。仅添加 PassKit.framework 无法解决这个符号缺失问题。

清理残留的 Pods 和构建缓存

如果 Podfile 配置正确，但错误依然存在，可以重新生成 Pods：

cd ios
pod deintegrate
pod install

之后清理 Xcode 的 Derived Data，重新打开 .xcworkspace 并构建。清理缓存只能移除旧的链接结果，不能替代正确的依赖声明。

仍然报错时需要检查什么

查看 Xcode 错误信息中 Referenced from: 后面的对象文件，可以确定哪个原生模块引用了 RCTConvert。如果引用者确实是 react-native-payments，并且 React-Core 已正确链接，还需要继续检查：

当前包版本是否支持项目所用的 React Native 版本；
项目是否启用了 use_frameworks!；
手动链接和自动链接是否同时存在；
项目是否启用了 React Native New Architecture，而旧模块只支持 Legacy Architecture；
Pod 是否安装到了错误的 target。

如果关闭 New Architecture 后能够成功构建，只能说明该模块可能存在兼容性问题，并不意味着关闭它适合作为长期方案。对于长期无人维护的支付库，更稳妥的选择是迁移到仍在维护，并明确支持当前 React Native 和 iOS 构建体系的支付 SDK。