从旧版本到 Hermes 原生一场有惊无险的架构进化之旅引言“升级”这两个字在 React Native 的世界里总是带着一丝微妙的紧张感。如果你手里有一个“上了年纪”的 React Native 项目——比如它诞生于 Hermes 成为默认引擎之前——那么把它迁移到 Hermes可能正是你当前最想解决的问题。好消息是Hermes 的集成并不复杂坏消息是随着这些年 React Native 版本的高速迭代0.70、0.76、0.84……一个旧项目可能同时面临“升级 RN 版本”“启用 Hermes”“迁移新架构”三重挑战这三件事交织在一起常常让开发者陷入“报错—搜索—尝试—再报错”的循环。Hermes 本身已经从hermes-engine独立依赖演进为与 React Native 绑定的“捆绑 Hermes”到 React Native 0.84Hermes V1 已成为双平台的默认引擎。但这对新项目来说是“零迁移成本”对旧项目而言却意味着必须一次性跨越由“JSC 旧架构”到“Hermes 新架构”的架构鸿沟。本文将系统梳理从各旧版本升级到 Hermes 的完整路径涵盖升级策略规划、分平台配置修改、依赖兼容性检查、常见构建错误排查以及 Expo 等特殊场景的处理方案帮你把这次“架构跨越”变成一场有惊无险的平稳过渡。一、升级前的准备工作1.1 评估当前项目状态在开始任何操作之前先回答以下几个关键问题你的 React Native 版本是多少bashnpx react-native --version # 或查看 package.json 中的 react-native 字段 cat package.json | grep react-native你的 Hermes 当前是开启还是关闭javascriptconst isHermes !!global.HermesInternal; console.log(当前引擎: ${isHermes ? Hermes : JSC});你的新架构New Architecture是开启还是关闭Android检查android/gradle.properties中的newArchEnablediOS检查ios/Podfile中的RCT_NEW_ARCH_ENABLED根据以上信息对照下表判断你的项目当前所处的“升级起点”当前 RN 版本Hermes 状态新架构状态升级到 Hermes 的路径≤ 0.60不支持不支持先升级 RN 到 0.60 → 启用 Hermes0.60 - 0.63Android 可选iOS 不支持不支持升级 RN 到 ≥ 0.64 → 启用 Hermes0.64 - 0.69双平台均可选可选直接启用 Hermes需兼容性检查0.70 - 0.75默认启用AndroidiOS 可选可选验证配置无需额外改动0.76 - 0.83默认启用新架构默认验证 Hermes 配置迁移依赖0.84Hermes V1 默认启用新架构唯一选项零迁移成本如果已用 Hermes1.2 创建备份与分支升级前务必执行以下操作bash# 创建升级分支 git checkout -b upgrade/hermes-migration # 确保所有更改已提交 git status同时备份以下关键文件package.json和yarn.lock/package-lock.jsonandroid/和ios/目录下的所有配置文件任何自定义的原生模块代码1.3 使用 Upgrade Helper 规划升级路径React Native 社区提供的Upgrade Helper是规划升级路线的最佳工具。使用步骤如下打开 Upgrade Helper 网站选择当前版本和目标版本如从0.66升级到0.84页面会逐文件对比两个版本之间的差异重点关注android/gradle.properties、ios/Podfile、package.json等文件的变更建议不要一步跨越太多版本而是在关键版本节点0.64、0.70、0.76、0.84分阶段升级每完成一个节点就进行一次完整的构建测试。二、Bundled Hermes理解 Hermes 与 RN 的版本绑定关系在动手修改配置之前有必要先理解一个核心概念Bundled Hermes捆绑 Hermes指每个 React Native 版本都自带一个经过兼容性测试的 Hermes 引擎版本。在 React Native 0.69 之前Hermes 和 React Native 采用两条独立的发布流程版本号互不匹配。开发者经常陷入“Hermes x.x.x 是否兼容 RN y.y.y”的困惑中。更严重的问题是两者共享 JSI 代码库如果两份 JSI 副本不同步Hermes 的构建版本可能与 React Native 构建版本存在 ABI应用程序二进制接口控制库与可执行文件之间的交互方式不兼容。从 React Native 0.69.0 开始每个 React Native 版本都会“捆绑”一个与之兼容的 Hermes 版本。这意味着不再需要单独维护 hermes-engine 版本Hermes 引擎会随 React Native 版本一起发布版本兼容性得到保证捆绑的 Hermes 与 React Native 经过了官方测试未来的版本中将完全移除 hermes-engine 依赖对于升级项目的开发者来说这意味着升级 React Native 版本就是升级 Hermes 版本。不要尝试单独安装或降级hermes-engine来“解决”构建错误这样做往往会让问题变得更复杂。三、升级到 Hermes 的完整步骤3.1 升级 React Native 版本由于 Hermes 与 RN 版本深度耦合启用 Hermes 的前提是将 RN 升级到支持 Hermes 的版本。使用 Upgrade Helper 逐版本升级bash# 示例从 0.66.0 升级到 0.70.0 npx react-native upgrade 0.70.0Upgrade Helper 会提示你手动合并以下关键文件的差异android/gradle.propertiesandroid/app/build.gradleios/Podfilepackage.json单版本升级后的验证每完成一个版本升级建议执行一次构建测试bash# 清理缓存 npx react-native start --reset-cache # Android npx react-native run-android # iOS cd ios pod install cd .. npx react-native run-ios如果构建失败先解决版本升级本身的 breaking changes再继续下一步。关键版本节点的变更要点≤ 0.60 → 0.60.x需升级 Android 构建工具minSdkVersion 提升到 210.60.x → 0.63.x相对平稳主要是 API 调整0.63.x → 0.64.xiOS 首次支持 Hermes0.64.x → 0.70.xHermes 成为 Android 默认引擎iOS 仍为可选0.70.x → 0.73.xHermes iOS 默认开启Flipper 调试被 Chrome DevTools 取代0.73.x → 0.76.x新架构成为默认Hermes 与 JSC 混用模式结束0.76.x → 0.84.xHermes V1 成为双平台默认引擎旧架构代码被移除3.2 Android 平台配置在 React Native 版本已升级的前提下确认或修改以下配置。步骤一启用 Hermes编辑android/gradle.propertiesproperties# 启用 Hermes JS 引擎 hermesEnabledtrue # 如果使用 React Native 0.84 且需要显式指定 V1 版本推荐 hermesV1Enabledtrue在 React Native 0.84 中Hermes V1 已经是双平台的默认 JS 引擎。hermesV1Enabled参数主要在 monorepo 等需要精确控制依赖解析的场景中用于确保更灵活动态的hermes-engine依赖解析。步骤二配置新架构可选如果计划同时迁移到新架构在同一个文件中添加properties# 启用新架构要求 Hermes 必须开启 newArchEnabledtrue⚠️ 注意从 React Native 0.76 开始新架构已成为默认选项。如果开启了newArchEnabledtrueHermes 必须同时启用因为新架构运行在 JSI 之上不支持 JavaScriptCore。步骤三确认 NDK 和 JDK 版本升级到 React Native 0.84 后构建时可能出现Could not find a package configuration file provided by hermes-engine错误。这通常不是 Hermes 本身的问题而是构建环境不满足新版本的要求。在android/app/build.gradle中指定 NDK 版本gradleandroid { ndkVersion 27.0.12077973 }确认 JDK 版本为 17bashjava -version # 输出应包含 openjdk version 17...同时建议删除构建缓存bashcd android rm -rf .cxx .gradle app/.cxx app/build cd ..步骤四构建与验证bashnpx react-native run-android --moderelease3.3 iOS 平台配置步骤一修改 Podfile编辑ios/Podfile添加或确认以下配置ruby# 启用新架构可选 ENV[RCT_NEW_ARCH_ENABLED] 1 use_react_native!( :path config[:reactNativePath], :hermes_enabled true # 启用 Hermes )在 React Native 0.84 中Hermes V1 是默认引擎:hermes_enabled true可以省略但建议保留以明确配置。此外预编译的.xcframework二进制文件会默认下载使用大幅减少构建时间。步骤二安装 Podsbashcd ios # 清理旧的 Pods 缓存 rm -rf Pods Podfile.lock pod install --repo-update cd ..步骤三构建与验证bash# Debug 模式 npx react-native run-ios # Release 模式验证字节码性能 npx react-native run-ios --modeRelease3.4 验证 Hermes 是否成功启用在所有配置完成后在应用代码中添加检测逻辑javascriptimport { Platform, Text, View } from react-native; const App () { const isHermes !!global.HermesInternal; const statusText 当前引擎: ${isHermes ? ✅ Hermes : ❌ 其他}; const hermiesText isHermes Hermes 版本: ${global.HermesInternal?.getRuntimeProperties?.()?.OSSReleaseVersion ?? 未知}; return ( View Text{statusText}/Text {hermiesText Text{hermiesText}/Text} Text平台: {Platform.OS}/Text /View ); }; export default App;然后在 Release 模式运行确认控制台输出或界面显示 Hermes 已启用。四、第三方依赖兼容性检查升级到 Hermes 和 React Native 新版本后许多第三方依赖需要更新版本或代码。4.1 使用 react-native-compatibility 工具社区提供了多个工具来帮助评估依赖兼容性reactnative.directory搜索第三方库查看是否标明 New Architecture 兼容性React Native Upgrade Helper除了帮助升级 RN 版本也会提示哪些常用库需要更新4.2 常见不兼容场景场景表现解决方案使用了Proxy、WeakRef等高级特性Hermes 下报语法错误或不支持检查 Hermes V1 是否支持如需在较旧 Hermes 版本上运行重构代码使用替代方案依赖 JSC 特有的行为或不规范的 API行为不一致或崩溃寻找该库的兼容版本或在升级前 fork 修改尚未适配 New Architecture 的原生模块TurboModuleRegistry.get() 返回 null检查库是否发布了 New Architecture 版本或等待更新旧版 Reanimated 与 Hermes V1 不兼容Reanimated 报错更新到 Reanimated 4.2.2 或更高版本4.3 依赖更新策略建议按以下顺序更新依赖React Native 核心相关react-native、react、react-test-renderer导航类react-navigation/*状态管理redux、mobx等通常无需改动原生模块react-native-firebase、react-native-camera等需逐个验证 New Architecture 兼容性UI 库react-native-elements、native-base等在升级过程中建议将package.json中的依赖版本先提升到最新稳定版但需确认与新 RN 版本的兼容性。如果某个库长期未更新且不兼容考虑寻找替代方案。五、常见构建错误的排查与修复5.1 Android 平台错误 1Could not find a package configuration file provided by hermes-engine错误信息textCould not find a package configuration file provided by hermes-engine with any of the following names...发生场景升级到 React Native 0.84 后首次构建 Android 时原因该版本中 Hermes V1 改变了 CMake 构建设置旧版构建缓存残留或 NDK/JDK 版本不满足条件解决方案按顺序尝试删除构建缓存bashcd android rm -rf .cxx .gradle app/.cxx app/build在android/app/build.gradle中指定 NDK 版本gradleandroid { ndkVersion 27.0.12077973 }确认 JDK 版本为 17bashjava -version export JAVA_HOME/path/to/jdk-17重新构建bash./gradlew clean ./gradlew assembleDebug作为临时方案可以在android/gradle.properties中添加hermesV1Enabledfalse禁用 Hermes V1但这会失去性能提升不推荐用于生产环境。错误 2java.lang.UnsatisfiedLinkError: couldnt find DSO to load: libhermes.so错误信息textjava.lang.UnsatisfiedLinkError: couldnt find DSO to load: libhermes.so发生场景Hermes 配置不完整或构建系统未正确打包 Hermes 动态库原因build.gradle中 Hermes 的 AAR 依赖配置有误或 Hermes Maven 仓库未正确添加解决方案检查android/app/build.gradle中 Hermes 依赖配置。如果使用的是较旧的模板可能需要手动添加gradledef enableHermes project.ext.react.get(enableHermes, true) dependencies { if (enableHermes) { implementation(com.facebook.react:hermes-android) } else { implementation jscFlavor } }错误 3Hermes 已启用但 Source Map 未生成错误信息无显式报错但上传到 Sentry 等服务的错误堆栈无法符号化原因Release 构建未正确生成组合 Source Map解决方案检查android/app/build.gradle中 Hermes 相关配置是否包含-output-source-map参数。如果是通过 React Native CLI 构建无需手动配置但如果使用了自定义构建脚本需确保hermesc调用时包含了该参数。5.2 iOS 平台错误 1Library not found for -lReact-hermes错误信息textld: library not found for -lReact-hermes发生场景升级后 iOS 构建失败Xcode 链接器找不到 Hermes 静态库原因Podfile 中的:hermes_enabled true缺失或未生效执行pod install后未重新构建Xcode 中的 Library Search Paths 设置不正确解决方案确认 Podfile 配置正确后重新安装 Podsbashcd ios rm -rf Pods Podfile.lock pod install在 Xcode 中执行 Product → Clean Build Folder快捷键 ShiftCmdK重新构建bashcd .. npx react-native run-ios错误 2Hermes 相关构建失败但 pod install 挂在下载阶段错误信息pod install卡住不动或提示无法下载 Hermes 预编译二进制原因网络问题或 CocoaPods CDN 不稳定解决方案bash# 使用代理如果可用 export https_proxyhttp://your-proxy:port # 或者改用 CDN URL cd ios pod install --repo-update --verbose5.3 通用问题Hermes 字节码版本不匹配导致启动崩溃错误信息JS bundle crash on startup应用启动后立即闪退原因更新 React Native 版本后使用了旧版本生成的字节码文件而新版本 Hermes 引擎无法加载旧格式字节码解决方案删除构建产物中的旧字节码文件执行完整的 clean buildEAS Update 或 CodePush 热更新务必同步更新runtimeVersion配置Metro 在 Debug 模式下报 Hermes 相关错误原因Hermes 在 Debug 模式下也是可用的但某些第三方调试工具可能不兼容如旧版 React Native Debugger解决方案从 React Native 0.73 开始推荐使用 Chrome DevTools 或 React Native DevTools 调试在开发者菜单中选择Open Debugger而非 Open React DevTools六、特殊场景Expo 项目升级如果你的项目使用的是 Expo Managed Workflow升级路径有所不同。6.1 查看当前 SDK 版本bashnpm list expo # 或 cat package.json | grep expo6.2 按 SDK 版本分步升级SDK 版本Hermes 状态升级操作SDK 46-47可选在app.json中添加jsEngine: hermesSDK 48-51默认启用无需额外配置移除可能冲突的显式配置SDK 52Expo Go 仅支持 Hermes确保不使用 JSC 依赖的特性SDK 55新架构唯一需 Build From Source配置expo-build-properties插件中的buildReactNativeFromSource: true和useHermesV1: true6.3 从 SDK 52 开始Expo Go 中只支持 Hermes 引擎这意味着如果某个依赖只兼容 JSC在 Expo Go 中调试时会遇到问题。解决方案是使用 Development Buildexpo run:ios/expo run:android或升级依赖到兼容版本。七、升级后的验证清单升级完成后建议逐一确认以下事项验证项验证方法预期结果Hermes 已启用!!global.HermesInternal返回trueAndroid 构建成功npx react-native run-android --moderelease无错误应用正常运行iOS 构建成功npx react-native run-ios --modeRelease无错误应用正常运行Source Map 组合成功检查构建产物中是否存在组合后的.map文件存在且可读生产环境错误可符号化上传到 Sentry 后触发测试错误堆栈指向原始源代码行号第三方依赖功能正常执行应用的核心功能流程无崩溃行为与升级前一致性能有明显提升对比升级前后的冷启动时间建议用 Release 模式Android 提升 20-40%iOS 约 30%内存占用无明显增加通过 Android Studio Profiler / Xcode Instruments 对比降低 30-50%建议在升级完成后将应用提交到内部测试渠道在多种设备和系统版本上进行充分测试。八、总结升级现有 RN 项目到 Hermes本质上是将其底层 JavaScript 引擎从 JSC 替换为 Hermes 的过程。随着 React Native 版本从 0.64 演进到 0.84这个过程已经变得非常平滑——在最新版本中Hermes 甚至已经是默认引擎。当前 RN 版本推荐操作预估工作量≤ 0.60优先考虑将整个项目基础架构重构升级追赶多个大版本差异若资源允许可逐步升级至 0.64 后再启用 Hermes2-4 周0.64 - 0.69确认依赖兼容性修改配置启用 Hermes1-3 天0.70 - 0.75验证 Hermes 配置通常已默认启用清理构建缓存半天0.76 - 0.83同时处理新架构迁移 Hermes 验证按库逐一适配2-4 周0.84零迁移成本如已用 Hermes仅需解决构建环境问题NDK/JDK 版本半天回顾这篇文章的起点——那个可能还跑在 JSC 上的旧项目通过一系列有规划的升级最终不仅能获得 Hermes 带来的启动加速和内存优化还为新架构的更多可能性铺平了道路。记住核心原则升级 React Native 版本就是升级 Hermes 版本不要试图单独维护 Hermes。遇到构建错误时优先检查构建环境NDK、JDK、CocoaPods 版本而非 Hermes 本身。完成升级后通过性能对比数据来验证收益——看到启动时间减少 30-50% 的那一刻你会觉得所有的 troubleshooting 都是值得的。下一讲预告Hermes 调试工具概览——Chrome DevTools React DevTools 联动 本专栏说明本专栏基于 Hermes 最新版本撰写截至 2026 年 4 月。不同 React Native 版本对 Hermes 的支持可能存在差异建议在升级前参考 React Native Upgrade Helper 和对应版本的官方更新日志。React Native, Hermes, 项目升级, 版本迁移, 依赖冲突, 新架构, 捆绑Hermes, 构建错误