React Native集成CodePush后首次启动不更新、需二次启动才生效的问题排查

云原生阿岚

2026-10-23

问题根因

结合你描述的「首次重启不生效、第二次启动才加载更新」的现象，高发的原因集中在3类：

触发时序与安装机制的认知误区
CodePush的InstallMode.IMMEDIATE并不支持在当前运行的应用进程内，热替换已经加载到内存的React Native JS Bundle——因为JS Bundle是在应用启动阶段就被加载到内存完成初始化的，运行时无法直接替换内存中的代码。你当前配置的CheckFrequency.ON_APP_START，实际触发检测的时机是在当前应用已经把旧版本Bundle加载到内存、完成启动流程之后才跑的：检测到更新、下载完成、写入“下次启动安装”的标记，整个过程都在旧Bundle已经运行的状态下完成，当前进程根本没法中途切换到新包，自然第一次重启看不到更新效果。
缺失notifyAppReady调用触发的自动回滚
CodePush内置了防崩溃回滚逻辑：当应用加载一个刚下载完成的新CodePush包时，必须在应用启动后的10秒窗口期内，主动调用codePush.notifyAppReady()上报“新包运行正常”，否则系统会判定这次更新存在问题，自动删除本地缓存的新包、回滚到上一个稳定旧包，让用户第一次启动时看不到新内容。等第二次启动时，系统重新检测、下载更新包，因为已经完成过旧版本的正常启动上报，回滚逻辑不会触发，用户就能正常加载新包，这个场景和描述的表现高度匹配。
版本校验的静默失败
如果在App Center发布更新时，绑定的目标原生应用版本（比如当前安装的原生包是3.2.0版本，发布的CodePush包却绑定到3.3.0版本）和本地应用不匹配，第一次启动检测时会因为版本校验不通过，跳过下载流程；等第二次启动时如果因为版本号的缓存校验逻辑异常，跳过校验完成下载，就会出现偶发的第二次启动才生效的问题。

定位排查步骤

开启CodePush调试日志，在配置项中加入debug: true，完整跟踪检测、下载、安装、回滚全流程的日志：
- 确认检测更新的触发时机，是在Bundle加载完成前还是完成后
- 确认检测到更新后是否完成了完整的下载流程，有没有触发回滚操作
- 确认新包的版本号和本地原生应用的版本匹配关系
手动验证时序问题：应用启动后不要立刻杀进程，等待10-15秒（等检测、下载流程完全跑完），再完全杀掉应用进程重新打开，如果这一次就能加载新版本，说明是时序问题导致的首次启动不生效。
检查项目代码中是否在应用正常渲染完成后，调用了codePush.notifyAppReady()，如果没有，大概率是回滚逻辑触发导致的问题。

解决方案

调整更新检测的触发时序：不要只依赖高阶组件的自动检测逻辑，在项目入口文件（比如index.js）的最顶部、注册根组件之前，手动调用codePush.sync接口，把检测流程提前到Bundle加载完成前执行，示例代码：

import {AppRegistry} from 'react-native';
import codePush from 'react-native-code-push';
import App from './App';

// 在注册App前就触发同步检测
codePush.sync({
  checkFrequency: codePush.CheckFrequency.ON_APP_START,
  installMode: codePush.InstallMode.IMMEDIATE,
  debug: __DEV__,
});

AppRegistry.registerComponent('YourAppName', () => App);

补充缺失的notifyAppReady调用：在根组件的useEffect（函数组件）或者componentDidMount（类组件）中，应用正常渲染完成后调用接口上报，避免触发回滚逻辑：

// 函数组件示例
useEffect(() => {
  codePush.notifyAppReady();
}, []);

核对App Center的发布配置：确认发布的CodePush包绑定的原生应用版本，和用户当前安装的原生版本完全一致，没有出现版本号偏移的问题。

内容的提问来源于stack exchange，提问作者Shariq