首页指南EAS参考教程

EAS 中的环境变量

了解在 EAS 中使用环境变量的基本概念以及如何管理它们。

Expo 中的环境变量 描述如何使用环境变量与 Expo 框架和 .env 文件来设置可以在 JavaScript 代码中内联的环境变量。Expo CLI 将使用开发机器上 .env 文件中的相应环境变量值替换代码中的前缀变量（例如 process.env.EXPO_PUBLIC_VARNAME）。

¥Environment variables in Expo describe how to use environment variables with the Expo framework and .env files to set environment variables that can be inlined in your JavaScript code. Expo CLI will substitute prefixed variables in your code (for example, process.env.EXPO_PUBLIC_VARNAME) with the corresponding environment variable values in .env files on your development machine.

由于 EAS Build 和 Workflows 作业在远程服务器上运行，因此 .env 文件可能不可用。例如，如果 .env 文件由于在 .gitignore 中列出或未提交到你的本地版本控制系统而被排除在你的项目之外。

¥Since EAS Build and Workflows jobs run on a remote server, .env files may not be available. For instance, if .env files are excluded from your project because they are listed in .gitignore or not committed to your local version control system.

此外，你可能希望在构建时使用项目代码之外的环境变量来自定义应用二进制文件，例如为错误报告服务设置包标识符或私钥。为了满足这些需求，我们有一个单独的（但兼容的）机制来管理 EAS 中的环境变量，该机制专注于在 EAS 服务器上存储和管理环境变量并同步它们以进行本地开发。

¥Additionally, you may want to use environment variables outside of your project code to customize your app binary at build time, like setting a bundle identifier or a private key for an error reporting service. To accommodate for those needs we have a separate (but compatible) mechanism for managing environment variables in EAS, which is focused on storing and managing environment variables on EAS servers and synchronizing them for local development.

项目范围的环境变量

¥Project-wide environment variables

项目范围的环境变量特定于单个 EAS 项目。你可以通过导航到项目上的 环境变量 页面来查看和管理它们。

¥Project-wide environment variables are specific to a single EAS project. You can view and manage them by navigating to the Environment Variables page on your project.

这些环境变量可用于在 EAS 服务器上运行的任何作业以及此项目的更新。如果它们的可见性设置允许，它们也可以在本地拉取以进行开发。

¥These environment variables are available in any jobs that run on EAS servers and updates for this project. They can also be pulled locally for development if their visibility setting allows it.

账户范围的环境变量

¥Account-wide environment variables

账户范围的环境变量可用于你 EAS 账户中的所有项目。你可以通过导航到你账户上的 环境变量 页面来查看和管理它们。

¥Account-wide environment variables are available across all of your projects in your EAS account. You can view and manage them by navigating to Environment Variables page on your account.

它们可用于在 EAS 服务器和更新上运行的作业，以及项目的项目范围变量。如果 EAS 服务器的可见性设置允许，你可以在本地拉取它们，也可以在 EAS 服务器之外读取它们。

¥They are available in jobs that run on EAS servers and updates, together with project-wide variables for a project. You can pull them locally or read outside of EAS servers if their visibility setting allows it.

环境

¥Environments

目前，EAS 支持三种环境变量环境：development、preview 和 production。环境是独立的环境变量集，可用于在不同上下文中自定义你的应用。例如，你可能希望对开发和生产使用不同的 API 密钥，或对不同的 App Store 版本使用不同的包标识符。环境允许你这样做。每个 EAS Build 和 Workflows 作业都使用来自其中一个可用环境的环境变量运行。你还可以使用环境进行更新，从而允许你对构建作业使用同一组环境变量。你可以在发布更新时通过提供 --environment 标志来执行此操作。

¥Currently EAS supports three environments for environment variables: development, preview and production. Environments are independent sets of environment variables that can be used to customize your app in different contexts. For example, you might want to use different API keys for development and production, or different bundle identifiers for different App Store releases. Environments allows you to do so. Every EAS Build and Workflows job runs using environment variables from one of the available environments. You can also use environments for updates, allowing you to use the same set of environment variables for your build jobs. You can do this when publishing an update by providing the --environment flag.

环境变量可以分配给多个环境，并在所有环境中具有相同的值，也可以为单个环境创建环境变量，以便你可以为单个环境设置特定值。

¥Environment variables can be assigned to multiple environments and have the same value across all of them, or be created for a single environment, so that you can set a specific value for a single environment.

可见性

¥Visibility

有三种不同的可见性设置：

¥There are three different visibility settings:

