This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

学习如何在运行时切换 EAS 更新通道。

通道切换 允许已安装的发布版本在运行时从不同的 EAS 更新通道请求更新。

在默认的 EAS 更新流程中，更新的 URL 和更新通道在构建时是固定的。在 EAS 上构建时，这个通道是在你的 eas.json 构建配置文件中设置的。它作为 expo-channel-name 请求头发送到更新 URL，并决定你的应用从哪个通道接收更新。通道切换允许你在 JavaScript 代码中覆盖该请求头，从而让你的应用可以从不同的通道请求更新。

🌐 In the default EAS Update flow, the updates URL and updates channel are fixed at build time. When building on EAS, this channel is set in your eas.json build profile. It is sent as the expo-channel-name request header to the updates URL and determines which channel your app receives updates from. Channel surfing allows you to override that request header in your JavaScript code so that your app can request updates from a different channel.

切换通道不会更改原生代码或绕过更新兼容性规则。所选通道的更新仍必须与已安装应用的平台和运行时版本匹配。

🌐 Channel surfing does not change native code or bypass update compatibility rules. The update on the selected channel must still match the installed app's platform and runtime version.

警告 使用 Updates.setUpdateRequestHeadersOverride() 进行通道切换在 Expo SDK 54 中可用，需 expo-updates 版本 0.29.0 及更高版本。

何时使用通道切换

🌐 When to use channel surfing

你可以使用通道切换来：

🌐 You can use channel surfing to:

• 允许单个已安装的应用按需在不同通道之间移动。应用可以在运行时切换通道，而不是保持绑定到构建时定义的通道。
• 启用在真实版本上的预览和测试。开发者、质量保证人员及其他相关人员可以使用与用户安装的相同的生产版本来尝试进行中的更新。
• 通过将应用重定向到另一个渠道来加快迭代和验证，无需等待新版本构建。

针对开发者测试和预览兼容更新，建议使用安装了带有“expo-dev-client”（/eas-update/expo-dev-client/）库的[开发构建版本]。这不使用 'Updates.setUpdateRequestHeadersOverride()'，开发版本不支持该功能。

🌐 For developer-focused testing and to preview compatible updates, use a development build with expo-dev-client library installed. This does not use Updates.setUpdateRequestHeadersOverride(), which is not supported in development builds.

切换通道

🌐 Switch channels

为更改通道提供一个应用级触发器，例如为受信任用户设置的隐藏菜单或适合你工作流程的其他机制。当选择通道时，使用 Updates.setUpdateRequestHeadersOverride() 来覆盖 expo-channel-name 请求头。设置覆盖后，检查更新，如果有更新则获取，并重新加载应用：

🌐 Provide an app-level trigger for changing channels, such as a hidden menu for trusted users or another mechanism that fits your workflow. When a channel is selected, use Updates.setUpdateRequestHeadersOverride() to override the expo-channel-name request header. After setting the override, check for an update, fetch it if available, and reload the app:

import * as Updates from 'expo-updates';

export async function switchUpdateChannelAsync(channel: string) {
  Updates.setUpdateRequestHeadersOverride({
    'expo-channel-name': channel,
  });

  const update = await Updates.checkForUpdateAsync();

  if (update.isAvailable) {
    await Updates.fetchUpdateAsync();
  }

  await Updates.reloadAsync();
}

该覆盖设置会保留在设备上。设置后，以后的更新检查将使用所选通道，直到应用清除或替换该覆盖，或直到应用被卸载。

🌐 The override persists on the device. After it is set, future update checks use the selected channel until the app clears or replaces the override, or until the app is uninstalled.

切换回开发通道

🌐 Switch back to the build channel

将 null 传递给 Updates.setUpdateRequestHeadersOverride() 以清除请求头覆盖并返回到构建中配置的通道：

🌐 Pass null to Updates.setUpdateRequestHeadersOverride() to clear the request header override and return to the channel configured in the build:

import * as Updates from 'expo-updates';

export async function clearUpdateChannelOverrideAsync() {
  Updates.setUpdateRequestHeadersOverride(null);

  const update = await Updates.checkForUpdateAsync();

  if (update.isAvailable) {
    await Updates.fetchUpdateAsync();
  }

  await Updates.reloadAsync();
}

Updates.channel 反映了应用启动时活跃的渠道。它在调用 Updates.setUpdateRequestHeadersOverride() 后不会立即更新，但在应用重新加载后会反映新的渠道。

测试通道切换

🌐 Test channel surfing

切换渠道时的风险和注意事项

🌐 Risks and considerations when switching channels

切换通道会改变应用运行的 JavaScript 包。如果你的应用依赖于在各通道间不兼容的迁移或数据结构，来回切换可能会造成问题。

🌐 Switching channels changes the JavaScript bundle the app runs. If your app depends on migrations or data shapes that are not compatible across channels, switching back and forth may cause issues.

例如，如果测试版更新进行了数据库迁移，生产版本可能无法理解新的架构。确保你的更新在切换时保持安全，或者在必要时限制只能单向切换。

🌐 For example, if a beta update applies a database migration, the production version might not understand the new schema. Ensure your updates remain safe to switch between, or restrict switching to one direction when needed.

其他资源

🌐 Additional resources