应用版本管理

了解不同的版本类型以及如何远程或本地管理它们。

Android 和 iOS 各自提供两种值来识别应用版本：商店中显示的版本（面向用户的版本）和仅开发者可见的版本（面向开发者的构建版本）。本指南解释了如何远程或本地管理这些版本。

🌐 Android and iOS each expose two values to identify the version of an app: the version visible in stores (user-facing version) and the version visible only to developers (developer-facing build version). This guide explains how you can manage those versions remotely or locally.

自动应用版本管理

在本期 Expo 特色聚焦视频中，你将了解 Expo EAS Build 中的自动应用版本管理。

应用版本

🌐 App versions

在 Expo 项目中，可以使用以下属性在 app 配置 文件中定义应用版本。

🌐 In Expo projects, the following properties can be used to define app versions in the app config file.

在你的应用中使用应用版本

🌐 Using app versions in your app

要在应用中显示面向用户的版本，你可以使用 expo-application 库中的 Application.nativeApplicationVersion。

🌐 To show the user-facing version inside your app, you can use Application.nativeApplicationVersion from the expo-application library.

要在应用中显示面向开发者的构建版本，你可以使用 expo-application 库中的 Application.nativeBuildVersion。

🌐 To show the developer-facing build version inside your app, you can use Application.nativeBuildVersion from the expo-application library.

推荐的工作流程

🌐 Recommended workflow

面向用户的版本

🌐 User-facing version

当你进行生产版本发布时，面向用户的版本应由你明确设置并更新。当生产构建提交到应用商店时，你可以更新应用配置中的 version 属性。如果你的项目使用 expo-updates 并且采用自动运行时版本策略，这同样适用。这标志着你的应用新版本开发周期的开始。了解更多关于部署模式的信息。

🌐 When you are doing a production release, the user-facing version should be explicitly set and updated by you. You can update the version property in app config when production build is submitted to the app stores. This also applies if your project uses expo-updates with an automatic runtime version policy. This marks the beginning of a new development cycle for a new version of your app. Learn more about deployment patterns.

面向开发者的构建版本

🌐 Developer-facing build version

对于面向开发者的构建版本，你可以设置每次构建时自动递增。这将帮助你避免每次在 Play 商店测试渠道或 TestFlight 上传新归档时都手动修改项目。应用商店拒绝的一个常见原因是提交了版本号重复的构建。这通常发生在开发者在创建新构建之前忘记递增面向开发者的构建版本号时。

🌐 For developer-facing build version, you can set them to auto increment on every build. This will help you avoid making manual changes to the project every time you upload a new archive on Play Store testing channels or TestFlight. One common cause for app store rejections is submitting a build with a duplicate version number. It happens when a developer forgets to increment the developer-facing build version number before creating a new build.

EAS Build 可以通过自动为你递增版本号来帮助管理面向开发者的构建版本，如果你选择使用 remote 版本来源，这是推荐的做法。你也可以选择使用 local 应用版本来源，这意味着你需要在各自的配置文件中手动控制版本号。

🌐 EAS Build can help manage developer-facing build versions automatically by incrementing these versions for you if you opt into using the remote version source, which is the recommended behavior. Optionally, you can choose to use a local app version source, which means you control versions manually in their respective config files.

远程版本源码

🌐 Remote version source

信息 remote 版本的源代码是 EAS CLI 12.0.0 版本推荐的行为。

EAS 服务器可以远程存储和管理你应用面向开发者的构建版本（android.versionCode 和 ios.buildNumber）。要启用此功能，你需要在 eas.json 中将 cli.appVersionSource 设置为 remote。然后，在 production 构建配置下，你可以将 autoIncrement 属性设置为 true。

🌐 EAS servers can store and manage your app's developer-facing build version (android.versionCode and ios.buildNumber) remotely. To enable it, you need to set cli.appVersionSource to remote in eas.json. Then, under the production build profile, you can set the autoIncrement property to true.

{
  "cli": {
    "appVersionSource": "remote"
  },
  "build": {
    "development": {
      %%placeholder-start%%... %%placeholder-end%%
    },
    "preview": {
      %%placeholder-start%%... %%placeholder-end%%
    },
    "production": {
      "autoIncrement": true
    }
  }
  %%placeholder-start%%... %%placeholder-end%%
}

远程版本会使用本地项目的值进行初始化。例如，如果你在应用配置中将 android.versionCode 设置为 1，当你使用远程版本源创建新构建时，它会自动递增为 2。但是，如果你在应用配置中没有设置构建版本，当创建第一个构建时，远程版本将以 1 初始化。

🌐 The remote version is initialized with the value from the local project. For example, if you have android.versionCode set to 1 in app config, when you create a new build using the remote version source, it will auto increment to 2. However, if you do not have build versions set in your app config, the remote version will initialize with 1 when the first build is created.

当在 eas.json 中启用 remote 版本属性时，存储在应用配置中的构建版本值会被忽略，并且在远程递增版本时不会更新。远程版本源值会在运行构建时设置到本地项目上，这被视为这些值的真实来源。你可以安全地从应用配置中删除这些值。