可见性描述
纯文本在网站、EAS CLI 和日志中可见。
敏感信息在构建和工作流作业日志中被混淆。你可以使用切换按钮使它们在网站上可见。它们在 EAS CLI 中也是可读的。
密钥在 EAS 服务器之外不可读，包括在网站和 EAS CLI 中。它们在构建和工作流作业日志中被混淆。
始终记住，客户端代码中包含的任何内容都应被视为公共，并且对于任何可以运行该应用的个人来说都是可读的。秘密类型环境变量旨在用于为 EAS 构建或工作流作业提供值，以便它们可用于改变作业的运行方式。例如，一个很好的用例是设置 NPM_TOKEN 以从 npm 安装私有包，或者设置 Sentry API 密钥以创建发布并上传源映射。秘密不会为你最终嵌入应用本身的值提供任何额外的安全性。

文件环境变量

¥File environment variables

除了将字符串设置为值之外，你还可以将文件上传为环境变量的值。

¥In addition to setting strings as values, you can also upload files as the value of an environment variable.

使用文件环境变量的一个常见用例是将 git 忽略的 google-services.json 配置文件传递给构建作业。在作业运行期间，将在项目目录之外的位置创建文件，并将文件路径分配给环境变量 (GOOGLE_SERVICES_JSON=/path/to/google-services.json)。例如，你可以将应用配置中的 android.googleServicesFile 设置为 GOOGLE_SERVICES_JSON 环境变量的值，以便在执行构建或工作流作业时使用此文件。

¥One common use case of using file environment variable is passing a git ignored google-services.json configuration file to a build job. During the job run, the file will be created in a location outside of the project directory and the path to the file will be assigned to the environment variable (GOOGLE_SERVICES_JSON=/path/to/google-services.json). For example, you can then set android.googleServicesFile in your app config to the value of the GOOGLE_SERVICES_JSON environment variable to use this file when executing the build or workflow job.

app.config.js
export default {
  %%placeholder-start%%...%%placeholder-end%%
  android: {
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json',
    %%placeholder-start%%...%%placeholder-end%%
  },
};

推荐的工作流程

¥Recommended workflow

在 EAS 项目中有效使用环境变量的一种可能方法是：

¥One possible way to efficiently work with environment variables in your EAS projects is to:

使用正确的可见性设置

¥Use correct visibility settings

确保将环境变量的可见性设置为适当的级别。避免为应用的 JavaScript 代码中使用的或用于解析应用配置的 EXPO_PUBLIC_ 变量设置过多的密钥可见性。请注意，具有密钥可见性的环境变量在 EAS 服务器之外不可读，并且无法在本地提取以进行开发或打包应用的 JavaScript 代码以进行更新。

¥Make sure to set the visibility of your environment variables to the appropriate level. Avoid setting excessive secret visibility to EXPO_PUBLIC_ variables that are used in your app's JavaScript code or are used to resolve your app's configuration. Be aware that environment variables with secret visibility are not readable outside of EAS servers, and can't be pulled locally for development or to bundle your app's JavaScript code for updates.

将 .env 文件添加到 .gitignore

¥Add .env files to .gitignore

为了避免在云作业期间混淆覆盖并泄露敏感信息，请将 .env 文件添加到你的 .gitignore 文件中。

¥To avoid confusing overrides during cloud jobs and leaking sensitive information, add .env files to your .gitignore file.

将 --environment 标志与 eas update 一起使用

¥Use the --environment flag with eas update

发布更新时，将 --environment 标志与 eas update 命令一起使用，以确保更新和构建作业使用相同的环境变量。

¥When publishing updates, use the --environment flag with the eas update command to ensure that the same environment variables are used for your updates as your build jobs.

当提供 --environment 标志时，eas update 将使用 EAS 服务器上的环境变量进行更新作业，而不会使用项目中经常用于本地开发的 .env 文件。

¥When the --environment flag is provided, eas update will use the environment variables on EAS servers for the update job and won't use the .env files present in your project often used for local development.

使用 eas env:pull 同步本地开发的环境变量

¥Sync the environment variables for local development using eas env:pull

你可以使用 eas env:pull 命令将环境变量从 EAS 服务器拉到你的本地 .env 文件以进行开发。可用于此目的的理想环境是 development 环境，因为它是用于开发构建的默认环境。

¥You can use the eas env:pull command to pull environment variables from EAS servers to your local .env file for development. The ideal environment that can be used for this purpose is the development environment, as it's the default environment used for development builds.

明确指定构建的环境

¥Explicitly specify the environment for your builds

在 eas.json 中为你的构建配置文件明确设置 environment 值，以确保始终为你的构建作业使用正确的环境变量，并且你可以完全控制此过程。

¥Explicitly set the environment value in eas.json for your build profiles to ensure that the correct environment variables are always used for your build jobs and you have full control over this process.

教程

¥Tutorial

请参阅 使用 EAS 环境变量 以获取有关如何在实际场景中使用 EAS 环境变量的分步指南。

¥See the Using EAS environment variables for a step-by-step guide on how to use EAS environment variables in a real world scenario.

在 EAS CLI 和 Expo CLI 中处理环境变量之间的差异

¥Differences between handling environment variables in EAS CLI and Expo CLI

Expo 框架和 EAS 的环境变量使用区别之一是 EAS CLI 本身不支持在解析 expo 配置时加载 .env 文件来设置环境变量。相反，建议使用带有 EAS CLI 命令的 EAS 环境变量管理系统为你的构建作业和更新设置环境变量，以避免混淆，并确保完全相同的环境变量用于：

¥One of the differences between using environment variables with the Expo framework and EAS is that EAS CLI itself does not support loading .env files to set environment variables when resolving the expo config. Instead, it's recommended to use the EAS environment variables management system with EAS CLI commands to set environment variables for your build jobs and updates to avoid confusion, and ensure that exactly the same environment variables are used both for:

  • 本地应用配置解析，由 EAS CLI 在准备 expo 配置时完成

    ¥Local app config resolution, done by EAS CLI when preparing the expo config

  • EAS 服务器上发生的远程作业通常无法访问被 git 忽略的本地 .env 文件

    ¥Remote jobs happening on EAS servers, which often don't have access to your local .env files that are git ignored

使用 eas update 是此规则的一个例外。默认情况下，出于向后兼容的原因，它使用项目目录中的 .env 文件为更新作业设置环境变量，就像 Expo CLI 一样（它在后台执行 npx expo export 命令）。

¥Using eas update is the one exception to this rule. By default, for backward compatibility reasons, it uses .env files present in your project directory to set environment variables for the update job, the same way Expo CLI does (it executes the npx expo export command under the hood).

要确保你可以在更新中使用与构建作业相同的环境变量，你可以将 --environment 标志与 eas update 命令一起使用，以强制它仅使用 EAS 服务器上设置的环境变量，而不是项目目录中存在的 .env 文件。它将忽略来自 .env 的环境变量。

¥To ensure that you can use the same environment variables in your updates as your build jobs, you can use the --environment flag with the eas update command to force it to use only the environment variables set on the EAS servers instead of the .env files present in your project directory. It will ignore environment variables from .env.

EAS Build 和 Workflows 作业运行

¥EAS Build and Workflows job runs

为构建设置环境

¥Setting the environment for your builds

要为 EAS Build 作业设置环境，你可以使用 eas.json 中的 environment 选项并将其设置为可用环境之一：development、preview 或 production。

¥To set the environment for your EAS Build jobs, you can use the environment option in eas.json and set it to one of the available environments: development, preview or production.

