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

Expo 更新 iconExpo 更新

使你的应用能够管理应用代码远程更新的库。

Android
iOS
tvOS
Included in Expo Go
Recommended version:
~58.0.15

expo-updates 是一个库,允许你的应用管理对应用代码的远程更新。它与配置的远程更新服务进行通信,以获取可用更新的信息。

安装

🌐 Installation

expo-updates 库可以通过 EAS Update 自动配置,EAS Update 是一个托管服务,用于管理和提供应用的更新。要开始使用 EAS Update,请按照 入门 指南中的说明操作。

🌐 The expo-updates library can be automatically configured using EAS Update, which is a hosted service that manages and serves updates to your app. To get started with EAS Update, follow the instructions in the Get started guide.

另外,在需要使用不同远程更新服务或配置仅在本地文件中指定的情况下,也可以手动配置 expo-updates 库。

🌐 Alternatively, it is also possible to configure the expo-updates library manually in cases where a different remote update service is required or configuration is only specified in native files.

手动安装、配置和自定义远程更新服务
Terminal
- npx expo install expo-updates
- yarn expo install expo-updates
- pnpm expo install expo-updates
- bun expo install expo-updates

如果你在一个现有的 React Native 项目中或一个手动配置了原生代码的通用应用中安装这个库,请按照这些安装说明操作。

🌐 If you're installing this library in an existing React Native project or a generic app with manually configured native code, follow these installation instructions.

如果使用 应用配置 进行配置,可以通过设置至少以下应用配置属性来配置此库:

🌐 If using app config for configuration, this library can be configured by setting at least the following app config properties:

远程服务必须实现 Expo Updates 协议。EAS Update 就是其中之一,但也可以将此库与自定义服务器一起使用。

🌐 The remote service must implement the Expo Updates protocol. EAS Update is one such service, but it is also possible to use this library with a custom server.

定制 Expo 更新服务器

使用该服务器的自定义服务器和应用的示例实现。

配置

🌐 Configuration

有一些构建时配置选项可以控制库的行为。对于大多数应用,这些配置值在 应用配置 中的 updates 属性 下设置。

🌐 There are build-time configuration options that control the behavior of the library. For most apps, these configuration values are set in the app config under the updates property.

应用配置属性默认值必需?iOS plist/字典键Android 元数据名称Android Map 键
updates.enabledtrueEXUpdatesEnabledexpo.modules.updates.ENABLEDenabled
updates.url(无)EXUpdatesURLexpo.modules.updates.EXPO_UPDATE_URLupdateUrl
updates.requestHeaders(无)EXUpdatesRequestHeadersexpo.modules.updates.UPDATES_CONFIGURATION_REQUEST_HEADERS_KEYrequestHeaders
runtimeVersion(无)EXUpdatesRuntimeVersionexpo.modules.updates.EXPO_RUNTIME_VERSIONruntimeVersion
updates.checkAutomaticallyON_LOADEXUpdatesCheckOnLaunchexpo.modules.updates.EXPO_UPDATES_CHECK_ON_LAUNCHcheckOnLaunch
updates.fallbackToCacheTimeout0EXUpdatesLaunchWaitMsexpo.modules.updates.EXPO_UPDATES_LAUNCH_WAIT_MSlaunchWaitMs
updates.useEmbeddedUpdatetrueEXUpdatesHasEmbeddedUpdateexpo.modules.updates.HAS_EMBEDDED_UPDATEhasEmbeddedUpdate
updates.codeSigningCertificate(无)EXUpdatesCodeSigningCertificateexpo.modules.updates.CODE_SIGNING_CERTIFICATEcodeSigningCertificate
updates.codeSigningMetadata(无)EXUpdatesCodeSigningMetadataexpo.modules.updates.CODE_SIGNING_METADATAcodeSigningMetadata
updates.assetPatternsToBeBundled(无)不适用不适用不适用
updates.disableAntiBrickingMeasuresfalseEXUpdatesDisableAntiBrickingMeasuresexpo.modules.updates.DISABLE_ANTI_BRICKING_MEASURESdisableAntiBrickingMeasures
updates.enableBsdiffPatchSupporttrueEXUpdatesEnableBsdiffPatchSupportexpo.modules.updates.ENABLE_BSDIFF_PATCH_SUPPORTenableBsdiffPatchSupport
updates.maxUpdatesToKeep2EXUpdatesMaxUpdatesToKeepexpo.modules.updates.EXPO_UPDATES_MAX_UPDATES_TO_KEEPmaxUpdatesToKeep

