EAS Build 中的环境变量和密钥

了解如何在 EAS 构建中使用环境变量和密钥。

Expo 中的环境变量 描述了如何使用 .env 文件来设置可以内联到 JavaScript 代码中的环境变量。Expo CLI 会将代码中正确添加前缀的变量（例如，process.env.EXPO_PUBLIC_VARNAME）替换为开发计算机上存在的 .env 文件中的相应环境变量值。

¥Environment variables in Expo describes how to use .env files to set environment variables that can be inlined in your JavaScript code. The Expo CLI will substitute properly 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 构建作业在远程服务器上运行，因此这些 .env 文件可能不可用。例如，如果 .env 文件列在 .gitignore 中或未提交到本地版本控制系统，则它们会从你上传的项目中排除。此外，你可能希望在构建时使用 JavaScript 代码外部的环境变量来自定义应用二进制文件，例如为错误报告服务设置包标识符或私钥。因此，EAS Build 允许你在 eas.json 中设置每个构建配置文件的环境变量以及不应通过 EAS Secrets 提交给源代码管理的敏感值。

¥Because your EAS Build job runs on a remote server, these .env files might not be available. For instance, .env files are excluded from your uploaded project if they are listed in .gitignore or not committed to your local version control system. Additionally, you may want to use environment variables outside of your JavaScript code to customize your app binary at build time, such as setting a bundle identifier or a private key for an error reporting service. Therefore, EAS Build lets you set per-build-profile environment variables within eas.json as well as sensitive values that should not be committed to source control via EAS Secrets.

在 eas.json 中设置纯文本环境变量

¥Setting plaintext environment variables in eas.json

用于应用代码

¥For use in application code

如果你按照 环境变量指南 中的说明在 .env 文件中设置用于本地开发的变量，则可以在 eas.json 的构建配置文件中设置这些相同的变量。例如，你可以在本地开发时将 API URL 变量设置为本地后端服务器，将测试服务器设置为用于测试，将生产服务器设置为生产构建。

¥If you set variables in a .env file for local development as described in the environment variables guide, you can set those same variables in a build profile in eas.json. For instance, you might set an API URL variable to a local backend server when developing locally, a test server for testing, and a production server for production builds.

在这种情况下，你的 .env 文件可能如下所示：

¥In this case, your .env file might look like this:

EXPO_PUBLIC_API_URL=http://api.local

将任何适用的 .env 文件添加到你的 .gitignore（和 .easignore，如果你的项目有的话）文件中，这样它们就不会与你的 EAS 构建作业一起上传：

¥Add any applicable .env files to your .gitignore (and .easignore, if your project has one) file so they are not uploaded with your EAS Build job:

# ignores all .env files
.env*

然后你可以为 eas.json 中的每个构建配置文件设置相同的环境变量：

¥Then you can set the same environment variable for each build profile in eas.json:

{
  "build": {
    "production": {
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api.production.com"
      }
    },
    "test": {
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api.test.com"
      }
    }
  }
}

对 process.env.EXPO_PUBLIC_API_URL 的任何引用都将根据环境替换为适用的值。

¥Any reference to process.env.EXPO_PUBLIC_API_URL will be substituted for the applicable value depending on the environment.

SDK 49 及更高版本中提供了 EXPO_PUBLIC_ 变量替换。

¥EXPO_PUBLIC_ variable replacement is available in SDK 49 and higher.

供你的 Expo 配置使用

¥For use by your Expo config

你可以使用 动态配置 (app.config.js) 中的环境变量来更改应用的构建方式。例如，你可能想要更改测试版本的应用图标或简称。

¥You can use environment variables in a dynamic config (app.config.js) to change how your app is built. For instance, you might want to change your app icon or short name for a test build.

在构建配置文件中设置变量：

¥Set the variable in your build profile:

{
  "build": {
    "test": {
      "env": {
        "APP_ICON": "./assets/icon-test.png",
        "APP_NAME": "My App (Test)"
      }
    }
  }
}

然后在 app.config.js 中引用该变量，为本地开发提供后备：

¥Then reference that variable in your app.config.js, providing fallbacks for local development:

module.exports = {
  // use the variable if it's defined, otherwise use the fallback
  icon: process.env.APP_ICON || './assets/icon.png',
  name: process.env.APP_NAME || 'My App',
};

评估 app.config.js 时，eas.json 构建配置文件中的所有环境变量都可用。最好只对应用代码中使用的变量使用 EXPO_PUBLIC_ 前缀。

¥All environment variables in your eas.json build profile are available when evaluating app.config.js. It's a good practice to only use the EXPO_PUBLIC_ prefix for variables used within your application code.

供其他构建步骤使用

¥For use by other build steps

eas.json 构建配置文件中设置的任何环境变量也可用于其他构建步骤。

¥Any environment variables set in your eas.json build profile are also available to other build steps.

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

¥You can also set environment variables dynamically during the build process. 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.

内置环境变量

¥Built-in environment variables