eas.json
{
  "build": {
    "development": {
      "environment": "development"
    },
    "preview": {
      "environment": "preview"
    },
    "production": {
      "environment": "production"
    },
    "my-profile": {
      "environment": "production"
  }
}

如果你未设置 environment 选项，我们将根据你的构建配置自动设置环境：

¥If you don't set the environment option, we will set the environment automatically based on your build's configuration:

  • development：用于开发客户端构建

    ¥development: for development client build

  • preview：用于其他配置

    ¥preview: for other configurations

  • production：用于应用商店构建

    ¥production: for app store build

此解析逻辑仅适用于 EAS CLI 版本 13.3.0 及更高版本。对于较旧的 CLI 版本，我们始终假设所有构建都使用 production 环境。

内置环境变量

¥Built-in environment variables

以下环境变量是向每个作业公开的附加系统环境变量，可以在任何构建步骤中使用。它们不是任何项目环境的一部分，在本地评估 app.config.js 时不可用：

¥The following environment variables are additional system environment variables exposed to each job and can be used within any build step. They are not a part of any project environment and are not available when evaluating app.config.js locally:

  • CI=1：表明这是一个 CI 环境

    ¥CI=1: indicates this is a CI environment

  • EAS_BUILD=true：表示这是 EAS 构建环境

    ¥EAS_BUILD=true: indicates this is an EAS Build environment

  • EAS_BUILD_PLATFORM：android 或 ios

    ¥EAS_BUILD_PLATFORM: either android or ios

  • EAS_BUILD_RUNNER：eas-build（用于 EAS Build 云构建）或 local-build-plugin（用于 本地构建）

    ¥EAS_BUILD_RUNNER: either eas-build for EAS Build cloud builds or local-build-plugin for local builds

  • EAS_BUILD_ID：构建 ID，例如 f51831f0-ea30-406a-8c5f-f8e1cc57d39c

    ¥EAS_BUILD_ID: the build ID, for example, f51831f0-ea30-406a-8c5f-f8e1cc57d39c

  • EAS_BUILD_PROFILE：eas.json 中的构建配置文件的名称，例如 production

    ¥EAS_BUILD_PROFILE: the name of the build profile from eas.json, for example, production

  • EAS_BUILD_GIT_COMMIT_HASH：Git 提交的哈希值，例如 88f28ab5ea39108ade978de2d0d1adeedf0ece76

    ¥EAS_BUILD_GIT_COMMIT_HASH: the hash of the Git commit, for example, 88f28ab5ea39108ade978de2d0d1adeedf0ece76

  • EAS_BUILD_NPM_CACHE_URL：npm 缓存的 URL (了解更多)

    ¥EAS_BUILD_NPM_CACHE_URL: the URL of npm cache (learn more)

  • EAS_BUILD_MAVEN_CACHE_URL：Maven 缓存的 URL (了解更多)

    ¥EAS_BUILD_MAVEN_CACHE_URL: the URL of Maven cache (learn more)

  • EAS_BUILD_COCOAPODS_CACHE_URL：CocoaPods 缓存的 URL (了解更多)

    ¥EAS_BUILD_COCOAPODS_CACHE_URL: the URL of CocoaPods cache (learn more)

  • EAS_BUILD_USERNAME：启动构建的用户的用户名（对于机器人用户来说未定义）

    ¥EAS_BUILD_USERNAME: the username of the user initiating the build (it's undefined for bot users)

  • EAS_BUILD_WORKINGDIR：你的项目的远程目录路径

    ¥EAS_BUILD_WORKINGDIR: the remote directory path with your project

在作业执行期间动态设置环境变量

¥Dynamically setting environment variables during the job execution

你还可以使用 set-env 命令在作业执行期间动态设置环境变量。set-env 可执行文件在 EAS Build Worker 上的 PATH 中可用，可用于设置在下一个构建阶段可见的环境变量。

¥You can also set environment variables dynamically during the job execution using the set-env command. The set-env executable is available in the PATH on EAS Build workers, and can be used to set environment variables that will be visible in the next build phases.

例如，你可以在 EAS 构建钩子 之一中添加以下内容，并且环境变量 EXAMPLE_ENV 将一直可用，直到构建作业结束。

¥For example, you can add the following in one of the EAS Build hooks and the environment variable EXAMPLE_ENV will be available until the end of the build job.

Terminal
- set-env EXAMPLE_ENV "example value"

访问环境变量

¥Accessing environment variables

创建环境变量后，你可以在后续的 EAS 构建作业中使用 Node.js 中的 process.env.VARIABLE_NAME 或在 shell 脚本中将其读取为 $VARIABLE_NAME。

¥After creating an environment variable, you can read it on subsequent EAS Build jobs with process.env.VARIABLE_NAME from Node.js or in shell scripts as $VARIABLE_NAME.

常见问题

¥FAQ

使用 eas build 命令触发构建时，我是否可以在 CI 提供程序上设置环境变量？

¥Can I just set my environment variables on a CI provider when triggering the build using eas build command?

环境变量必须在 EAS 服务器上定义才能提供给 EAS Build 构建器。如果你从 CI 触发构建，则适用相同的规则，并且你应该注意不要将在 GitHub Actions（或你选择的提供商）上设置环境变量与在 EAS 服务器上设置环境变量和密钥混淆。

¥Environment variables must be defined on EAS servers to be made available to EAS Build builders. If you are triggering builds from CI the same rule applies, and you should be careful to not confuse setting environment variables on GitHub Actions (or the provider of your choice) with setting environment variables and secrets on EAS servers.

环境变量如何用于我的开发构建？

¥How do environment variables work for my development builds?

构建配置文件中设置的影响 app.config.js 的环境变量将用于配置开发构建。

¥Environment variables set in your build profile that impact app.config.js will be used for configuring the development build.

当你运行 npx expo start 在开发构建中加载应用时，将仅使用开发计算机上可用的环境变量。

¥When you run npx expo start to load your app inside of your development build, only environment variables that are available on your development machine will be used.

EAS 更新

¥EAS Update

将 .env 文件与 EAS 更新结合使用

¥Using .env files with EAS Update

未提供 --environment 标志时，eas update 将使用项目目录中的 .env 文件执行更新作业，而不会使用 EAS 服务器上设置的环境变量。

¥When the --environment flag is not provided, eas update will use the .env files present in your project directory for the update job and won't use the environment variables set on the EAS servers.

Expo 中的环境变量 描述了如何使用 .env 文件在 JavaScript 代码中设置和使用环境变量。Expo CLI 将使用你开发机器上的 .env 文件中的相应环境变量值替换你代码中的前缀变量（例如，process.env.EXPO_PUBLIC_VARNAME）。

¥Environment variables in Expo describes how to use .env files to set and use environment variables within your JavaScript code. Expo CLI will substitute prefixed variables in your code (for example,process.env.EXPO_PUBLIC_VARNAME) with the corresponding environment variable values in .env files present on your development machine.

当你运行 eas update 时，打包 JavaScript 时将评估所有 .env 文件。应用代码中的任何 EXPO_PUBLIC_ 变量都将被替换为发布更新的计算机上存在的 .env 文件中的相应值，无论是本地计算机还是 CI/CD 服务器。

¥When you run eas update, all .env files will be evaluated when your JavaScript is bundled. Any EXPO_PUBLIC_ variables in your application code will be replaced inline with the corresponding values from your .env files that are present on the machine from which the update is published, whether that is your local machine or your CI/CD server.

当将 .env 文件与 EAS Update 一起使用时，这些文件中的 EXPO_PUBLIC_ 变量仅在打包应用的 JavaScript 时使用。在评估 app.config.js 时它们将不可用。

使用 EAS 更新中的 --environment 标志

¥Using the --environment flag with EAS Update

当提供 --environment 标志时，eas update 将使用 EAS 服务器上的环境变量，而不会使用项目中存在的 .env 文件。Expo CLI 将使用 EAS 服务器上为使用 --environment 标志指定的环境设置的相应纯文本和敏感环境变量值替换代码中的前缀变量（例如 process.env.EXPO_PUBLIC_VARNAME）。

¥When the --environment flag is provided, eas update will use the environment variables on EAS servers for and won't use the .env files present in your project. Expo CLI will substitute prefixed variables in your code (for example,process.env.EXPO_PUBLIC_VARNAME) with the corresponding plain text and sensitive environment variable values set on EAS servers for the environment specified with the --environment flag.

应用代码中的任何 EXPO_PUBLIC_ 变量都将被替换为 EAS 环境中的相应值，无论是本地计算机还是 CI/CD 服务器。

¥Any EXPO_PUBLIC_ variables in your application code will be replaced inline with the corresponding values from your EAS environment whether that is your local machine or your CI/CD server.

我们建议使用 --environment 标志来确保更新和构建作业使用相同的环境变量。

¥We recommend using the --environment flag to ensure the same environment variables are used both for your update and build jobs.

管理环境变量

¥Managing environment variables

使用 Expo 网站

¥Using Expo website

创建、读取、更新、导出和删除环境变量的最简单方法是使用 Expo 网站。导航到 你项目上的环境变量页面 或 你账户上的环境变量页面 以管理你的环境变量。

¥The easiest way to create, read, update, export and delete environment variables is to use the Expo website. Navigate to the Environment Variables page on your project or Environment Variables page on your account to manage your environment variables.

使用 EAS CLI

¥Using EAS CLI

要使用 EAS CLI 管理环境变量，你可以使用 eas env:create、eas env:update、eas env:list 和 eas env:delete 命令。

¥To manage environment variables using EAS CLI, you can use the eas env:create, eas env:update, eas env:list, and eas env:delete commands.

你还可以使用 eas env:pull 命令将环境变量从 EAS 服务器拉到本地 .env 文件以进行开发。

¥You can additionally use eas env:pull command to pull environment variables from EAS servers to your local .env file for development.

有关这些命令的更多信息，请参阅 EAS CLI 命令参考。

¥See the EAS CLI command reference for more information about these commands.

局限性

¥Limitations

对于具有秘密可见性的环境变量，环境变量值大小限制为 32 KiB，对于其他可见性类型，环境变量值大小限制为 4 KiB。

¥Environment variable value size is limited to 32 KiB for environment variables with secret visibility and 4 KiB for other visibility types.

你可以为每个 Expo 账户创建最多 100 个账户范围的环境变量，并为每个应用创建 100 个项目特定的环境变量

¥You can create up to 100 account-wide environment variables for each Expo account and 100 project-specific environment variables for each app