在 EAS 中创建和管理环境变量

了解如何使用 EAS 控制台和 EAS CLI 创建、作用域和使用环境变量。

以下部分介绍了如何使用 EAS 仪表板和 EAS CLI 创建、定义作用域以及使用环境变量。

🌐 The following sections cover how to create, scope, and consume environment variables with EAS dashboard and EAS CLI.

创建环境变量

🌐 Create environment variables

• 选择一个环境或多个环境：默认情况下提供 development、preview 和 production。变量可以在它们之间重用，也可以为每个环境自定义。
• 选择范围：项目范围的变量适用于单个项目。账户范围的变量可以在多个项目中重复使用，并在构建时与项目变量合并。
• 选择可见性：对于绝不应离开 EAS 服务器的值，请使用 秘密；对于可能在本地显示的值，请使用 敏感；对于非敏感值，请使用 明文。

在仪表板中创建变量

🌐 Create variables in the dashboard

要在 EAS 服务器上创建新的环境变量，你可以在项目仪表板中导航至 项目设置 > 环境变量，然后点击 添加变量 按钮。

🌐 To create a new environment variable on EAS servers, in your project dashboard, you can navigate to the Project settings > Environment variables and then click on the Add Variables button.

使用 环境变量创建表单 页面来设置名称、值、环境、可见性以及可选描述。

🌐 Use the environment variables creation form page to set the name, value, environment(s), visibility, and optional description.

创建的变量会出现在列表中，显示其作用域、可见性和环境标签。根据此示例中的环境变量，列表可能如下所示：

🌐 Created variables appear in the list with their scope, visibility, and environment tags. Based on the environment variables in this example, the list may look like this:

在上面的示例列表中：

🌐 In the above example list:

• SENTRY_AUTH_TOKEN 变量是一个敏感的环境变量。它用于在构建和更新后对 Sentry 进行身份验证以上传源映射，并且必须在 EAS 服务器之外也能访问。
• GOOGLE_SERVICES_JSON 变量是一个秘密环境变量，并使用上传的文件。它用于验证 Google 以访问 Google 服务的 JSON 文件，必须安全地存储在 EAS 服务器上。这个上传的 JSON 文件通常会被添加到你项目的 .gitignore 中。
• 所有其他变量，例如 APP_VARIANT 和 EXPO_PUBLIC_API_URL，都是纯文本环境变量。

使用 EAS CLI 创建变量

🌐 Create variables with EAS CLI

使用 eas env:create 添加变量，使用 eas env:list 验证已设置的内容。

🌐 Use eas env:create to add variables and eas env:list to verify what is set.

在代码中使用环境变量

🌐 Using environment variables in your code

客户端值

🌐 Client-side values

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

🌐 The environment variables with the EXPO_PUBLIC_ prefix are available as process.env variables in your app's code. You can use them dynamically to configure your app behavior based in their values:

import { Button } from 'react-native';

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

  async function onPress() {
    await fetch(apiUrl, {
      %%placeholder-start%%... %%placeholder-end%%
    });
  }

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

在上面的例子中，EXPO_PUBLIC_API_URL 被用来动态设置 fetch 请求的 API URL。

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

警告 不要将密钥信息放入 EXPO_PUBLIC_ 变量中。客户端打包中的所有内容都可以被终端用户读取。

构建时间和应用配置

🌐 Build-time and app config

其他没有 EXPO_PUBLIC_ 前缀的变量，可以在 应用配置 解析过程中用于配置应用的行为。例如，APP_VARIANT 变量用于确定所选 应用变体 的应用名称、包名和打包标识符：

🌐 Other variables that are without EXPO_PUBLIC_ prefix, can be used during app config resolution to configure your app's behavior. For example, the APP_VARIANT variable is used to determine the app name, package name, and bundle identifier for the selected app variant:

在动态应用配置中使用非前缀变量。如果需要在本地解析配置，请保持可见性至少为 sensitive（在 EAS CLI 中，明文和敏感信息可读取；秘密信息保留在服务器上）。