以下环境变量公开给每个构建作业，并且可以在任何构建步骤中使用。在本地评估 app.config.js 时未设置它们：

¥The following environment variables are exposed to each build job and can be used within any build step. They are not set 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

在环境变量中使用秘密

¥Using secrets in environment variables

要为你的构建作业提供对过于敏感而无法包含在源代码和 Git 存储库中的值的访问权限，你可以使用 "秘密"。

¥To provide your build jobs with access to values that are too sensitive to include in your source code and Git repository, you can use "Secrets".

秘密由名称和值组成。该名称只能包含字母数字字符和下划线。该值限制为 32 KiB。

¥A secret is made up of a name and a value. The name can only contain alphanumeric characters and underscores. The value is limited to 32 KiB.

该值可以是文件或字符串值。对于文件，其内容将保存到 EAS 构建服务器上的临时文件中。文件路径可通过环境变量获得。例如，如果你创建了一个名为 SECRET_FILE 的文件密钥，EAS Build 将在 /Users/expo/workingdir/environment-secrets/__UNIQUE_RANDOM_UUID__ 处创建一个文件，并且 SECRET_FILE 将设置为该路径。

¥The value can be either a file or a string value. For a file, its contents are saved to a temporary file on EAS Build servers. The file path is available via the environment variable. For example, if you created a file secret named SECRET_FILE, EAS Build will create a file at /Users/expo/workingdir/environment-secrets/__UNIQUE_RANDOM_UUID__, and SECRET_FILE will be set to that path.

秘密值在静态和传输过程中进行加密，并且仅在安全环境中由 EAS 服务器解密。

¥The secret values are encrypted at rest and in transit and are only decrypted in a secure environment by EAS servers.

你可以为每个 Expo 账户创建最多 100 个账户范围的密钥，并为每个应用创建 100 个应用特定的密钥。账户范围的秘密将暴露给所有应用中的每个构建环境。应用特定的密钥仅适用于为其定义的应用，并将覆盖任何具有相同名称的账户范围的密钥。

¥You can create up to 100 account-wide secrets for each Expo account and 100 app-specific secrets for each app. Account-wide secrets will be exposed to every build environment across all of your apps. App-specific secrets only apply to the app they're defined for and will override any account-wide secrets with the same name.

你可以通过 Expo 网站和 EAS CLI 管理密钥。

¥You can manage secrets through the Expo website and EAS CLI.

始终记住，客户端代码中包含的任何内容都应被视为公共，并且对于任何可以运行该应用的个人来说都是可读的。EAS 密钥旨在用于为 EAS 构建作业提供值，以便可以在构建过程中使用它们。正确使用的示例包括设置 NPM_TOKEN 以从 npm 安装私有包，或设置 Sentry API 密钥以创建版本并将源映射上传到其服务。EAS Secrets 不会为你最终嵌入应用本身的值（例如 AWS 访问密钥或其他私钥）提供任何额外的安全性。

Expo 网站上的秘密

¥Secrets on the Expo website

要创建账户范围的密钥，请在账户设置中导航到 Secrets 选项卡。

¥To create account-wide secrets, navigate to Secrets tab in your account's settings.

要创建特定于应用的密钥，请在项目仪表板中导航到 Secrets 选项卡。

¥To create app-specific secrets, navigate to the Secrets tab in your project's dashboard.

使用 EAS CLI 添加密钥

¥Adding secrets with EAS CLI

要创建新密钥，请运行 eas secret:create：

¥To create a new secret, run eas secret:create:

要查看此项目的任何现有密钥，请运行 eas secret:list：

¥To view any existing secrets for this project, run eas secret:list:

从 dotenv 文件导入密钥

¥Importing secrets from a dotenv file

如果你使用 .env 文件在本地存储密钥，则可以使用 eas secret:push 命令将所有密钥导入到 EAS：

¥If you're using a .env file for storing your secrets locally, you can use the eas secret:push command to import all of them to EAS:

请注意，如果 dotenv 文件中定义的某些密钥已存在于服务器上，EAS CLI 将失败。要强制覆盖这些密钥，请将 --force 标志传递给命令。

¥Beware that EAS CLI will fail if some of the secrets defined in the dotenv file already exist on the server. To force override those secrets, pass the --force flag to the command.

多普勒积分

¥Doppler integration

你可以使用 eas secret:push 命令将 EAS 与你的 Doppler 项目集成：

¥You can use the eas secret:push command to integrate EAS with your Doppler project:

访问 EAS Build 中的密钥

¥Accessing secrets in EAS Build

创建密钥后，你可以在后续 EAS 构建作业中使用 Node.js 中的 process.env.VARIABLE_NAME 或在 shell 脚本中读取它作为 $VARIABLE_NAME。

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

常见问题

¥Common questions

EAS Build 可以使用 .env 文件吗？

¥Can EAS Build use .env files?

.env 文件中定义的环境变量仅被 Expo CLI 考虑。因此，如果你将 .env 文件上传到 EAS Build，它可用于将 EXPO_PUBLIC_ 变量内联到你的应用代码中。

