React Native 新架构 iOS 报错怎么办？12 个新架构常见问题

React Native 新架构在 iOS 上报错，大多出在三个地方：pod install 时 Codegen 和预编译包没准备好，第三方库没适配新架构，以及 Hermes 与 JS bundle 的打包。先在 package.json 确认版本：0.76 起新架构默认开启，0.82 起只剩新架构，关闭开关已不起作用，所以改法是修 Codegen、升级库、重新 pod install，而不是关掉新架构。下面按「现象 → 原因 → 改法」整理 12 个常见问题，先看总表找到报错再跳到小节。版本信息以 React Native 官方博客和源码为准，截至 2026 年 10 月。

你的 React Native 版本处在新架构的哪个阶段？

同一个报错，在不同版本上的改法不一样。先在 package.json 里看 react-native 的版本号，对照下表。

版本	时间	和 iOS 端有关的变化
0.76	2024 年 10 月	新架构默认开启，还可以用 RCT_NEW_ARCH_ENABLED=0 关闭
0.81	2025 年 8 月	最后一个能用旧架构的版本；iOS 构建要求 Xcode 16.1 或更高
0.82	2025 年 10 月	只剩新架构，关闭开关被忽略；旧架构的库靠兼容层继续工作
0.84	2026 年 2 月	Hermes V1 成为默认引擎；iOS 默认使用预编译的 React Native 二进制；要求 Node.js 22.11 或更高
0.87	2026 年 8 月	iOS 端加入实验性的 Swift Package Manager 支持
0.88	2026 年 10 月	当前最新稳定版；支持 SceneDelegate；CocoaPods 仍完整支持

0.88 的发布说明提到，0.89 计划把 Swift Package Manager 设为默认，CocoaPods 之后再移除。本文按目前仍是主流的 CocoaPods 方式来写。

12 个新架构 iOS 报错怎么快速对照？

#	现象（节选）	原因	改法
1	pod install 报找不到 react_native_pods.rb	还没装 JS 依赖	先在项目根目录 npm install
2	required a higher minimum deployment target	部署目标低于 RN 或某个库的要求	用 min_ios_version_supported，不低于 15.1
3	pod install 下载预编译包失败或很慢	网络问题	重试，或设 RCT_USE_PREBUILT_RNCORE=0 从源码编译
4	No such module 'ReactAppDependencyProvider'、找不到 ReactCodegen 头文件	Codegen 产物没生成或被删了	重新 pod install
5	设了 RCT_NEW_ARCH_ENABLED=0 还是新架构	0.82 起只支持新架构	删掉这个开关，升级不兼容的库
6	TurboModuleRegistry.getEnforcing(...): 'Xxx' could not be found	原生模块没装进 App，或库不支持新架构	重新 pod install 并重新构建，查库的兼容性
7	pod install 提示 USE_HERMES=0 不再支持	JSC 已移出核心	删掉 USE_HERMES=0，要用 JSC 装社区包
8	启动即崩，日志里有 Wrong bytecode version	编译 JS 的 hermesc 和 App 里的 Hermes 版本不一致	升级后重新 pod install，清理旧构建
9	红屏 Could not connect to development server	手机连不上 Metro	同一局域网、放行 8081、允许本地网络
10	Release 包打开白屏或闪退	JS bundle 没打进 App	检查 Bundle React Native code and images 阶段
11	开了 use_frameworks! 后编译或链接报错	静态库与动态框架混用	用 USE_FRAMEWORKS=static，按库文档设置
12	升级后编译报大量找不到符号、头文件	原生模板文件没跟着升级	用 Upgrade Helper 对比，重新 pod install

pod install 阶段报错怎么改？

1. 找不到 react_native_pods.rb

RN 模板的 Podfile 第一段会用 node 去 node_modules 里找 react-native/scripts/react_native_pods.rb。刚克隆下来的项目没有 node_modules，pod install 一开始就失败，报错里会有 Cannot find module 和这个文件名。

先在项目根目录装 JS 依赖，再进 ios 目录。

1npm install
2cd ios
3pod install

2. 最低部署目标不够

1[!] CocoaPods could not find compatible versions for pod "xxx":
2  ...
3Specs satisfying the `xxx` dependency were found, but they required a higher minimum deployment target.

React Native 0.88 的 CocoaPods 脚本里 min_ios_version_supported 是 15.1。模板 Podfile 写的是 platform :ios, min_ios_version_supported，不要改成写死的更低版本。某个库要求更高时，把 Podfile 的 platform 和 App target 的 IPHONEOS_DEPLOYMENT_TARGET 一起提高到库的要求，再 pod install。

1platform :ios, '16.0'   # 某个库要求 16.0 时

3. 预编译包下载失败

