关于 EAS 中环境变量的常见问题

关于 EAS 中环境变量的常见问题解答。

本页涵盖有关 EAS 中环境变量的常见问题解答。

🌐 This page covers frequently asked questions about environment variables in EAS.

在我的 EAS 项目中使用环境变量的推荐工作流程是什么？

🌐 What is the recommended workflow for using environment variables in my EAS project?

在你的 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

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

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

我可以在使用 `eas build` 命令触发构建时，在 CI 提供商上设置我的环境变量吗？

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

环境变量必须在 EAS 服务器上定义，才能供 EAS 构建器使用。如果你是从 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 项目中使用文件环境变量吗？

🌐 Can I use file environment variables in my EAS project?

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

🌐 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%%
  },
};

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

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

使用 Expo 框架和 EAS 时在使用环境变量上的一个区别是，EAS CLI 本身不支持在解析应用配置时通过加载 .env 文件来设置环境变量。相反，建议使用 EAS 的环境变量管理系统，并通过 EAS CLI 命令为你的构建任务和更新设置环境变量，以避免混淆，并确保在以下情况中使用完全相同的环境变量：

🌐 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 app 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 在准备应用配置时完成
远程工作发生在 EAS 服务器上，这些服务器通常无法访问被 git 忽略的本地 .env 文件

使用 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).

为了确保你在更新中可以使用与构建作业相同的环境变量，你可以在 eas update 命令中使用 --environment 标志，以强制其仅使用在 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 中使用环境变量有任何限制吗？

🌐 Are there any limitations to using environment variables in EAS?

对于具有秘密可见性的环境变量，环境变量值的大小限制为 32 KiB，对于其他可见性类型则限制为 4 KiB。
每个 Expo 账户最多可以创建 150 个全账户环境变量，每个应用最多可以创建 200 个项目特定的环境变量。
自定义环境每个项目限制为 10 个。
在创建自定义环境时，环境名称可以包含字母、数字、下划线和连字符，长度为3到100个字符。