使用 eas.json 配置 EAS 构建

了解如何使用 eas.json 配置使用 EAS 服务的项目。

eas.json 是 EAS CLI 和服务的配置文件。它是在你的项目中第一次运行 eas build:configure 命令 时生成的，位于项目根目录的 package.json 旁边。EAS Build 的配置全部属于 build 密钥。

¥eas.json is the configuration file for EAS CLI and services. It is generated when the eas build:configure command runs for the first time in your project and is located next to package.json at the root of your project. Configuration for EAS Build all belongs under the build key.

新项目中生成的 eas.json 的默认配置如下所示：

¥The default configuration for eas.json generated in a new project is shown below:

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {}
  }
}

建立档案

¥Build profiles

构建配置文件是一组命名的配置，描述了执行某种类型的构建所需的参数。

¥A build profile is a named group of configurations that describes the necessary parameters to perform a certain type of build.

build 键下的 JSON 对象可以包含多个构建配置文件，并且你可以拥有自定义构建配置文件名称。在默认配置中，存在三个构建配置文件：development、preview 和 production。然而，这些可能被命名为 foo、bar 和 baz。

¥The JSON object under the build key can contain multiple build profiles, and you can have custom build profile names. In the default configuration, there are three build profiles: development, preview, and production. However, these could have been named foo, bar, and baz.

要使用特定配置文件运行构建，请使用如下所示的带有 <profile-name> 的命令：

¥To run a build with a specific profile, use the command as shown below with a <profile-name>:

如果省略 --profile 标志，EAS CLI 将默认使用名为 production 的配置文件（如果存在）。

¥If you omit the --profile flag, EAS CLI will default to using the profile with the name production (if it exists).

特定于平台的选项和通用选项

¥Platform-specific and common options

在每个构建配置文件中，你可以指定包含特定于平台的构建配置的 android 和 ios 字段。两个平台都可用的选项 可以在特定于平台的配置对象或配置文件的根上提供。

¥Inside each build profile, you can specify android and ios fields that contain platform-specific configuration for the build. Options that are available to both platforms can be provided on the platform-specific configuration object or the root of a profile.

在配置文件之间共享配置

¥Sharing configuration between profiles

可以使用 extends 选项将构建配置文件扩展到其他构建配置文件属性。

¥Build profiles can be extended to other build profile properties using the extends option.

例如，在 preview 配置文件中，你可能有 "extends": "production"。这将使 preview 配置文件继承 production 配置文件的配置。

¥For example, in the preview profile you might have "extends": "production". This will make the preview profile inherit the configuration of the production profile.

常见用例

¥Common use cases

使用 Expo 工具的开发者通常最终会得到三种不同类型的构建：开发、预览和生产。

¥Developers using Expo tools usually end up having three different types of builds: development, preview, and production.

开发构建

¥Development builds

默认情况下，eas build:configure 将使用 "developmentClient": true 创建 development 配置文件。这表明该构建依赖于 expo-dev-client。这些构建包括开发者工具，并且它们永远不会提交到应用商店。

¥By default, eas build:configure will create a development profile with "developmentClient": true. This indicates that this build depends on expo-dev-client. These builds include developer tools, and they are never submitted to an app store.

development 配置文件也默认为 "distribution": "internal"。这将使你可以轻松地将应用直接分发到物理 Android 和 iOS 设备。

¥The development profile also defaults to "distribution": "internal". This will make it easy to distribute your app directly to physical Android and iOS devices.

你还可以配置你的开发版本以在 iOS 模拟器 上运行。为此，请对 development 配置文件使用以下配置：

¥You can also configure your development builds to run on the iOS Simulator. To do this, use the following configuration for the development profile:

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": {
        "simulator": true
      }
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

注意：对于 iOS，要为内部分发创建一个构建，并为 iOS 模拟器创建另一个构建，你可以为该构建创建单独的开发配置文件。你可以为配置文件指定一个自定义名称。例如，development-simulator，并在该配置文件上使用 iOS 模拟器具体配置，而不是在 development 上。运行 设备和 Android 模拟器上的 Android .apk 不需要此类配置，因为相同的 .apk 将在两种环境中运行。

¥Note: For iOS, to create a build for internal distribution and another for the iOS Simulator, you can create a separate development profile for that build. You can give the profile a custom name. For example, development-simulator, and use the iOS Simulator specific configuration on that profile instead of on development. No such configuration is required to run an Android .apk on a device and an Android Emulator as the same .apk will run with both environments.

预览版本

¥Preview builds

这些版本不包括开发者工具。它们旨在由你的团队和其他利益相关者安装，以在类似生产的环境中测试应用。从这一点来说，它们和 生产构建 很相似。但是，它们与生产版本不同，因为它们要么没有在应用商店上进行分发（iOS 上的临时或企业配置），要么以不适合商店部署的方式打包（建议使用 Android .apk 进行预览） ，.aab 建议用于 Google Play 商店）。