0.84 起 pod install 默认下载 React Native 预编译好的 .xcframework，编译快很多。网络不好时这一步会卡住或报下载失败。先重试；一直下不来，可以设环境变量改回从源码编译，代价是第一次构建要多花不少时间。

1RCT_USE_PREBUILT_RNCORE=0 pod install

Windows 的 PowerShell 里写法不同，先设变量再执行。

1$env:RCT_USE_PREBUILT_RNCORE = "0"
2pod install

预编译模式下不能单步进入 React Native 内部的原生代码，自己写的原生代码照常可以断点。

4. Codegen 产物缺失

1No such module 'ReactAppDependencyProvider'
2'ReactCodegen/...h' file not found

新架构用 Codegen 根据 JS 里的类型声明生成原生胶水代码。pod install 时会运行它，把结果写进 ios/build/generated/ios，其中的 ReactCodegen 和 ReactAppDependencyProvider 又作为两个本地 Pod 装进工程。删过 ios/build、换了分支、新装了带原生代码的库，这些文件就可能缺失或过期。

改法是在 ios 目录重新 pod install。你自己写的 Turbo Native Module 没生成代码时，再检查 package.json 的 codegenConfig：jsSrcsDir 要指向放 spec 文件的目录，模块 spec 文件名要以 Native 开头，例如 NativeLocalStorage.ts，组件 spec 以 NativeComponent 结尾。规则见 Using Codegen。

第三方库不兼容新架构怎么办？

5. 关不掉新架构

0.82 起只有新架构。按官方博客，iOS 上用 RCT_NEW_ARCH_ENABLED=0 执行 pod install 会被忽略，脚本只打印一段警告，App 照样跑在新架构上。还依赖旧架构的项目，官方建议先停在 0.81 或 Expo SDK 54 完成迁移，再往上升级。

这个开关已经没有意义，从 Podfile 和 CI 脚本里删掉，避免误导后来的人。

6. 原生模块找不到，或库不兼容新架构

1Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'RNXxx' could not be found.
2Verify that a module by this name is registered in the native binary.

两类原因。第一类是原生部分根本没进 App：装了库之后没有 pod install，或者装完没有重新构建。第二类是库本身没适配新架构，兼容层也接不住它的用法。

先排除第一类，在 ios 目录 pod install，然后完整重新构建，不要只刷新 JS。还不行，按下面的顺序判断库的兼容性。

1. 在 reactnative.directory 搜这个库，看是否标注支持新架构。
2. 看库的 package.json 有没有 codegenConfig，有就说明作者做了新架构适配。
3. 看库的 GitHub Issues 里有没有 New Architecture 相关的问题和修复版本。
4. 升级到最新版。长期不维护的库，换成目录里标注支持新架构的替代库。

0.82 的发布说明表示，兼容层在可预见的将来会保留，同时支持两种架构的库在只有新架构的版本上也能继续工作。兼容层有已知限制，例如不支持访问自定义 Shadow Node，所以自定义布局类的原生组件最容易出问题。

Hermes 相关的 iOS 报错怎么处理？

7. USE_HERMES=0 不再支持

1Hermes is the default engine and JSC has been moved to community support.
2Please remove the USE_HERMES=0, as it is not supported anymore.

JavaScriptCore 已经移到社区维护的 @react-native-community/javascriptcore 包。按提示删掉 USE_HERMES=0。确实要用 JSC 的，按社区包的说明安装。想确认当前用的是不是 Hermes，在 JS 里判断 !!global.HermesInternal。

0.84 起默认引擎是 Hermes V1。0.84 的发布说明给了退回旧版 Hermes 的环境变量，较新版本的 pod 脚本已经固定启用 V1，以你所用版本的发布说明为准。

8. 启动即崩：Wrong bytecode version

Release 包里的 JS 会先用 hermesc 编译成字节码。编译用的 hermesc 和 App 里链接的 Hermes 引擎版本不一致，App 一启动就崩，日志里能看到 Wrong bytecode version。常见于升级 RN 之后只更新了 node_modules，没有重新 pod install，旧的 hermes-engine 还留在 Pods 里。

升级后在 ios 目录重新 pod install，再做一次干净构建。

Metro 连不上或 JS bundle 缺失怎么办？

9. 真机连不上 Metro

Debug 包启动后要从电脑上的 Metro 开发服务器加载 JS，连不上就红屏，提示 Could not connect to development server。React Native 官方文档的要求是手机和电脑在同一个 Wi-Fi，并且能互相访问。按顺序检查：

1. Metro 还在运行，终端里没有报错。
2. 手机和电脑在同一个网络。访客网络、开了客户端隔离的网络连不通，可以改用手机热点。
3. 电脑防火墙放行 8081 端口的入站连接。
4. App 第一次启动时，iOS 询问是否允许查找本地网络上的设备，要点「允许」。点错了到「设置 → 隐私与安全性 → 本地网络」里打开。

