移动工程 · 深度解析

React Native 热更新
架构设计全剖析

从 JSBundle 构建流水线到灰度发布策略，再到线上秒级热修复机制—— 一次完整的技术解构，带你掌握 RN 热更的每一个核心环节。

修复耗时

< 30s

覆盖用户

亿级

无需审核

秒级生效

回滚能力

即时回退

架构全景

热更新三阶段生命周期

Phase 1

JSBundle 构建

将 JS 源码编译、分包、压缩为可分发的 Bundle 包，是热更新的基石。

Metro 打包器

Code Splitting

Source Map 生成

Hermes 字节码编译

Phase 2

灰度发布策略

分批次、可控地将新 Bundle 推送给用户，降低全量发布的风险。

白名单 / 比例放量

AB Test 分组

异常监控熔断

版本回退机制

Phase 3

秒级热修复

在不发版的前提下，将修复后的 Bundle 极速下发到用户设备。

差异增量更新 (Diff)

双 Bundle 预加载

静默下载替换

崩溃自动回滚

流水线全景

热更新完整链路

源码变更

Git Push / MR Merge

CI 构建

Metro / Hermes 编译

Bundle 产物

JSBundle + Sourcemap

CDN 分发

全球节点同步

灰度推送

分批 / 分群下发

客户端拉取

Diff Patch 应用

更新完成

新 Bundle 生效

底层原理

热更新为什么能生效？

React Native 运行时架构 —— 一切的前提

理解热更新的第一步，是理解 RN 将代码分成了两个世界。正是这种分离，赋予了 JS 层「可独立替换」的能力。

JS 层 (可热更)

JavaScript Thread

React 组件树 & UI 逻辑

业务状态管理 (Redux / Zustand)

网络请求、数据处理

由 JS 引擎 (JSC/Hermes) 执行

Bridge / JSI (桥接层)

Communication Layer

JSON 序列化异步通信 (旧架构)

JSI 同步 C++ 绑定 (新架构)

JS ↔ Native 双向调用通道

Shadow Tree 同步 (Fabric)

Native 层 (不可热更)

Native Thread

原生 UI 渲染 (UIView / Android.View)

系统 API (相机 / GPS / 蓝牙)

编译为机器码，随 App 安装包分发

修改必须走应用商店发版流程

关键认知

RN 的 JS 代码并非编译进安装包的机器码，而是作为运行时被 JS 引擎解释执行的脚本。这意味着只要替换掉这份脚本文件（JSBundle），下次引擎加载时就会执行新逻辑—— 这就是热更新的本质。

App 启动时 Bundle 加载的完整生命周期

每次 App 冷启动，Native 端的加载器都会执行一套固定流程来决定加载哪个 Bundle。热更新的「替换」就发生在启动前的准备阶段。

① App 启动

Native 进程创建，执行 Application 初始化

iOS: AppDelegate → didFinishLaunchingWithOptions Android: Application.onCreate()

② 检查热更版本

加载器读取本地存储的热更 Manifest，比对当前 Bundle 版本

从 AsyncStorage / NSUserDefaults / 文件系统中读取热更记录，与 App 内置 Bundle 版本做比较。

③ 版本决策

选择最终要加载的 Bundle 路径

若存在已下载且校验通过的热更 Bundle → 加载热更版本；否则 → 降级到 App 内置 Bundle。

// 伪代码：Bundle 路径决策
const hotBundle = await getPendingBundle();
if (hotBundle && await verifyIntegrity(hotBundle)) {
  bundlePath = hotBundle.path;       // → 加载热更版本
} else {
  bundlePath = BUILTIN_BUNDLE_PATH;  // → 降级到内置版本
}

④ JS 引擎加载

Hermes / JSC 引擎加载并执行 Bundle 文件

引擎从文件系统读取 Bundle → 解析 → 编译（Hermes 为 AOT 字节码）→ 执行入口函数 index.js

// Hermes AOT: 已预编译为 .hbc 字节码
// 启动时直接加载字节码，省去 parse + compile 阶段
HermesRuntime::loadBytecode(bundlePath);

// JS 侧入口开始执行
AppRegistry.registerComponent('App', () => App);
AppRegistry.runApplication('App', { rootTag });

⑤ UI 渲染

JS 构建 Virtual DOM → 通过 Bridge/JSI → Native 渲染真实视图

React 组件 render → Shadow Tree 计算布局 → Native 端创建真实 View → 屏幕显示。

⑥ 后台检查更新

App 运行期间，静默拉取服务端最新版本信息

比较本地版本号与服务端版本号，若有新版本则后台下载 Patch，下次冷启动时自动替换。

热替换的「魔法」原理

为什么替换文件就等于更新了功能？

脚本语言的运行时特性

