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

了解如何使用 EAS 仪表板和 EAS CLI 创建、作用域化和使用环境变量。

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

以下章节介绍如何使用 EAS 仪表盘和 EAS CLI 创建、作用域以及消费环境变量。

创建环境变量

• 选择一个环境或多个环境：默认可用 development、preview 和 production。一个变量可以在这些环境之间复用，也可以按环境定制。
• 选择作用域：项目级变量适用于单个项目。账户级变量可以在多个项目之间复用，并且会在构建时与项目变量合并。
• 选择可见性：对绝不应离开 EAS 服务器的值使用 secret，对可能在本地被显示的值使用 sensitive，对非敏感值使用 plain text。

在仪表盘中创建变量

要在 EAS 服务器上创建新的环境变量，你可以在项目仪表盘中导航到 Project settings > Environment variables，然后点击 Add Variables 按钮。

使用 environment variables creation form 页面来设置名称、值、环境、可见性以及可选描述。

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

在上面的示例列表中：

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

使用 EAS CLI 创建变量

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

在代码中使用环境变量

客户端值

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

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。

不要把密钥放进 EXPO_PUBLIC_ 变量中。客户端包中的所有内容最终都可被终端用户读取。

构建时和应用配置

其他不带 EXPO_PUBLIC_ 前缀的变量可以在 app config 解析期间使用，以配置应用行为。例如，APP_VARIANT 变量用于确定所选 app variant 的应用名称、包名和 bundle 标识符：

在动态 app config 中使用非前缀变量。如果你需要在本地解析配置，可见性至少保持为 sensitive（plain text 和 sensitive 可通过 EAS CLI 读取；secrets 会保留在服务器上）。

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（开发）';
  }

  if (IS_PREVIEW) {
    return 'StickerSmash（预览）';
  }

  return 'StickerSmash：Emoji 贴纸';
};

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 这样的环境变量是一个 secret 文件变量，无法在 EAS 服务器之外读取，用于向 EAS Build 任务提供被 git 忽略的 google-services.json 文件。要在 app config 中使用它，你可以使用 process.env 变量，并在变量未设置时提供一个回退值（用于本地开发时，通常它位于项目仓库中）：

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

管理环境变量

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

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

提示： 查看 EAS CLI 命令参考 以获取有关上述命令的更多信息。

为本地开发拉取变量

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

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

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

# 环境：production

APP_VARIANT=development
EXPO_PUBLIC_API_URL=https://staging.my-api-url.mycompany.com
# GOOGLE_SERVICES_JSON=*****（secret 变量不可读取）
SENTRY_AUTH_TOKEN=token

提示： 请将生成的 .env 文件保留在 .gitignore 中，以避免泄漏以及本地与云端任务之间的优先级冲突。

你也可以在 EAS 仪表盘中使用 Export 选项下载文件，并将其存储到你的项目中。

自定义环境

创建自定义环境适用于 Enterprise 和 production 套餐。

这三个默认环境对于大多数用例已经足够，但如果你的项目依赖复杂工作流，并且需要创建更多环境的灵活性，那么使用自定义环境可能会很有用。

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

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

• 在你的项目中，导航到 Project settings > Environment variables，然后点击 Add Variables 按钮。
• 在 Environments 下，点击 plus (+) icon 以输入自定义环境的名称。

• 创建环境后，它会在 Custom environments 部分下预先选中。
• 只要至少有一个环境变量关联到这个环境，它就会作为该账户或项目下所有环境变量的可选项显示出来。

使用 EAS CLI 创建自定义环境

要将环境变量分配给自定义环境，请在环境位置使用你的自定义环境名称。例如，下面的命令会创建一个新的变量 EXPO_PUBLIC_API_URL，并将其分配到自定义的 staging 环境：