updates.maxUpdatesToKeep 控制要保留多少个更新,包括当前正在运行的那个。例如,将它设置为 3 会保留正在运行的更新以及最多两个旧更新。符合清单过滤条件的更新优先保留,且会优先保留最新的更新。

这个值控制在运行更新的同时保留多少旧的更新。清理操作会保留其他范围的更新以及提交时间与运行更新相同或更晚的更新,所以缓存中可能包含比这个值更多的更新。

🌐 This value controls how many older updates to keep alongside the running update. Cleanup leaves updates from other scopes and updates with the same or a newer commit time than the running update untouched, so the cache can contain more updates than this value.

两个核心必需的配置选项是:

🌐 The two core required configuration options are:

在按照 EAS 更新 入门 指南操作时,这些会自动配置。

🌐 These are configured automatically when following the EAS Update Get started guide.

运行时版本

🌐 Runtime version

每次为应用构建二进制文件时,它都会包含构建时的本地代码和配置,以及本地配置,这种唯一组合由一个称为运行时版本的字符串表示。远程更新会针对一个运行时版本,这意味着只有具有匹配运行时版本的二进制文件才能加载远程更新。

🌐 Each time you build a binary for your app it includes the native code and configuration present at the time of the build as well as native configuration, and this unique combination is represented by a string called a runtime version. A remote update targets one runtime version, indicating that only binaries with a matching runtime version can load the remote update.

手动配置

运行时版本可以通过在配置字段中设置字符串值来手动管理。

🌐 The runtime version can be managed manually by setting the string value in the config field.

{ "expo": { "runtimeVersion": "<runtime_version_string>" } }
Automatic configuration using runtime version policies

运行时版本策略从项目中已存在的其他信息推导运行时版本。它们可以在 runtimeVersion 配置字段中设置,如下所示:

🌐 Runtime version policies derive the runtime version from another piece of information already present in your project. They can be set in the runtimeVersion config field as follows:

{ "expo": { "runtimeVersion": { "policy": "<policy_name>" } } }

可用的保单类型:

🌐 Available policy types:

appVersion

"appVersion" 策略适用于希望根据应用版本定义其运行时兼容性的项目。

🌐 The "appVersion" policy is provided for projects with that wish to define their runtime compatibility based on the app version.

例如,在一个项目的应用配置中包含以下内容时:

🌐 For example, in a project that has the following in its app config:

{ "expo": { "runtimeVersion": { "policy": "appVersion" }, "version": "1.0.0", "ios": { "buildNumber": "1" }, "android": { "versionCode": 1 } } }

"appVersion" 策略将把运行时版本设置为项目当前的 "version" 属性。在这种情况下,Android 和 iOS 构建以及任何更新的运行时版本都将是 "1.0.0"。

🌐 The "appVersion" policy will set the runtime version to the project's current "version" property. In this case, the runtime version for the Android and iOS builds and any updates would be "1.0.0".

此策略非常适用于包含自定义原生代码且在每次公开发布后都会更新 "version" 字段的项目。要提交应用,应用商店要求每次提交的构建都提供更新的原生版本号,因此如果你希望确保安装在用户设备上的每个版本都有不同的运行时版本,这一策略会非常方便。

🌐 This policy is great for projects that contain custom native code and that update the "version" field after every public release. To submit an app, the app stores require an updated native version number for each submitted build, which makes this policy convenient if you want to be sure that every version installed on user devices has a different runtime version.

使用此策略时,每次有公开版本发布时,你需要手动更新应用配置中的 "version" 字段,但对于 Play 商店的内部测试渠道和 App Store 的 TestFlight 上传,你可以依赖 eas.json 中的 "autoIncrement" 选项来为你管理版本。

🌐 When using this policy, you need to manually update "version" field in the app config every time there is a public release, but for Play Store's Internal Test Track and the App Store's TestFlight uploads, you can rely on "autoIncrement" option in eas.json to manage versions for you.

nativeVersion

"nativeVersion" 策略适用于希望根据项目当前的 "version" 和 "versionCode"(Android)或 "buildNumber"(iOS)属性来定义其运行时兼容性的项目。

🌐 The "nativeVersion" policy is provided for projects that wish to define their runtime compatibility based on the project's current "version" and "versionCode" (Android) or "buildNumber" (iOS) properties.