🌐 Use non-prefixed variables in dynamic app config. Keep visibility at least sensitive if you need to resolve config locally (plain text and sensitive are readable in EAS CLI; secrets stay on the server).

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

秘密和文件变量

🌐 Secrets and file variables

环境变量例如 GOOGLE_SERVICES_JSON 是一个密钥文件变量，外部无法读取 EAS 服务器，并用于向 EAS 构建任务提供被 git 忽略的 google-services.json 文件。要在应用配置中使用它，可以使用 process.env 变量，并在变量未设置时提供一个备用值（用于本地开发时，通常你会将其放在项目的仓库中）：

🌐 Environment variables such as GOOGLE_SERVICES_JSON is a secret file variable that is not readable outside of EAS servers and is used to provide the git ignored google-services.json file to an EAS 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 {
  android: {
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json',
  },
};

管理环境变量

🌐 Manage environment variables

你可以在你的项目或账户中使用 EAS 控制面板 来创建、更新和删除环境变量。

🌐 You can use EAS dashboard in your project or account to create, update, and delete environment variables.

你也可以使用 EAS CLI 来管理它们。以下命令是针对 production 环境提供的示例。在使用这些命令时，请将 production 替换为你想要管理的环境。

🌐 You can also use EAS CLI to manage them. The following commands are provided as examples for production environment. When using these commands, replace production with the environment you want to manage.

信息 提示： 有关上述命令的更多信息，请参见 EAS CLI 命令参考。

拉取本地开发用的变量

🌐 Pull variables for local development

在本地开发中使用 EAS 环境变量的高效方法是使用 eas env:pull --environment environment-name 命令将它们导入到 .env 文件中：

🌐 The efficient way to use EAS environment variables for local development is to pull them into a .env file using the eas env:pull --environment environment-name command:

例如，要将 production 环境的环境变量导入到 .env 文件中，你可以运行：

🌐 For example, to pull the environment variables for the production environment into a .env file, you can run:

创建的文件可能如下所示：

🌐 The created file may look like the following:

# Environment: production

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

信息 提示： 将生成的 .env 文件保存在 .gitignore 中，以避免本地和云端任务之间的泄露和优先级冲突。

你也可以使用 EAS 仪表板上的 导出 选项来下载文件并将其存储在你的项目中。

🌐 You can also use the Export option in the EAS dashboard to download the file and store it inside your project.

自定义环境

🌐 Custom environments

重要 创建自定义环境适用于企业和生产计划。

三个默认环境已经足以满足大多数使用场景，但如果你的项目依赖复杂的工作流程并且需要更灵活地创建更多环境，使用自定义环境可能会很有用。

🌐 The three default environments are sufficient for most use-cases, but if you project relies on complex workflows and requires the flexibility to create more environments, using custom environments may come in handy.

在 EAS 仪表板中创建自定义环境

🌐 Create a custom environment in EAS dashboard

在 EAS 仪表板中创建自定义环境：

🌐 To create a custom environment in EAS dashboard:

• 在你的项目中，导航到 项目设置 > 环境变量，然后点击 添加变量 按钮。
• 在 环境 下，点击 加号 (+) 图标 输入自定义环境的名称。

• 创建环境后，它将会在 自定义环境 部分被预先选中。
• 只要至少有一个环境变量与此环境相关联，它将在该账户或项目的所有环境变量中显示为可选择的选项。

使用 EAS CLI 创建自定义环境

🌐 Create a custom environment with EAS CLI

要将环境变量分配给自定义环境，请将环境的名称替换为你的自定义环境名称。例如，下面的命令创建一个新变量 EXPO_PUBLIC_API_URL 并将其分配给自定义 staging 环境：

🌐 To assign an environment variable to a custom environments, use your custom environment name in place of the environment. For example, the command below creates a new variable EXPO_PUBLIC_API_URL and assigns it to the custom staging environment: