使用 eas.json 配置 EAS 构建

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

eas.json 是 EAS CLI 和服务的配置文件。当你的项目第一次运行 eas build:configure 命令 时，它会被生成，并位于项目根目录下与 package.json 相邻的位置。所有 EAS Build 的配置都应放在 build 键下。

在新项目中生成的 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.

只要避免产生循环依赖，你就可以将配置文件扩展链接至 5 个深度。

🌐 You can keep chaining profile extensions up to the depth of 5 as long as you avoid making circular dependencies.

常见用例

🌐 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 .apk 在设备和 Android 模拟器上 则不需要这样的配置，因为同一个 .apk 可以在两种环境下运行。

预览版本

🌐 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 .apk 和 Android 模拟器 时则无需这样的配置，因为相同的 .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 核心数、内存大小）。默认情况下，资源类设置为 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 计划。

选择基础图片

🌐 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%%
  }
}

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

{
  "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 Update 指南则提供了在将此功能与 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