Docs
博客更新日志GitHub简中文档
首页指南EAS参考学习
存档Expo SnackDiscord 和论坛新闻邮件

使用 eas.json 配置 EAS Build

编辑页面

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

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

eas.json 是 EAS CLI 和服务的配置文件。它会在你的项目中首次运行 eas build:configure 命令 时生成，并位于项目根目录下，紧挨着 package.json。EAS Build 的所有配置都归属于 build 键。

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

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

构建配置档案

构建配置档案是一个有名称的配置组，用于描述执行某种类型构建所需的参数。

build 键下的 JSON 对象可以包含多个构建配置档案，并且你可以使用自定义的构建配置档案名称。在默认配置中，有三个构建配置档案：development、preview 和 production。不过，它们也可以被命名为 foo、bar 和 baz。

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

Terminal
# 将 <profile-name> 替换为 eas.json 中的一个构建配置档案
- eas build --profile <profile-name>

如果你省略 --profile 标志，EAS CLI 默认会使用名为 production 的配置档案（如果它存在）。

平台特定与通用选项

在每个构建配置档案中，你可以指定包含该构建平台特定配置的 android 和 ios 字段。适用于两个平台的选项 可以提供在平台特定配置对象中，或者配置档案的根级别。

在配置档案之间共享配置

可以使用 extends 选项将构建配置档案扩展为其他构建配置档案属性。

例如，在 preview 配置档案中，你可能会设置 "extends": "production"。这会让 preview 配置档案继承 production 配置档案的配置。

只要避免循环依赖，你可以继续链式扩展配置档案，最多深度为 5。

常见用例

使用 Expo 工具的开发者通常最终会有三种不同类型的构建：development、preview 和 production。

开发构建

默认情况下，eas build:configure 会创建一个带有 "developmentClient": true 的 development 配置档案。这表示此构建依赖于 expo-dev-client。这些构建包含开发者工具，并且永远不会提交到应用商店。

development 配置档案还默认设置为 "distribution": "internal"。这会让你更容易直接将应用分发到物理 Android 和 iOS 设备。

你也可以将开发构建配置为在 iOS 模拟器 上运行。为此，请为 development 配置档案使用以下配置：

eas.json
{
  "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 可以在两种环境中运行。

预览构建

这些构建不包含开发者工具。它们 предназнач于由你的团队和其他相关人员安装，用于在接近生产环境的条件下测试应用。在这一点上，它们类似于 生产构建。不过，它们与生产构建不同，因为它们要么没有用于应用商店分发的签名（iOS 上的 ad hoc 或 enterprise provisioning），要么以不适合商店部署的方式打包（Android .apk 推荐用于预览，.aab 推荐用于 Google Play Store）。

一个最小的 preview 配置档案示例：

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

与 开发构建 类似，你可以将预览构建配置为在 iOS 模拟器 上运行，或者为此创建一个预览配置档案的变体。对于在设备和 Android 模拟器上运行 Android .apk，则不需要任何此类配置，因为同一个 .apk 可以在两种环境中运行。

生产构建

这些构建会提交到应用商店，用于向公众发布，或作为诸如 TestFlight 之类的商店辅助测试流程的一部分。

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

一个最小的 production 配置档案示例：

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

在单个设备上安装同一应用的多个构建

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

配置构建工具

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

选择构建工具版本

最常见的构建工具版本可以在构建配置档案中通过与工具名称对应的字段来设置。例如 node：

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

通常会在配置档案之间共享构建工具配置。可以使用 extends 来实现：

eas.json
{
  "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%%
}

选择资源类

资源类是 EAS Build 为你的任务提供的虚拟机资源配置（CPU 核数、RAM 大小）。默认情况下，资源类设置为 medium，这通常足以满足小型和大型项目的需求。不过，如果你的项目需要更强大的 CPU 或更大的内存，或者你希望构建更快完成，你可以切换到 large worker。

有关每个类提供的资源的更多细节，请参阅 android.resourceClass 和 ios.resourceClass 属性。要在特定资源类的 worker 上运行你的构建，请在构建配置档案中配置此属性：

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

注意：在 large worker 上运行作业需要 付费 EAS 套餐。

选择基础镜像

构建任务的基础镜像会控制多种依赖项的默认版本，例如 Node.js、Yarn 和 CocoaPods。你可以按照上一节所述，使用特定的命名字段并通过 resourceClass 来覆盖它们。然而，该镜像还包含一些无法通过其他方式显式设置的工具特定版本，例如操作系统版本和 Xcode 版本。

如果你正在使用 Expo 构建应用，EAS Build 会根据你要构建的 SDK 版本，自动选择一个合适的镜像及一组合理的依赖项。否则，建议查看 构建服务器基础设施 中可用镜像的列表。

示例

模式

eas.json
{
  "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%%
  }
}

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

具有多个配置文件的托管项目
eas.json
{
  "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"
      }
    }
  }
}
具有多个配置文件的裸项目
eas.json
{
  "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"
      }
    }
  }
}

环境变量

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

eas.json
{
  "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 一起使用时需要考虑的事项。

更多

EAS Build schema reference

查看 EAS Build 可用属性的完整参考。