使用 EAS 环境变量

通过示例了解如何在 EAS 中使用环境变量。

EAS 中的环境变量 描述了在 EAS 中使用环境变量的相关概念以及使用 Expo CLI 和 EAS CLI 处理它们的区别。在本指南中，你将通过实际示例学习如何在 EAS 中使用环境变量。

¥Environment variables in EAS describes concepts related to using environment variables in EAS and differences in handling them with Expo CLI and EAS CLI. In this guide, you will learn how to use environment variables in EAS with practical examples.

本指南中使用的示例是一个简单的项目，它在构建过程中以及出于配置目的使用常见的环境变量：

¥The example used in this guide is a simple project that uses common environment variables during the build process and for configuration purposes:

• EXPO_PUBLIC_API_URL：保存 API 服务器 URL 的纯文本 EXPO_PUBLIC_ 变量

  ¥EXPO_PUBLIC_API_URL: a plain text EXPO_PUBLIC_ variable that holds the URL of the API server

• APP_VARIANT：用于选择 应用变体 的纯文本变量

  ¥APP_VARIANT: a plain text variable to select an app variant

• GOOGLE_SERVICES_JSON：一个秘密文件变量，用于将 git 忽略的 google-services.json 文件提供给构建作业

  ¥GOOGLE_SERVICES_JSON: a secret file variable to supply your git ignored google-services.json file to the build job

• SENTRY_AUTH_TOKEN：保存用于在构建和更新后上传源映射的 Sentry 身份验证令牌的敏感变量

  ¥SENTRY_AUTH_TOKEN: a sensitive variable that holds the authentication token for Sentry used to upload source maps after builds and updates

在代码中使用环境变量

¥Use environment variables in your code

带有 EXPO_PUBLIC_ 前缀的环境变量可用作应用代码中的 process.env 变量。这意味着你可以使用它们根据环境变量的值动态配置你的应用行为。

¥The environment variables with the EXPO_PUBLIC_ prefix are available as process.env variables in your app's code. This means you can use them to dynamically configure your app behavior based on the values from environment variables.

import { Button } from 'react-native';

function Post() {
  const apiUrl = process.env.EXPO_PUBLIC_API_URL;

  async function onPress() {
    await fetch(apiUrl, { ... })
  }

  return <Button onPress={onPress} title="Post" />;
}

在上面的例子中，EXPO_PUBLIC_API_URL 用于动态设置获取请求的 API URL。

¥In above example, EXPO_PUBLIC_API_URL is used to dynamically set the API URL for the fetch request.

请勿将敏感信息存储在 EXPO_PUBLIC_ 变量中，例如私钥。这些变量将以纯文本形式显示在编译的应用中。

在应用配置解析期间可以使用没有 EXPO_PUBLIC_ 前缀的其他变量。一个例子是 APP_VARIANT 变量，用于根据所选的应用变体确定应用名称和包名称或包标识符。

¥Other variables, without the EXPO_PUBLIC_ prefix, can be used during app config resolution. An example of this is the APP_VARIANT variable used to determine the app name and package name or bundle identifier based on the selected app variant.

const IS_DEV = process.env.APP_VARIANT === 'development';
const IS_PREVIEW = process.env.APP_VARIANT === 'preview';

const getUniqueIdentifier = () => {
  if (IS_DEV) {
    return 'com.yourname.stickersmash.dev';
  }

  if (IS_PREVIEW) {
    return 'com.yourname.stickersmash.preview';
  }

  return 'com.yourname.stickersmash';
};

const getAppName = () => {
  if (IS_DEV) {
    return 'StickerSmash (Dev)';
  }

  if (IS_PREVIEW) {
    return 'StickerSmash (Preview)';
  }

  return 'StickerSmash: Emoji Stickers';
};

export default {
  name: getAppName(),
  %%placeholder-start%%... %%placeholder-end%%
  ios: {
    bundleIdentifier: getUniqueIdentifier(),
    %%placeholder-start%%... %%placeholder-end%%
  },
  android: {
    package: getUniqueIdentifier(),
    %%placeholder-start%%... %%placeholder-end%%
  },
};

GOOGLE_SERVICES_JSON 是一个秘密文件变量，在 EAS 服务器之外不可读，用于向构建作业提供 git 忽略的 google-services.json 文件。要在应用配置中使用它，你可以使用 process.env 变量并在未设置变量的情况下提供后备值（对于本地开发，当你通常在项目的存储库中使用它时）。