例如,在一个项目的应用配置中包含以下内容时:

🌐 For example, in a project that has the following in its app config:

{ "expo": { "runtimeVersion": { "policy": "nativeVersion" }, "version": "1.0.0", "ios": { "buildNumber": "1" }, "android": { "versionCode": 1 } } }

Android 和 iOS 构建的运行时版本以及任何更新将是 "[version]([buildNumber|versionCode])" 的组合,在本例中为 "1.0.0(1)"。

🌐 The runtime version for the Android and iOS builds and any updates would be the combination of "[version]([buildNumber|versionCode])", which in this case would be "1.0.0(1)".

该政策非常适用于包含自定义原生代码的项目,这些项目会在每次构建时更新原生版本号(iOS 为 "buildNumber",Android 为 "versionCode")。要提交应用,应用商店要求每次提交的构建都必须有更新的原生版本号,因此如果你希望确保上传到 Play 商店内部测试渠道和 App Store 的 TestFlight 分发工具的每个应用都有不同的 runtimeVersion,该政策就非常方便。

🌐 This policy is great for projects containing custom native code that update the native version numbers ("buildNumber" for iOS and "versionCode" for Android) for each build. To submit an app, the app stores require an updated native version number for each submitted build, which makes this policy convenient if you want to be sure that every app uploaded to the Play Store's Internal Test Track and the App Store's TestFlight distribution tools has a different runtimeVersion.

重要的是要知道,这项政策要求在每次构建之间手动管理原生版本号。

🌐 It's important to know that this policy requires management of the native version numbers manually between each build.

另外,如果你在 Android 和 iOS 之间选择了不同的原生版本,你最终将得到具有独立运行时版本的构建和更新。

🌐 Also, if you select a different native version between Android and iOS, you'll end up with builds and updates with separate runtime versions.

fingerprint

"fingerprint" 运行时版本策略会自动为你计算运行时版本,包括在 SDK 升级或添加自定义本地代码等更改时。

🌐 The "fingerprint" runtime version policy automatically calculates the runtime version for you, including through changes like SDK upgrades or adding custom native code.

{ "expo": { "runtimeVersion": { "policy": "fingerprint" } } }

此策略适用于有自定义原生代码和没有自定义原生代码的项目。它通过使用 @expo/fingerprint 包在构建和更新过程中计算项目的哈希值来确定构建更新的兼容性(也称为运行时)。

🌐 This policy works for both projects with and without custom native code. It works by using the @expo/fingerprint package to calculate the hash of your project during builds and updates to determine build-update compatibility (also known as the runtime).

本地配置与覆盖

🌐 Native configuration and overriding

如果你的项目不使用连续本地生成,这些配置值也可以在应用的本地配置文件中设置,或在本地代码初始化期间被覆盖。

🌐 If your project does not use Continuous Native Generation, these configuration values may also be set in your app's native configuration files or overridden during initialization in native code.

本地配置说明

在 Android 上,这些选项在 AndroidManifest.xml 文件中设置为 meta-data 标签(如果使用自动设置安装,则在安装时添加的标签旁边)。你也可以在运行时使用 UpdatesController.overrideConfiguration() 设置或覆盖它们。

🌐 On Android, these options are set as meta-data tags in the AndroidManifest.xml file (adjacent to the tags added during installation if auto-setup was used). You can also set or override them at runtime using UpdatesController.overrideConfiguration().

在 iOS 上,这些属性作为键设置在 Expo.plist 文件中。你也可以在运行时通过调用 AppController.overrideConfiguration 来设置或覆盖它们。

🌐 On iOS, these properties are set as keys in the Expo.plist file. You can also set or override them at runtime by calling AppController.overrideConfiguration.

导入 Swift 生成的头文件以在 Objective-C++ 中使用

如果你的 iOS 原生代码或 AppDelegate.mm 是用 Objective-C++ 编写的,你需要添加以下导入来引用 EXUpdatesAppController 上的方法。这仅在运行时覆盖配置时才有必要。

🌐 If your iOS native code or AppDelegate.mm is written in Objective-C++, you will need to add the following imports to reference methods on EXUpdatesAppController. This is only necessary for overriding configuration at runtime.

#import "ExpoModulesCore-Swift.h" #import "EXUpdatesInterface-Swift.h" #import "EXUpdates-Swift.h"

用法

🌐 Usage