JS 是解释型语言，代码不编译进二进制。App 运行时，JS 引擎从磁盘读取 Bundle 文件并执行。只要在下次执行前替换文件，引擎就读到新代码。

Bundle = 一份自描述脚本

Metro 打包器将所有 JS 模块、依赖、资源引用打包成一个文件。这个文件包含了完整的 UI 描述和业务逻辑，是一个完整的「App 皮肤」。

Native 壳 + JS 核 = 分离架构

Native 层只提供渲染容器和系统能力桥接，不包含业务逻辑。所以只要 JS 层的 Bridge 接口不变，替换 Bundle 不影响 Native 层的稳定性。

冷启动 = 天然的切换时机

JS 引擎在 App 冷启动时初始化。此时是加载新 Bundle 的最佳时机——无状态残留、无内存碎片，确保新代码从零开始干净执行。

可以热更的部分

UI 布局与样式

业务逻辑 & 事件处理

页面路由跳转

API 调用与数据处理

文本内容 & 国际化

动画参数 (Animated)

React 组件树结构

状态管理逻辑

无法热更的部分 (需要发版)

新增 / 修改 Native Module (原生桥接模块) — 编译进二进制，需重新打包

变更第三方 Native SDK 版本 — CocoaPods / Gradle 依赖

修改 App 权限声明 (Info.plist / AndroidManifest) — 随安装包分发

更新 React Native 框架本身的大版本 — Bridge / JSI 协议可能不兼容

旧架构 (Bridge) vs 新架构 (JSI/Fabric) 对热更的影响

RN 新架构用 JSI (JavaScript Interface) 替代了异步 JSON Bridge，这对热更新机制产生了深远影响。

旧架构 (Bridge)

通信方式

JSON 序列化 → 异步消息队列

线程模型

JS Thread / Shadow Thread / UI Thread 三线程

热更影响

Bridge 协议稳定，热更兼容性好

性能瓶颈

序列化开销大，列表滚动易卡顿

新架构 (JSI / Fabric)

通信方式

JSI 直接调用 C++ Host Objects，同步无序列化

线程模型

Fabric 渲染器合并 Shadow / UI 线程

热更影响

TurboModule 懒加载，需关注接口兼容性

性能提升

启动速度 ↑，滚动帧率 ↑，内存 ↓

新架构下的热更注意事项：TurboModule 采用懒加载机制，Native Module 的初始化时机与旧架构不同。热更 Bundle 中如果调用了新的 TurboModule 接口，需要确保宿主 App 的 Native 层已支持该接口，否则会触发 TurboModuleRegistry.get() 返回 null 的兼容性问题。建议在热更 Manifest 中声明 TurboModule 兼容版本号。

热更新的本质 = 「解释型语言的运行时文件替换」
趁引擎还没读到新文件之前，把旧文件换掉 → 引擎读到新逻辑 → 新 UI 呈现

Phase 1

JSBundle 构建深度拆解

Metro Bundler 构建流程

核心打包引擎

入口解析 (Entry Resolution)

以 index.js 为入口，解析 import/require 依赖图，构建模块依赖树。

转换 (Transformation)

通过 Babel 转译 JSX/Flow/TS，支持自定义 Plugin 和 Preset。

序列化 (Serialization)

将模块图序列化为 JS Bundle 文本。支持分包 (Splitting) 按需加载。

Hermes 字节码编译

AOT 将 JS → Hermes Bytecode，启动速度提升 40-60%，内存占用降低。

Bundle 产物结构

main.jsbundle

主 Bundle 文件 · ~800KB

main.jsbundle.map

Source Map · ~2MB

assets/

图片/字体资源 · 可变

manifest.json

版本元信息 · ~1KB

metro.config.js

const { getDefaultConfig } = require('metro-config');

module.exports = (async () => {
  const config = await getDefaultConfig();
  return {
    ...config,
    transformer: {
      ...config.transformer,
      // 启用 Hermes 字节码输出
      hermesCommand: './node_modules/.bin/hermesc',
      enableHermes: true,
    },
    serializer: {
      ...config.serializer,
      // 自定义分包逻辑
      customSerializer: require('./scripts/bundleSplit'),
    },
  };
})();

全量更新 vs 增量 Diff 更新

全量更新

✗下载完整 JSBundle (~800KB+)

✗网络开销大，弱网下超时风险高

✗实现简单，兼容性好

✗适合首次安装或大版本升级

增量 Diff 更新 (推荐)

✓仅传输差异 Patch (~10-50KB)

✓基于 bsdiff/bspatch 或自研算法

✓端上合并 Patch → 新 Bundle

✓节省 90%+ 带宽，弱网友好

Phase 2

灰度发布策略设计

白名单发布

指定内部用户或设备 ID 先行更新，用于功能验证和内部测试。

设备 ID 白名单员工账号测试设备

比例放量