¥The GOOGLE_SERVICES_JSON is a secret file variable in that is not readable outside of EAS servers and is used to provide the git ignored google-services.json file to the build job. To use it in the app config, you can use the process.env variable and provide a fallback value in case the variable is not set (for local development when you usually have it inside your project's repository).

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

创建环境变量

¥Create environment variables

要在 EAS 服务器上创建环境变量，你可以使用 环境变量创建表单 页面或 eas env:create 命令。

¥To create environment variables on EAS servers, you can use the environment variables creation form page or eas env:create command.

在表单中，你可以指定变量的名称、值、环境和可见性。

¥In the form, you can specify the name, value, environment(s) and visibility for the variable.

创建的环境变量将在 Expo 网站的 环境变量 页面上的列表中提供。

¥Created environment variables will be available in the list on the Environment Variables page on the Expo website.

根据本例中的环境变量，列表将如下所示：

¥Based on the environment variables in this example, the list will look like this:

在上面的例子中，SENTRY_AUTH_TOKEN 可以被视为敏感的环境变量。它用于在构建和更新后对 Sentry 进行身份验证以上传源地图，因此它必须在 EAS 服务器之外可访问。

¥In above example, the SENTRY_AUTH_TOKEN can be treated as a sensitive environment variable. It is used to authenticate Sentry to upload source maps after builds and updates, so it has to be accessible outside of EAS servers.

为你的本地开发提取环境变量

¥Pull environment variables for your local development

使用 EAS 环境变量进行本地开发的最简单方法是使用 eas env:pull --environment environment 命令将它们拉入 .env 文件中。你还可以使用 Expo 网站 上的导出选项下载文件并将其存储在你的项目中。

¥The easiest way to use the EAS environment variables for local development is to pull them into a .env file using the eas env:pull --environment environment command. You can also use the Export option on the Expo website to download the file and store it inside your project.

运行以下命令在项目的根目录中创建一个 .env 文件：

¥Run the following command to create a .env file in the root of your project:

创建的 .env 文件将如下所示：

¥The created .env file will look like this:

# Environment: development

APP_VARIANT=development
EXPO_PUBLIC_API_URL=https://staging.my-api-url.mycompany.com
# GOOGLE_SERVICES_JSON=***** (secret variables are not available for reading)
SENTRY_AUTH_TOKEN=token

使用 npx expo start 命令时，下载的 EXPO_PUBLIC_ 变量可用于本地开发。GOOGLE_SERVICES_JSON 变量无法被拉到本地环境，因为它是一个秘密变量。

¥The downloaded EXPO_PUBLIC_ variables are available for local development when using the npx expo start command. The GOOGLE_SERVICES_JSON variable is not available to be pulled to the local environment since it is a secret variable.

最好将所有 .env 文件添加到 .gitignore，以避免将它们提交到你的存储库并暴露敏感信息。提交 .env 文件还可能导致环境变量解析冲突。

将环境变量与 EAS Build 一起使用

¥Use 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.

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

在此示例应用中，除 GOOGLE_SERVICES_JSON（密钥）之外的所有环境变量都将在 EAS CLI 中的构建配置解析期间可用。

¥In this example app, all of the environment variables except GOOGLE_SERVICES_JSON (which is secret) will be available during build configuration resolution in EAS CLI.

在这种情况下，为 APP_VARIANT 变量设置正确的可见性尤为重要，以便变量在 EAS CLI 中可用，并能够为正确的包名称和包标识符生成凭据。

¥It's especially important in this context to have the correct visibility set for the APP_VARIANT variable so that the variable available in EAS CLI and is able to generate credentials for the correct package name and bundle identifier.

将环境变量与 EAS Update 一起使用

¥Use environment variables with EAS Update

在 EAS Update 中使用 EAS 环境变量的最方便方法是运行指定 --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 环境中的环境变量。此标志允许你在创建更新时使用与创建构建相同的环境变量。

¥When the --environment flag is used, only the environment variables from the specified EAS environment will be used during the update process. This flag allows you to use the same environment variables while creating updates as with creating builds.

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

如果未指定 --environment 标志，则 eas update 命令的默认行为是使用 .env 文件。

将环境变量用于其他命令

¥Use 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.