¥Environment variables defined in a .env file are only considered by the Expo CLI. Therefore, if you upload a .env file to EAS Build, it can be used to inline EXPO_PUBLIC_ variables into your application code.

但是，建议的做法是在本地环境中使用 .env 文件，同时在 eas.json 中定义 EAS Build 的环境变量。在运行 eas build 时评估 app.config.js 时，将使用 eas.json 构建配置文件中定义的环境变量，并且可用于 EAS 构建服务器上构建过程的所有步骤。

¥However, the recommended practice is to use .env files in your local environment, while defining environment variables for EAS Build in eas.json. Environment variables defined in your eas.json build profile will be used when evaluating your app.config.js when running eas build and will be available to all steps of the build process on the EAS Build server.

这可能会导致 .env 文件和 eas.json 构建配置文件之间出现一些变量重复，但可以更轻松地查看哪些变量将应用于所有环境。

¥This may result in some duplication of variables between .env files and eas.json build profiles, but makes it easier to see what variables will be applied across all environments.

如何在本地开发环境、EAS 更新和 EAS 构建之间共享环境变量？

¥How do I share environment variables between my local development environment, EAS Update, and EAS Build?

eas.json 中定义的环境变量仅在运行 EAS 构建作业时可用。但是，你可能希望根据构建配置文件更改应用代码中使用的变量，同时最大限度地减少可能保留在 .env 文件中以进行本地开发或发布到 EAS 更新时的重复值。

¥Environment variables defined in eas.json are only available when running an EAS Build job. However, you may wish to change variables used within your application code based on the build profile while minimizing duplicating values you might keep in an .env file for local development or for when publishing to EAS Update.

我们的 EAS 更新指南中的环境变量 描述了在所有这些上下文之间共享环境变量的几种方法。

¥Our Environment variables in EAS Update guide describes a few approaches for sharing environment variables between all of these contexts.

如何处理密钥、eas.json 中的 env 字段和 .env 文件之间的命名冲突？

¥How are naming collisions between secrets, the env field in eas.json, and .env files handled?

环境变量按以下顺序应用：

¥Environment variables are applied in the following order:

1. eas.json 构建配置文件 env 字段

   ¥eas.json build profile env field

2. EAS Secrets 中定义的环境变量

   ¥Environment variables defined in EAS Secrets

3. .env 文件提交给源代码管理并且不在 .easignore 中

   ¥**.env** files committed to source control and are not in .easignore

最后应用的变量源将覆盖先前加载的同名变量源。因此，在 Expo 网站上或使用 eas secret:create 创建的密钥将优先于通过 eas.json 中的 env 字段设置的同名环境变量。

¥Variable sources applied last will overwrite the previously loaded source for variables with the same name. So, a secret created on the Expo website or with eas secret:create will take precedence over an environment variable of the same name that is set through the env field in eas.json.

例如，如果你创建一个名为 MY_TOKEN 和值 secret 的密钥，并且还在 eas.json 中设置了 "env": { "MY_TOKEN": "public" }，则 EAS Build 上的 process.env.MY_TOKEN 将计算为 secret。

¥For example, if you create a secret with the name MY_TOKEN and value secret and also set "env": { "MY_TOKEN": "public" } in your eas.json, then process.env.MY_TOKEN on EAS Build will evaluate to secret.

环境变量如何适用于我的 Expo Development Client 构建？

¥How do environment variables work for my Expo Development Client builds?

构建配置文件中设置的影响 app.config.js 的环境变量将用于配置开发构建。当你运行 npx expo start 在开发构建中加载应用时，将仅使用开发计算机上可用的环境变量。

¥Environment variables set in your build profile that impact app.config.js will be used for configuring the development build. 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.

我可以只在 CI 提供程序上设置环境变量吗？

¥Can I just set my environment variables on a CI provider?

环境变量必须在 eas.json 中定义，以供 EAS Build 构建者使用。如果你是 从 CI 触发构建，则适用相同的规则，并且你应该小心，不要将 GitHub Actions（或你选择的提供商）上的设置环境变量与 eas.json 中的设置环境变量和密钥混淆。

¥Environment variables must be defined in eas.json to be made available to EAS Build builders. If you are triggering builds from CI this 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 in eas.json.

如何上传秘密文件并在我的应用配置中使用它？

¥How to upload a secret file and use it in my app config?

将文件密钥上传到 EAS 的一个常见用例是当你想要为构建提供 google-services.json 和 GoogleService-Info.plist 文件时。通常，不应将这些文件检入存储库。

¥A common use case for uploading file secrets to EAS is when you want to supply your build with the google-services.json and GoogleService-Info.plist files. Usually, those files should not be checked into the repository.

以下是如何将 google-services.json 上传到 EAS 并在应用配置中使用它的示例：

¥Here's an example of how to upload google-services.json to EAS and use it in your app config:

export default {
  %%placeholder-start%%...%%placeholder-end%%
  android: {
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON,
    %%placeholder-start%%...%%placeholder-end%%
  },
};