按百分比逐步放量（1% → 5% → 20% → 50% → 100%），结合监控指标决策。

随机哈希分流渐进放量自动扩量

多维度定向

按 App 版本、系统版本、地域、设备型号等维度精准定向发布。

版本条件地域定向AB 分组

灰度发布时间线 (典型流程)

T + 0h内部验证

白名单用户 (≤ 100 人)，核心功能冒烟测试

T + 2h1% 放量

监控崩溃率 (Crash Rate < 0.1%)、接口异常率

T + 6h10% → 30%

逐步扩量，关注用户反馈、性能指标 (FPS/TTI)

T + 24h50% → 100%

全量发布，持续监控 48 小时

异常时立即回滚

任一指标超阈值 → 自动/手动回滚至上一稳定版本

rollback-guard.js — 客户端自动回滚逻辑

class HotUpdateGuard {
  constructor(options) {
    this.maxCrashCount = options.maxCrashCount ?? 3;
    this.rollbackVersion = options.rollbackVersion;
    this.monitoringWindow = options.windowMs ?? 60_000; // 1 min
  }

  async onBundleLoaded(bundleVersion) {
    // 启动崩溃监控窗口
    const crashCount = await this.startMonitoring(this.monitoringWindow);
    
    if (crashCount >= this.maxCrashCount) {
      console.warn(`[HotUpdate] Crash threshold exceeded (${crashCount}), rolling back...`);
      await this.rollback(this.rollbackVersion);
      // 强制重新加载上一稳定版本
      NativeModules.DevSettings.reload();
    }
  }

  async rollback(targetVersion) {
    // 1. 标记当前版本为 broken
    await this.markBundleBroken(currentVersion);
    // 2. 激活上一版本 Bundle
    await this.activateBundle(targetVersion);
    // 3. 上报回滚事件
    this.reportRollback(currentVersion, targetVersion);
  }
}

Phase 3

线上秒级热修复机制

线上问题发现

Crash 监控 / 用户反馈 / 性能告警触发

修复提交构建

修复代码 → CI 自动构建新 Bundle

紧急灰度推送

跳过常规流程，快速灰度验证后推送

静默下载生效

客户端静默下载 Patch，下次启动生效

双 Bundle 预加载策略

当前 Bundle (Active)

正在运行的 JSBundle，标记为 Active 状态

待切换 Bundle (Standby)

预下载到本地，等待下次启动时热替换

回滚 Bundle (Rollback)

保留上一个稳定版本，异常时立即切换

bundle-loader.ts — 双 Bundle 切换核心

async function loadBundle(version: string) {
  const bundlePath = `${RNFS.DocumentDirectoryPath}/bundles/${version}`;
  
  // 1. 检查本地是否已有该版本
  const exists = await RNFS.exists(bundlePath);
  if (!exists) {
    // 从 CDN 下载 Diff Patch
    const patch = await downloadPatch(currentVersion, version);
    // 合并生成新 Bundle
    await bspatch(currentBundlePath, bundlePath, patch);
  }

  // 2. 校验 Bundle 完整性
  const hash = await computeSHA256(bundlePath);
  if (hash !== expectedHash) {
    throw new Error('Bundle integrity check failed');
  }

  // 3. 标记为 Standby，等待下次启动切换
  await AsyncStorage.setItem(
    'pending_bundle', 
    JSON.stringify({ version, path: bundlePath })
  );
}

热更新关键监控指标

≥ 99.5%

下载成功率

≥ 99.8%

Patch 应用成功率

< 0.1%

热更后崩溃率

< 3s

平均下载耗时

方案选型

主流 RN 热更新方案对比

方案	Diff 更新	增量大小	回滚机制	Hermes 支持	开源
CodePush (MS)	✓	~20KB	自动	✓	✓
AppCenter	✓	~30KB	自动	✓	✗
Pushy (国内)	✓	~15KB	自动	✓	✓
自研方案	可选	可控	自定义	✓	✗

经验沉淀

最佳实践 & 避坑指南

常见陷阱

热更修改了 Native 依赖却期望纯 JS Patch 生效

未做 Bundle 完整性校验，被中间人攻击篡改

全量更新未考虑弱网场景，导致用户长时间白屏

灰度阶段缺乏自动化监控，依赖人工巡查

忽略 Source Map 管理，线上崩溃无法定位

频繁热更导致版本碎片化严重

未在 Manifest 中声明 Bundle 与 Native 最低兼容版本

总结

热更新的核心是安全 × 速度 × 可观测

一套成熟的热更新方案，不仅需要高效的构建和分发能力，更需要完善的灰度策略和自动回滚机制来保障线上稳定性。把每一次热更都当作一次「可控的发版」来对待。

构建

灰度

修复

监控

回滚

React Native 热更新架构设计 全剖析