在 EAS 中使用环境变量

了解如何在 EAS 构建、更新、托管和工作流程任务中使用环境变量。

以下部分将介绍如何在 EAS 构建、更新和工作流程作业中使用环境变量。

🌐 The following sections cover how to use environment variables in EAS builds, updates, and workflow jobs.

在 EAS Build 中使用环境变量

🌐 Using environment variables with EAS Build

为了完全控制用于构建的环境，你可以在 eas.json 文件的构建配置设置中指定 environment 字段。

🌐 To have a full control over the environments used for your builds, you can specify the environment field in the build profiles settings in the eas.json file.

{
  "build": {
    "development": {
      "environment": "development"
      %%placeholder-start%%... %%placeholder-end%%
    },
    "preview": {
      "environment": "preview"
      %%placeholder-start%%... %%placeholder-end%%
    },
    "production": {
      "environment": "production"
      %%placeholder-start%%... %%placeholder-end%%
    },
    "my-profile": {
      "environment": "production"
      %%placeholder-start%%... %%placeholder-end%%
    }
  }
}

在构建过程中，将使用所选环境的所有环境变量。在基于 EAS CLI 中的动态应用配置解析构建配置时，明文和敏感变量也将可用。

🌐 All of the environment variables from the selected environment will be used during the build process. Plain text and sensitive variables will be available when resolving build configuration based on the dynamic app config in EAS CLI as well.

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

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

• 当 distribution设置为store时production``
• developmentClient 为 true 时的 development
• preview 用于其他所有情况

信息 在 EAS CLI 中，秘密类型的环境变量在构建配置解析期间不可用，因为它们在 EAS 服务器之外无法读取。

在 EAS 更新中使用环境变量

🌐 Using environment variables with EAS Update

默认情况下，当你在使用 eas update 命令时省略 --environment 标志，EAS Update 会使用项目目录中本地 .env 文件里的环境变量。

🌐 By default, EAS Update uses environment variables from the local .env files present in your project directory when you omit the --environment flag with eas update command.

使用 EAS Update 最方便的方法是运行带有指定 --environment 标志的 eas update 命令：

🌐 The most convenient way to use EAS environment variables with EAS Update is to run the eas update command with the --environment flag specified:

当使用 --environment 标志时，更新过程中只会使用指定 EAS 环境的环境变量，不会使用项目中存在的 .env 文件。此标志允许你在创建更新时使用与创建构建时相同的环境变量。

🌐 When the --environment flag is used, only the environment variables from the specified EAS environment will be used during the update process and won't use the .env files present in your project. This flag allows you to use the same environment variables while creating updates as with creating builds.

Expo CLI 会将你代码中的带前缀变量（例如 process.env.EXPO_PUBLIC_VARNAME）替换为对应的纯文本和 EAS 服务器上为通过 --environment 标志指定的环境设置的敏感环境变量值。你应用代码中的任何 EXPO_PUBLIC_ 变量都会被替换为来自你的 EAS 环境的对应值，无论该环境是在你的本地计算机还是在你的 CI/CD 服务器上。

🌐 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. 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.

信息 在更新过程中，秘密变量将不可用，因为它们在 EAS 服务器之外不可读取。

在 EAS Hosting 中使用环境变量

🌐 Using environment variables with EAS Hosting

一个 Expo Router 网络项目可以包含在客户端和服务器端都使用的环境变量。客户端的值会在你运行 npx expo export 时内联到 JavaScript 包中，而服务器端的值会存储在服务器上，并在你运行 eas deploy 时随你的 API 路由一起部署。

🌐 An Expo Router web project can include environment variables that are used on both the client and the server. Client-side values are inlined in the JavaScript bundle when you run npx expo export, while server-side values are stored on the server and are deployed with your API routes when you run eas deploy.

警告 使用 EAS 托管时，只能使用 纯文本 和 敏感的 环境变量。密钥信息不能通过 EAS 托管进行部署。

存储环境变量

🌐 Storing environment variables

在使用 EAS 环境变量部署项目时，请注意客户端代码和服务器端代码的环境变量是在不同步骤中包含的：

