This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

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

以下章节介绍如何在 EAS builds、updates 和 workflow jobs 中使用环境变量。

在 EAS Build 中使用环境变量

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

{
  "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 中动态 app config 的构建配置解析时，也可以使用纯文本和敏感变量。

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

• 当 distribution 设置为 store 时，使用 production
• 当 developmentClient 为 true 时，使用 development
• 其他情况使用 preview

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

在 EAS Update 中使用环境变量

在 SDK 55 或更高版本 中，运行 eas update 时必须使用 --environment 标志。指定的 EAS 环境中的环境变量会在更新过程中使用。对于使用 SDK 54 或更早版本的项目，如果省略 --environment 标志，eas update 会回退到本地的 .env 文件。

要在 EAS Update 中使用 EAS 环境变量，请使用 --environment 标志运行 eas update 命令：

当使用 --environment 标志时，更新过程中只会使用指定 EAS 环境中的环境变量，不会使用项目中存在的 .env 文件。这样可以确保你的更新和构建使用相同的环境变量。

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

--environment 标志确保更新和构建 job 使用相同的环境变量。

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

在 EAS Hosting 中使用环境变量

Expo Router Web 项目可以包含同时用于客户端和服务端的环境变量。客户端值会在运行 npx expo export 时内联到 JavaScript bundle 中，而服务端值会保存在服务器上，并在运行 eas deploy 时与 API 路由一起部署。

使用 EAS Hosting 时，只能使用纯文本和敏感环境变量。秘密变量不能通过 EAS Hosting 部署。

存储环境变量

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

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

环境变量是按部署生效的，且部署是不可变的。这意味着在更改环境变量之后，你需要重新导出项目并重新部署，才能让这些更改生效。

本地开发

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

在其他命令中使用环境变量

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

例如，在更新 bundle 创建后，使用 SENTRY_AUTH_TOKEN 变量上传 source map 到 Sentry 时，这会很有用。

在 EAS Workflows 中使用环境变量

为 workflow jobs 设置 EAS 环境

当你省略 jobs.<job_id>.environment 时，默认值取决于 job 类型：

• 构建 jobs：环境来自 eas.json 中的构建 profile（build.<profile>.environment）。如果缺少该字段，则应用上述自动默认值。在 EAS Build 中使用环境变量。
• 提交 jobs：环境继承自提交的构建。
• Maestro jobs（maestro 和 maestro-cloud）：环境默认为 preview。
• 其他 jobs（例如 update、fingerprint、deploy 和自定义 jobs）：环境默认为 production。

在 job 上显式设置 environment 可以覆盖其默认值，并使其与 workflow 中之前使用的构建 profile 保持同步。有关完整说明，请参阅Job 环境。

在下面的示例中，build job 配置为使用 preview profile，然后 update job 配置为使用相同的 EAS 环境。

name: Publish preview build and update

jobs:
  build_preview:
    type: build
    params:
      platform: ios
      profile: preview # 使用来自 eas.json 的 build.preview.environment 的环境

  publish_preview_update:
    needs: [build_preview]
    type: update
    environment: preview # 从 preview 环境中拉取变量
    params:
      branch: preview

在下面的示例中，fingerprint job 配置为使用 production 环境，然后 build job 配置为使用相同的 EAS 环境。

name: Fingerprint and build

jobs:
  fingerprint:
    type: fingerprint
    environment: production # 默认为 production，但显式设置以与 build 匹配
  build_ios:
    needs: [fingerprint]
    type: build
    params:
      platform: ios
      profile: production # 使用来自 eas.json 的 build.production.environment 的环境

请将 job 的环境值与 build profile 保持一致，以避免 secret 不匹配。例如，fingerprint/update jobs 通常应与 build 的 profile 环境保持一致。

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

你还可以在 job 执行期间使用 set-env 命令动态设置环境变量。 set-env 可执行文件在 EAS Build workers 的 PATH 中可用，可用于设置在后续构建阶段可见的环境变量。

例如，你可以在某个 EAS Build hooks 中添加以下内容，环境变量 EXAMPLE_ENV 将一直可用到构建 job 结束。

访问环境变量

创建环境变量后，你可以在后续的 EAS Build jobs 中通过 Node.js 中的 process.env.VARIABLE_NAME 或 shell 脚本中的 $VARIABLE_NAME 来读取它。