Expo Updates 热更新实战指南：正确处理开发模式限制与生产构建陷阱

Expo Updates 热更新实战指南：正确处理开发模式限制与生产构建陷阱

升级到 Expo SDK 49 或更高版本后，很多开发者都会遇到一个棘手的警告：“Cannot use Updates module in development mode in a production app”。这背后，其实是 Expo 团队在安全策略上的一次重要收紧。简单来说，expo-updates 现在对运行环境的校验变得极其严格：它明确禁止在 Expo Go 这个通用调试客户端里，调用任何可能触发 OTA 更新的逻辑，比如 `Updates.reloadAsync()`。原因很简单，Expo Go 本身并不具备生产环境所需的更新签名和验证能力。所以，你看到的那个警告：

WARN [Error: You cannot use the Updates module in development mode in a production app. ...]

这并非系统出了 Bug，而是一道强制性的安全防线，目的就是防止开发阶段的逻辑被不小心打包进生产环境，引发不可预知的问题。

✅ 正确做法：环境感知 + 条件执行

关键在于，绝不能在任何环境下都无差别地调用更新方法。正确的姿势是严格区分开发和生产环境，进行条件判断。来看一个典型的场景，比如在初始化多语言后需要根据 RTL 布局重载应用：

import * as Updates from 'expo-updates';
import { Platform } from 'react-native';

const loadI18n = async () => {
  // ... 语言初始化逻辑（保持不变）
  i18n.init().then(async () => {
    const isLocaleRTL = selectedLanguage.layout === 'RTL';
    const shouldForceRTL = (i18n.dir !== selectedLanguage.layout) ||
                            (!I18nManager.isRTL && isLocaleRTL);

    if (shouldForceRTL) {
      I18nManager.forceRTL(isLocaleRTL);
      I18nManager.allowRTL(isLocaleRTL);

      // ✅ 核心修复点：只在真正的生产环境执行重载
      if (!__DEV__ && Updates.isA vailable) {
        try {
          console.log('✅ Triggering OTA reload for RTL switch...');
          await Updates.reloadAsync();
        } catch (error) {
          console.warn('⚠️ Reload failed (expected in dev):', error);
        }
      } else if (__DEV__) {
        console.log('? Skipping Updates.reloadAsync in development (Expo Go)');
      }
    }
    setIsI18nInitialized(true);
  });
};

这里有个重要提示：`Updates.isA vailable` 是 Expo 提供的、用于判断更新是否可用的可靠 API（从 SDK 47 开始稳定支持）。它在 Expo Go 中会返回 `false`，而在 EAS 构建的生产包中则返回 `true`。切记不要单独依赖 `__DEV__` 这个变量来做判断，因为在某些 EAS 的预发布构建配置下，它可能仍然为 `true`。最稳妥的方式就是结合 `Updates.isA vailable` 一起使用。

⚠️ EAS 构建闪退/白屏的深层原因与修复

解决了开发环境的警告，下一个拦路虎往往是：用 `eas build` 打出来的包，一启动就卡在白屏甚至直接崩溃。这通常不是单一问题，而是由下面三个环节连锁反应导致的。

1. 缺失 runtimeVersion 配置（最高发！）

从 Expo SDK 49 开始，强制要求在 `app.json` 或 `app.config.js` 中明确配置 `runtimeVersion`。如果这个字段缺失，`expo-updates` 在初始化阶段就会失败，反映到用户侧就是 App 启动即崩溃（Android 可能没有直接日志，iOS 则会抛出 EXUpdates 初始化错误）。

✅ 正确的配置姿势（以 `app.json` 为例）：

{
  "expo": {
    "name": "MyApp",
    "runtimeVersion": "1.0.0",  // ← 这个必须要有！格式可以是 x.y.z 或任意自定义字符串
    "updates": {
      "enabled": true,
      "checkAutomatically": "ON_LOAD",
      "fallbackToCacheTimeout": 0
    }
  }
}

需要特别澄清一下：`runtimeVersion` 不是指我们常说的应用版本号（那是 `version` 字段），它本质上是一个原生兼容性标识符。但凡你修改了原生代码（比如 AndroidManifest）、升级了 SDK 或者添加了新的原生模块，都需要更新这个 `runtimeVersion`。

2. releaseChannel 与 EAS Profile 不匹配

这个问题也很常见：你的 `eas.json` 里为某个 profile 指定了 `"releaseChannel": "qa"`，但在 `app.json` 的更新配置里，却没有正确指向这个通道（如果使用自建更新服务器），或者压根没在 EAS 服务端创建名为 “qa” 的更新通道。

✅ 最省心的解决方案（使用 Expo 官方的 EAS Update 服务）：

• 直接移除 `app.json` 中自定义的 `updates.url`，让 Expo 自动托管。
• 确保 `eas.json` 里各个 profile 配置的 `releaseChannel`，与通过 `eas update:configure` 创建的通道名称一致。
• 发布更新前，执行命令明确指定通道：`eas update --channel qa --message "RTL fix"`。

3. AndroidManifest.xml 缺少必要权限与元数据（Bare 项目特有）

如果你的项目是通过 `expo prebuild` 生成的 Bare（裸）项目，而不是纯 Managed 项目，那就需要手动检查一下 `android/app/src/main/AndroidManifest.xml` 文件，确保以下关键配置存在：

注意：上面的 `YOUR_PROJECT_ID` 需要替换成你项目的真实 ID。获取路径是：Expo Dashboard → 项目设置（Project Settings）→ Updates 选项卡。

? 补充：构建前必做清理步骤（防缓存污染）

EAS 构建会利用本地缓存来加速，但旧版的 `expo-updates` 缓存有时会引发冲突。在每次重要的构建之前，建议执行以下清理命令：

# 清理 Metro 打包器和原生构建缓存（关键！）
npx expo start --clear
cd android && ./gradlew clean && cd ..

# 清理 EAS 构建缓存
eas build:clean

# 重新预构建（Bare 项目必需）
npx expo prebuild --clean

✅ 总结：三步落地 checklist

只要按照以上方案逐一排查和落实，你不仅能彻底告别那个烦人的开发模式警告，更能确保通过 EAS 构建的生产包能够稳定启动，热更新逻辑在正确的时机精准触发。这，才是真正实现 Expo 热更新“一次配置，多端无忧”的最佳实践路径。