🌐 When the remote version property is enabled inside eas.json, the build version values stored in app config are ignored and not updated when the version is incremented remotely. The remote version source values are set on the native project when running a build, which is considered the source of truth for these values. You can safely remove these values from your app config.

将已定义的版本同步到远程

🌐 Syncing already defined versions to remote

在某些情况下，你的项目已经设置了版本，并且希望在创建新的 EAS 构建时从这些版本递增。然而，这些现有的版本可能尚未与 EAS 远程同步。其中一些情况包括：

🌐 There are different scenarios where you already have versions set up for your project and want to increment from those versions when you create a new EAS Build. However, these existing versions might not be synced remotely with EAS. Some of these scenarios are:

• 你已经在应用商店中发布了你的应用，并希望继续使用相同的版本号。
• EAS CLI 无法检测应用的版本。
• 出于任何其他原因，你已明确设置版本，例如在你的应用配置中。

在这些情况下，你可以使用 EAS CLI 将当前版本同步到 EAS Build，步骤如下：

🌐 In these scenarios, you can sync the current version to EAS Build using the EAS CLI using the following steps:

• 在终端窗口中，运行以下命令：

  Terminal

  Copy

  - eas build:version:set

• 在提示时选择平台（Android 或 iOS）。

• 当出现提示 你现在想将应用版本来源设置为远程吗？ 时，选择 是。这将在 eas.json 中将 cli.appVersionSource 设置为 remote。

• 当提示 你想用哪个版本初始化它？ 时，输入你在应用商店中设置的最后一个版本号。

完成这些步骤后，应用版本将会远程同步到 EAS Build。你现在可以在 eas.json 中将 build.production.autoIncrement 设置为 true。当你创建新的生产构建时，versionCode 和 buildNumber 将会自动递增。

🌐 After these steps, the app versions will be synced to EAS Build remotely. You can now set build.production.autoIncrement to true in eas.json. When you create a new production build, the versionCode and buildNumber will be automatically incremented.

将版本从远程同步到本地

🌐 Syncing versions from remote to local

要使用远程存储在 EAS 上的相同版本在 Android Studio 或 Xcode 中本地构建你的项目，请使用以下命令使用远程版本更新你的本地项目：

🌐 To build your project locally in Android Studio or Xcode using the same version stored remotely on EAS, update your local project with the remote versions using the following command:

局限性

🌐 Limitations

• Android 上的 eas build:version:sync 命令不支持包含多个风味的裸项目。但是，其余的远程版本控制功能应该适用于所有项目。
• autoIncrement 不支持 version 选项。
• 如果你正在使用 EAS 更新并且运行时策略设置为 "runtimeVersion": { "policy": "nativeVersion" }，则不受支持。要获得类似行为，请改用 "appVersion" 策略。

本地版本源码

🌐 Local version source

你可以配置项目，使项目版本的真实性来源为本地项目源代码本身。为此，请在你的 eas.json 中将 cli.appVersionSource 设置为 local。

🌐 You can configure your project so that the source of truth for project versions is the local project source code itself. To do this, set cli.appVersionSource to local in your eas.json.

通过这种设置，EAS 会读取应用版本值并按原样构建项目。它不会写入项目。你也可以通过在构建配置文件上设置 autoIncrement 选项来本地启用版本自动递增。

🌐 With this setup, EAS reads app version values and builds projects as they are. It doesn't write to the project. You can also enable auto incrementing versions locally by setting the autoIncrement option on a build profile.

{
  "cli": {
    "appVersionSource": "local"
  },
  "build": {
    "development": {
      %%placeholder-start%%... %%placeholder-end%%
    },
    "preview": {
      %%placeholder-start%%... %%placeholder-end%%
    },
    "production": {
      "autoIncrement": true
    }
  }
  %%placeholder-start%%... %%placeholder-end%%
}

在已有的 React Native 项目 中，本地代码中的值优先。库 expo-constants 和 expo-updates 会从应用配置文件中读取值。如果你依赖清单中的版本值，应确保它们与本地代码保持同步。如果你使用 EAS Update 且运行时策略设置为 "runtimeVersion": { "policy": "nativeVersion" }，保持这些值同步尤其重要，因为版本不匹配可能导致更新被推送到错误的应用版本。我们建议使用 expo-application 来读取版本，而不是依赖应用配置中的值。

🌐 In the case of existing React Native projects, the values in native code take precedence. The libraries expo-constants and expo-updates read values from the app config file. If you rely on version values from a manifest, you should keep them in sync with native code. Keeping these values in sync is especially important if you are using EAS Update with the runtime policy set to "runtimeVersion": { "policy": "nativeVersion" }, because mismatched versions may result in the delivery of updates to the wrong version of an application. We recommend using expo-application to read the version instead of depending on values from app config.

局限性

🌐 Limitations

• 使用 autoIncrement 时，如果你希望版本更改能持久保存，每次构建都需要提交你的更改。在 CI 上构建时，这可能很难协调。
• 对于现有的具有多种版本风格支持的 Gradle 配置的 React Native 项目，EAS CLI 无法读取或修改版本，因此不支持 autoIncrement 选项，并且版本不会在 expo.dev 的构建详情页面中列出。