React Native iOS 编译链接错误排查：libc++ 缺失

在将 React Native 集成到现有 iOS 项目时，经常会遇到各种编译问题。本文记录了一个典型的链接错误排查过程：项目编译阶段正常通过，但在链接阶段大量 C++ 标准库符号未定义，导致 BUILD FAILED。通过对比一个能正常编译的参考项目，最终定位并修复了问题。

问题现象

使用 xcodebuild 编译 KlilalaRN 项目时，链接阶段报出大量未定义符号错误：

Undefined symbols for architecture arm64:
  "std::__1::shared_ptr<...>::~shared_ptr()", referenced from:
      ...
  "std::__1::__shared_weak_count::~__shared_weak_count()", referenced from:
      ...
  "operator delete(void*)", referenced from:
      ...
  "operator new(unsigned long)", referenced from:
      ...
  "___gxx_personality_v0", referenced from:
      ...
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1

这些符号全部来自 C++ 标准库（libc++），涉及 std::shared_ptr、std::weak_ptr、operator new/delete、异常处理（___cxa_*、___gxx_personality_v0）等基础 C++ 运行时设施。

错误来源指向两个 React Native 的 C++ 静态库：

libReactCodegen.a — React Native 新架构的代码生成库
libreact-native-safe-area-context.a — safe-area-context 的原生组件库

排查过程

1. 对比参考项目

有一个结构相似的参考项目 xx_proj 能正常编译通过。对比两个项目的配置文件：

Podfile — 几乎完全一致，仅 target 名称不同。

package.json — 依赖版本完全一致：

{
  "react": "19.2.3",
  "react-native": "0.86.0",
  "react-native-safe-area-context": "^5.5.2"
}

Pods xcconfig — OTHER_LDFLAGS 内容一致，均包含 -ObjC 但都没有 -lc++。

2. 对比 Xcode 项目构建设置

关键差异在 project.pbxproj 的构建设置中：

参考项目（xx_proj） 的项目级别配置：

CLANG_CXX_LANGUAGE_STANDARD = "c++20";
CLANG_CXX_LIBRARY = "libc++";          // ← 关键差异

参考项目 的 target 级别配置：

OTHER_LDFLAGS = (
    "$(inherited)",
    "-ObjC",
    "-lc++",                            // ← 关键差异
);

KlilalaRN 的项目级别配置：

CLANG_CXX_LANGUAGE_STANDARD = "c++20";
// 缺少 CLANG_CXX_LIBRARY

KlilalaRN 的 target 级别配置：

// 完全没有 OTHER_LDFLAGS

3. 验证链接命令

通过查看实际的链接命令，确认 -lc++ 确实没有被传递给链接器：

# KlilalaRN 的链接命令（简化）
clang ... -ObjC -lReactAppDependencyProvider -lReactCodegen \
    -lreact-native-safe-area-context -framework React ... -lPods-KlilalaRN -o KlilalaRN
# 没有 -lc++

根本原因

React Native 0.86 的新架构大量使用 C++ 实现，其静态库（ReactCodegen、react-native-safe-area-context 等）依赖 libc++ 中的符号。要正常链接，需要同时满足两个条件：

编译器需要知道使用哪个 C++ 标准库 — 通过 CLANG_CXX_LIBRARY = "libc++" 指定。该设置影响编译阶段的头文件搜索和 ABI 选择。
链接器需要链接 libc++ — 通过在 OTHER_LDFLAGS 中添加 -lc++ 显式指定。CLANG_CXX_LIBRARY 设置不会自动传递给链接器，需要手动添加链接标志。

缺少任何一个都会导致链接阶段找不到 C++ 标准库符号。Pods xcconfig 中的 $(inherited) 只会继承项目级别的 OTHER_LDFLAGS，如果项目本身没有定义，继承结果就是空。

修复方案

在 ios/KlilalaRN.xcodeproj/project.pbxproj 中补充两项配置：

项目级别：添加 CLANG_CXX_LIBRARY

在 Debug 和 Release 两个项目级配置中，于 CLANG_CXX_LANGUAGE_STANDARD 之后添加：

CLANG_CXX_LANGUAGE_STANDARD = "c++20";
CLANG_CXX_LIBRARY = "libc++";       // 新增

Target 级别：添加 OTHER_LDFLAGS

在 Debug 和 Release 两个 target 级配置中，添加链接器标志：

OTHER_LDFLAGS = (
    "$(inherited)",
    "-lc++",
);

修复后验证

xcodebuild -workspace ios/KlilalaRN.xcworkspace \
    -scheme KlilalaRN \
    -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
    -configuration Debug clean build

输出 ** BUILD SUCCEEDED **，编译通过。

总结

配置项	作用	缺失后果
`CLANG_CXX_LIBRARY = "libc++"`	告诉编译器使用 libc++ 标准库	编译阶段可能使用错误的 C++ ABI
`OTHER_LDFLAGS` 中的 `-lc++`	告诉链接器链接 libc++	链接阶段 C++ 标准库符号未定义

当 React Native 项目出现大量 std::__1::*、operator new/delete、___cxa_*、___gxx_personality_v0 等 C++ 标准库符号的链接错误时，优先检查这两项配置是否缺失。这是将 React Native 新架构集成到已有 iOS 项目时的常见遗漏。

Shaula Blog