¥These builds don't include developer tools. They are intended to be installed by your team and other stakeholders, to test out the app in production-like circumstances. In this way, they are similar to production builds. However, they are different from production builds because they are either not signed for distribution on app stores (ad hoc or enterprise provisioning on iOS), or are packaged in a way that is not optimal for store deployment (Android .apk is recommended for preview, .aab is recommended for Google Play Store).

最小 preview 配置文件示例：

¥A minimal preview profile example:

{
  "build": {
    "preview": {
      "distribution": "internal"
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

与 开发构建 类似，你可以配置预览版本以在 iOS 模拟器 上运行，或为此目的创建预览配置文件的变体。运行 设备和 Android 模拟器上的 Android .apk 不需要此类配置，因为相同的 .apk 将在两种环境中运行。

¥Similar to development builds, you can configure a preview build to run on the iOS Simulator or create a variant of your preview profile for that purpose. No such configuration is required to run an Android .apk on a device and an Android Emulator as the same .apk will run with both environments.

生产构建

¥Production builds

这些构建版本被提交到应用商店，以便向公众发布或作为商店促进的测试过程（例如 TestFlight）的一部分。

¥These builds are submitted to an app store, for release to the general public or as part of a store-facilitated testing process such as TestFlight.

生产版本必须通过各自的应用商店安装。它们无法直接安装在你的 Android 模拟器或设备、iOS 模拟器或设备上。唯一的例外是，如果你在构建配置文件中明确为 Android 设置了 "buildType": "apk"。但是，建议在提交到商店时使用 .aab，因为这是默认配置。

¥Production builds must be installed through their respective app stores. They cannot be installed directly on your Android Emulator or device, or iOS Simulator or device. The only exception to this is if you explicitly set "buildType": "apk" for Android on your build profile. However, it is recommended to use .aab when submitting to stores, as this is the default configuration.

最小 production 配置文件示例：

¥A minimal production profile example:

{
  "build": {
    "production": {}
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

在单个设备上安装同一应用的多个版本

¥Installing multiple builds of the same app on a single device

在同一设备上同时安装开发和生产版本是很常见的。参见 在同一设备上安装应用变体。

¥It's common to have development and production builds installed simultaneously on the same device. See Install app variants on the same device.

配置构建工具

¥Configuring build tools

每个构建都隐式或显式地依赖于执行构建过程所需的一组特定版本的相关工具。这些包括但不限于：Node.js、npm、Yarn、Ruby、Bundler、CocoaPods、Fastlane、Xcode 和 Android NDK。

¥Every build depends either implicitly or explicitly on a specific set of versions of related tools that are needed to carry out the build process. These include but are not limited to: Node.js, npm, Yarn, Ruby, Bundler, CocoaPods, Fastlane, Xcode, and Android NDK.

选择构建工具版本

¥Selecting build tool versions

可以在构建配置文件上设置最常见构建工具的版本，其中的字段与工具名称相对应。例如 node：

¥Versions for the most common build tools can be set on build profiles with fields corresponding to the names of the tools. For example node:

{
  "build": {
    "production": {
      "node": "18.18.0"
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

在配置文件之间共享构建工具配置是很常见的。使用 extends 来实现：

¥It's common to share build tool configurations between profiles. Use extends for that:

{
  "build": {
    "production": {
      "node": "18.18.0"
    },
    "preview": {
      "extends": "production",
      "distribution": "internal"
    },
    "development": {
      "extends": "production",
      "developmentClient": true,
      "distribution": "internal"
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

选择资源类别

¥Selecting resource class

资源类是 EAS Build 为你的作业提供的虚拟机资源配置（CPU 核心、RAM 大小）。默认情况下，资源类别设置为 medium，这通常足以满足小型和大型项目的需要。但是，如果你的项目需要更强大的 CPU 或更大的内存，或者你希望构建更快地完成，则可以切换到 large 工作线程。

¥A resource class is the virtual machine resources configuration (CPU cores, RAM size) EAS Build provides to your jobs. By default, the resource class is set to medium, which is usually sufficient for both small and bigger projects. However, if your project requires a more powerful CPU or bigger memory, or if you want your builds to finish faster, you can switch to large workers.

有关为每个类提供的资源的更多详细信息，请参阅 android.resourceClass 和 ios.resourceClass 属性。要在特定资源类的工作线程上运行构建，请在构建配置文件中配置此属性：

¥For more details on resources provided to each class, see android.resourceClass and ios.resourceClass properties. To run your build on a worker of a specific resource class, configure this property in your build profile:

{
  "build": {
    "production": {
      "android": {
        "resourceClass": "medium"
      },
      "ios": {
        "resourceClass": "large"
      },
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

注意：在 large 工作线程上运行作业需要 付费 EAS 计划。

¥Note: Running jobs on a large worker requires a paid EAS plan.

选择基础图片

¥Selecting a base image

构建作业的基础镜像控制各种依赖的默认版本，例如 Node.js、Yarn 和 CocoaPods。你可以使用特定的命名字段来覆盖它们，如上一节中所述，使用 resourceClass。但是，该映像包含无法以任何其他方式显式设置的特定工具版本，例如操作系统版本和 Xcode 版本。

¥The base image for the build job controls the default versions for a variety of dependencies, such as Node.js, Yarn, and CocoaPods. You can override them using the specific named fields as described in the previous section using resourceClass. However, the image includes specific versions of tools that can't be explicitly set any other way, such as the operating system version and Xcode version.

如果你正在使用 Expo 构建应用，EAS Build 将选择适当的图片，并使用一组合理的依赖来适应你正在构建的 SDK 版本。否则，建议查看 构建服务器基础设施 上的可用图片列表。

¥If you are building an app with Expo, EAS Build will pick the appropriate image to use with a reasonable set of dependencies for the SDK version that you are building for. Otherwise, it is recommended to see the list of available images on Build server infrastructure.

示例

¥Examples

模式

¥Schema

{
  "cli": {
    "version": "SEMVER_RANGE",
    "requireCommit": boolean,
    "appVersionSource": string,
    "promptToConfigurePushNotifications": boolean,
  },
  "build": {
    "BUILD_PROFILE_NAME_1": {
      ...COMMON_OPTIONS,
      "android": {
        ...COMMON_OPTIONS,
        ...ANDROID_OPTIONS
      },
      "ios": {
        ...COMMON_OPTIONS,
        ...IOS_OPTIONS
      }
    },
    "BUILD_PROFILE_NAME_2": {},
	%%placeholder-start%%... %%placeholder-end%%
  }
}

你可以在特定于平台的配置对象或配置文件的根中指定 共同属性。特定于平台的选项优先于全局定义的选项。

¥You can specify common properties both in the platform-specific configuration object or at the profile's root. The platform-specific options take precedence over globally-defined ones.

{
  "build": {
    "base": {
      "node": "12.13.0",
      "yarn": "1.22.5",
      "env": {
        "EXAMPLE_ENV": "example value"
      },
      "android": {
        "image": "default",
        "env": {
          "PLATFORM": "android"
        }
      },
      "ios": {
        "image": "latest",
        "env": {
          "PLATFORM": "ios"
        }
      }
    },
    "development": {
      "extends": "base",
      "developmentClient": true,
      "env": {
        "ENVIRONMENT": "development"
      },
      "android": {
        "distribution": "internal",
        "withoutCredentials": true
      },
      "ios": {
        "simulator": true
      }
    },
    "staging": {
      "extends": "base",
      "env": {
        "ENVIRONMENT": "staging"
      },
      "distribution": "internal",
      "android": {
        "buildType": "apk"
      }
    },
    "production": {
      "extends": "base",
      "env": {
        "ENVIRONMENT": "production"
      }
    }
  }
}

{
  "build": {
    "base": {
      "env": {
        "EXAMPLE_ENV": "example value"
      },
      "android": {
        "image": "ubuntu-18.04-android-30-ndk-r19c",
        "ndk": "21.4.7075529"
      },
      "ios": {
        "image": "latest",
        "node": "12.13.0",
        "yarn": "1.22.5"
      }
    },
    "development": {
      "extends": "base",
      "env": {
        "ENVIRONMENT": "staging"
      },
      "android": {
        "distribution": "internal",
        "withoutCredentials": true,
        "gradleCommand": ":app:assembleDebug"
      },
      "ios": {
        "simulator": true,
        "buildConfiguration": "Debug"
      }
    },
    "staging": {
      "extends": "base",
      "env": {
        "ENVIRONMENT": "staging"
      },
      "distribution": "internal",
      "android": {
        "gradleCommand": ":app:assembleRelease"
      }
    },
    "production": {
      "extends": "base",
      "env": {
        "ENVIRONMENT": "production"
      }
    }
  }
}

环境变量

¥Environment variables

你可以使用 "env" 字段在构建配置文件上配置环境变量。当你运行 eas build 时，这些环境变量将用于在本地评估 app.config.js，并且它们也将在 EAS Build 构建器上设置。

¥You can configure environment variables on your build profiles using the "env" field. These environment variables will be used to evaluate app.config.js locally when you run eas build, and they will also be set on the EAS Build builder.

{
  "build": {
    "production": {
      "node": "16.13.0",
      "env": {
        "API_URL": "https://company.com/api"
      }
    },
    "preview": {
      "extends": "production",
      "distribution": "internal",
      "env": {
        "API_URL": "https://staging.company.com/api"
      }
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

环境变量和秘密 参考更详细地解释了此主题，使用 EAS 更新 指南提供了与 expo-updates 一起使用此功能时的注意事项。

¥The Environment variables and secrets reference explains this topic in greater detail, and the Use EAS Update guide provides considerations when using this feature alongside expo-updates.

更多

¥More