🌐 When deploying a project with EAS environment variables, note that the environment variables for the client-side and server-side code are included at different steps:

• 运行 npx expo export --platform web 将会在前端代码中内联 EXPO_PUBLIC_ 变量。因此，请确保在运行 npx export 命令之前，你的 .env.local 文件包含正确的环境变量。
• eas deploy --environment production 将在 API 路由中包含给定环境（在本例中为 production）的所有变量。使用 --environment 标志加载的 EAS 环境变量将优先于 .env 和 .env.local 文件中定义的变量。

警告 环境变量是按部署设置的，并且部署是不可变的。这意味着在更改环境变量后，你需要重新导出项目并重新部署，才能使其更新。

用于本地开发

🌐 For local development

对于本地开发，客户端和服务器端的环境变量都从本地 .env 文件加载，这些文件应被 git 忽略。如果你使用 EAS 环境变量，请使用 eas env:pull 来获取 development、preview 或 production 的环境变量。

🌐 For local development, both client- and server-side environment variables are loaded from local .env files, which should be gitignored. If you are using EAS environment variables, use eas env:pull to retrieve the environment variables for development, preview, or production.

为其他命令使用环境变量

🌐 Using environment variables for other commands

向其他 EAS 命令提供非保密 EAS 环境变量的一种方法是使用 eas env:exec 命令。

🌐 One way to supply non-secret EAS environment variables to other EAS commands is to use the eas env:exec command.

例如，在创建更新包后，使用 SENTRY_AUTH_TOKEN 变量将源映射上传到 Sentry 时，它可能会很有用。

🌐 For example, it can be useful when uploading source maps to Sentry using a SENTRY_AUTH_TOKEN variable after an update bundle is created.

在 EAS 工作流程中使用环境变量

🌐 Using environment variables in EAS Workflows

为工作流作业设置 EAS 环境

🌐 Setting EAS environment for workflow jobs

• 构建任务：环境来自 eas.json 中的构建配置文件（build.<profile>.environment）。如果该字段缺失，将应用上述描述的自动默认值。在 EAS Build 中使用环境变量。
• 其他任务（例如，更新、提交、指纹识别、Maestro 和自定义任务）：设置 jobs.<job_id>.environment。如果省略，则使用 production。显式设置它有助于保持任务与你在工作流中之前使用的构建配置保持同步。

在以下示例中，一个构建任务被配置为使用 preview 配置文件，然后一个更新任务被配置为使用相同的 EAS 环境。

🌐 In the following example, a build job is configured to use the preview profile, then an update job is configured to use the same EAS environment.

name: Publish preview build and update

jobs:
  build_preview:
    type: build
    params:
      platform: ios
      profile: preview # uses environment from eas.json's build.preview.environment

  publish_preview_update:
    needs: [build_preview]
    type: update
    environment: preview # pulls variables from the preview environment
    params:
      branch: preview

在以下示例中，指纹作业被配置为使用 production 环境，然后构建作业被配置为使用相同的 EAS 环境。

🌐 In the following example, a fingerprint job is configured to use the production environment, then a build job is configured to use the same EAS environment.

name: Fingerprint and build

jobs:
  fingerprint:
    type: fingerprint
    environment: production # defaults to production, but set explicitly to match the build
  build_ios:
    needs: [fingerprint]
    type: build
    params:
      platform: ios
      profile: production # uses environment from eas.json's build.production.environment

保持工作环境值与构建配置文件同步，以避免秘密信息不匹配。例如，指纹/更新作业通常应与构建的配置环境相匹配。

🌐 Keep the job environment value in sync with the build profile to avoid mismatched secrets. For example, fingerprint/update jobs should usually match the build's profile environment.

在作业执行过程中动态设置环境变量

🌐 Dynamically setting environment variables during the job execution

你也可以在作业执行期间使用 set-env 命令动态设置环境变量。set-env 可执行文件在 EAS 构建工作者的 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 Build hooks 中添加以下内容，环境变量 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.

访问环境变量

🌐 Accessing environment variables

创建环境变量后，你可以在后续的 EAS Build 作业中通过 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.