默认情况下,expo-updates 会在应用启动时检查更新。如果有可用更新,它会下载更新并在下次重启应用时应用更新。你可以使用上面的 checkAutomatically 和 fallbackToCacheTimeout 配置选项来调整这种启动行为。

🌐 By default, expo-updates checks for updates when the app launches. If an update is available, it downloads the update and applies it the next time the app is restarted. You can tune this startup behavior using the checkAutomatically and fallbackToCacheTimeout configuration options above.

该库还提供了多种常量用于检查当前更新,以及用于从应用代码(启动后)自定义更新行为的函数。例如,一个常见的替代使用模式是,在应用启动后手动检查更新,而不是在启动时进行默认检查。

🌐 The library also provides a variety of constants to inspect the current update and functions to customize update behavior from your application code (after startup). For example, one common alternative usage pattern is to manually check for updates after the app has started instead of doing the default check on launch.

示例:手动检查更新

你可以通过以下步骤配置你的应用以手动检查更新:

🌐 You can configure your app to check for updates manually by doing the following steps:

  1. 将 checkAutomatically 配置值设置为 ON_ERROR_RECOVERY 或 NEVER 以禁用库的默认启动行为。

  2. 添加以下代码以检查可用更新、下载它们并重新加载:

    App.js
    import { View, Button } from 'react-native'; import * as Updates from 'expo-updates'; function App() { async function onFetchUpdateAsync() { try { const update = await Updates.checkForUpdateAsync(); if (update.isAvailable) { await Updates.fetchUpdateAsync(); await Updates.reloadAsync(); } } catch (error) { // You can also add an alert() to see the error message in case of an error when fetching updates. alert(`Error fetching latest Expo update: ${error}`); } } return ( <View> <Button title="获取更新" onPress={onFetchUpdateAsync} /> </View> ); }

测试

🌐 Testing

此库中的大多数方法和常量只能在发布版本中使用或测试。在调试版本中,默认行为是始终从开发服务器加载最新的 JavaScript。可以构建具有与发布版本相同更新行为的调试版本应用。这样的应用不会从开发服务器打开最新的 JavaScript——它将像发布版本一样加载已发布的更新。这对于调试应用在未连接到开发服务器时的行为可能很有用。

🌐 Most of the methods and constants in this library can be used or tested only in release builds. In debug builds, the default behavior is to always load the latest JavaScript from a development server. It is possible to build a debug version of your app with the same updates behavior as a release build. Such an app will not open the latest JavaScript from your development server — it will load published updates just as a release build does. This may be useful for debugging the behavior of your app when it is not connected to a development server.

要在开发版本中测试更新的内容,请运行 eas update,然后在开发版本中浏览该更新。请注意,这仅仅是模拟更新在应用中的样子,大部分 Updates API 在开发版本中不可用。

要在发布版本中测试更新,你可以创建一个 .apk 文件或一个 模拟器版本,或者在本地使用 npx expo run:android --variant release 和 npx expo run:ios --configuration Release 制作发布版本(测试时不需要将此版本提交到商店)。完整的 更新 API 在发布版本中可用。

在 Expo Go 中测试更新内容,运行 eas update,然后在 Expo Go 中浏览该更新。请注意,这仅模拟更新在应用中的显示效果,并且在 Expo Go 中运行时,大部分 Updates API 无法使用。另外请注意,仅支持使用 兼容 Expo Go 的库 的更新。

应用接口

🌐 API

import * as Updates from 'expo-updates';

No API data file found, sorry!

错误代码

🌐 Error codes

代码描述
ERR_UPDATES_DISABLED当 Updates 库被禁用或应用处于开发模式时,尝试调用方法
ERR_UPDATES_RELOAD在尝试重新加载应用时发生了错误,应用无法重新加载。对于现有的 React Native 项目,请仔细检查这个库的设置步骤,确保它已正确安装,并调用了正确的本地初始化方法。
ERR_UPDATES_CHECK尝试检查新更新时发生意外错误。请查看错误信息以获取更多信息。
ERR_UPDATES_FETCH尝试获取新更新时发生意外错误。请检查错误信息以获取更多信息。
ERR_UPDATES_READ_LOGS尝试读取日志条目时发生意外错误。请检查错误信息以获取更多信息。
ERR_NOT_AVAILABLE_IN_DEV_CLIENT在开发版本中运行时,该方法不可用。应使用发布版本来测试此方法。