10. Release 包打开白屏或闪退

Release 包不连 Metro，JS 必须提前打成 main.jsbundle 放进 App。这一步由工程里的 Bundle React Native code and images 构建阶段完成，它失败了 App 里就没有 JS。构建日志里会有这样一行：

1error: File .../main.jsbundle does not exist. Your environment is misconfigured as Metro was not able to produce the bundle so your release application won't work!

常见原因有三个。构建环境找不到 node，日志里是 Can't find the 'node' binary to build the React Native bundle，在 ios/.xcode.env.local 里写一行 export NODE_BINARY=node 的绝对路径 即可。环境里设了 SKIP_BUNDLING，删掉它。JS 代码本身有语法或导入错误，Metro 打包失败，往上翻日志找第一条 JS 报错。

想确认 ipa 里有没有 bundle，把 .ipa 复制一份改名为 .zip 解压，看 Payload/你的App.app/ 下有没有 main.jsbundle。

工程配置和升级后的报错怎么改？

11. use_frameworks 冲突

有些库（常见的是 Firebase 一类）要求 Pod 以 framework 形式集成。RN 模板的 Podfile 已经支持用环境变量 USE_FRAMEWORKS 打开，不用自己改 Podfile。

1USE_FRAMEWORKS=static pod install

优先用 static。用 dynamic 或者直接在 Podfile 里写不带参数的 use_frameworks!，更容易遇到 transitive dependencies that include statically linked binaries 和重复符号这类错误。切换之后先把 ios 目录的 Pods 删掉再 pod install，残留的旧产物会造成奇怪的链接错误。团队里所有人和 CI 要用同一个值。

12. 升级 RN 后编译报错

升级 RN 不只是改 package.json 的版本号，ios 目录里的 AppDelegate、Podfile、Info.plist 也要跟着模板改。用官方的 Upgrade Helper 选择当前版本和目标版本，逐个文件对比差异，照着改完再 pod install。

升到 0.88 时多留意一件事。0.88 的发布说明提到，用 iOS 27 SDK 构建的 UIKit App 必须使用 UIScene 生命周期，否则无法启动；0.88 为此加入了 SceneDelegate 支持，社区模板已经改成 SceneDelegate 写法，迁移时照模板把入口移到 SceneDelegate，并在 Info.plist 里加 UIApplicationSceneManifest。

在 Windows、Linux 上怎么排查这些报错？

在 Windows、Linux 上用 KXBuild 做 React Native 开发 iOS App 时，顺序是先带项目路径运行体检，再在 ios 目录 pod install，构建用 .xcworkspace。本文第 9 条的网络检查同样适用，Windows 防火墙放行 8081 的命令和完整流程见 React Native 在 Windows 上开发 iOS App。Run Script 阶段报错时，带项目路径重新体检，见排错与 FAQ；其余 React Native 新架构问题按上面的总表逐条对照即可。

常见问题

React Native 新架构还能关闭吗？

从 0.82 起不能。iOS 上用 RCT_NEW_ARCH_ENABLED=0 执行 pod install 会被忽略，App 仍运行在新架构上。还离不开旧架构的项目，官方建议先停在 0.81 或 Expo SDK 54 完成迁移。

怎么判断一个第三方库支持新架构？

在 reactnative.directory 搜这个库，看是否标注支持新架构；再看它的 package.json 有没有 codegenConfig。两者都没有时，查库的 Issues 里有没有适配计划，长期不维护的就换成替代库。

React Native 0.88 的 iOS 最低版本是多少？

0.88 的 CocoaPods 脚本里 min_ios_version_supported 是 15.1，模板 Podfile 直接引用它。用到的库要求更高时，以库的要求为准，Podfile 和 App target 的部署目标设成同一个值。

No such module ‘ReactAppDependencyProvider’ 怎么解决？

这个模块是 pod install 时由 Codegen 生成在 ios/build/generated/ios 下的。删过 ios/build 或换过分支后它会缺失，在 ios 目录重新运行 pod install 即可。

React Native Release 包打开白屏怎么办？

多数是 JS bundle 没打进 App。在构建日志里找 Bundle React Native code and images 阶段的报错，常见是找不到 node、设了 SKIP_BUNDLING 或 JS 本身打包失败；解压 ipa 确认 App 里有 main.jsbundle。

相关阅读

• React Native 技术栈
• React Native 在 Windows 上开发 iOS App
• Expo 在 Windows 本地构建 iOS 安装包
• CocoaPods 技术栈
• Flutter iOS 编译常见错误