EAS Build中使用环境变量和密钥

---

Expo中的环境变量描述了如何使用**.env文件来设置可以在JavaScript代码中内联的环境变量。Expo CLI将在您的代码中适当前缀的变量（例如，process.env.EXPO_PUBLIC_VARNAME）替换为开发机器上.env**文件中的相应环境变量值。

由于您的EAS Build作业在远程服务器上运行，这些**.env文件可能不可用。例如，如果它们列在.gitignore中或未提交到您的本地版本控制系统中，则.env文件将从上传的项目中排除。此外，您可能希望在JavaScript代码之外使用环境变量来自定义构建时的应用二进制文件，例如设置捆绑标识符或错误报告服务的私钥。因此，EAS Build允许您在eas.json**中设置每个构建配置文件的环境变量，以及不应提交到源代码控制的敏感值，通过EAS Secrets。

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

用于应用程序代码

如果您在**.env文件中设置了本地开发变量，如环境变量指南中所述，您可以在eas.json**的构建配置文件中设置相同的变量。例如，当本地开发时，您可能会将API URL变量设置为本地后端服务器，测试时设置为测试服务器，生产构建时设置为生产服务器。

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

EXPO_PUBLIC_API_URL=http://api.local

将所有适用的**.env文件添加到您的.gitignore**（和**.easignore**，如果您的项目有一个）文件中，以便它们不随EAS Build作业一起上传：

# 忽略所有 .env 文件
.env*

然后，您可以在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的引用都将根据环境替换为适用的值。

EXPO_PUBLIC_变量替换在SDK 49及更高版本中可用。

用于您的Expo配置

您可以在动态配置中使用环境变量（app.config.js），以更改应用程序的构建方式。例如，您可能希望更改测试构建的应用程序图标或简称。

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

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

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

module.exports = {
  // 如果定义了变量，则使用它，否则使用回退
  icon: process.env.APP_ICON || './assets/icon.png',
  name: process.env.APP_NAME || 'My App',
};

所有在eas.json构建配置文件中的环境变量在评估app.config.js时都可用。仅在应用程序代码中使用的变量使用EXPO_PUBLIC_前缀是一个好习惯。

用于其他构建步骤

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

您还可以在构建过程中动态设置环境变量。set-env可执行文件在EAS Build工作器的PATH中可用，并且可以用来设置将在下一个构建阶段中可见的环境变量。

例如，您可以在EAS Build钩子中添加以下内容，环境变量EXAMPLE_ENV将在构建作业结束之前可用。

set-env EXAMPLE_ENV "example value"

内置环境变量

以下环境变量对每个构建作业都是公开的，可以在任何构建步骤中使用。它们在本地评估app.config.js时不会设置：

• CI=1 \- 表示这是一个CI环境
• EAS_BUILD=true \- 表示这是一个EAS Build环境
• EAS_BUILD_PLATFORM \- 要么是android要么是ios
• EAS_BUILD_RUNNER \- 要么是eas-build用于EAS Build云构建，要么是local-build-plugin用于本地构建
• EAS_BUILD_ID \- 构建ID，例如f51831f0-ea30-406a-8c5f-f8e1cc57d39c
• EAS_BUILD_PROFILE \- 来自eas.json的构建配置文件名称，例如production
• EAS_BUILD_GIT_COMMIT_HASH \- Git提交的哈希值，例如88f28ab5ea39108ade978de2d0d1adeedf0ece76
• EAS_BUILD_NPM_CACHE_URL \- npm缓存的URL（了解更多）
• EAS_BUILD_MAVEN_CACHE_URL \- Maven缓存的URL（了解更多）
• EAS_BUILD_COCOAPODS_CACHE_URL \- CocoaPods缓存的URL（了解更多）
• EAS_BUILD_USERNAME \- 启动构建的用户的用户名（对于机器人用户未定义）
• EAS_BUILD_WORKINGDIR \- 带有您项目的远程目录路径

在环境变量中使用密钥

为了向您的构建作业提供访问权限，这些权限对于包含在您的源代码和Git仓库中过于敏感的值，您可以使用“密钥”。

一个密钥由名称和值组成。名称只能包含字母数字字符和下划线。值的大小限制为32 KiB。

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

密钥值在静止和传输过程中都是加密的，并且只有在EAS服务器的安全环境中才会解密。

您可以为每个Expo账户创建多达100个账户范围的密钥和每个应用程序100个应用程序特定密钥。账户范围的密钥将暴露在您所有应用程序的所有构建环境中。应用程序特定的密钥仅适用于它们定义的应用程序，并将覆盖任何具有相同名称的账户范围密钥。

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

始终记住，任何包含在客户端代码中的都应被视为公共和可读，任何可以运行应用程序的个人都可以访问。 EAS密钥旨在用于提供值给EAS Build作业，以便在构建过程中使用。 正确使用的例子包括设置NPM_TOKEN以从npm安装私有包，或Sentry API密钥以创建发布并上传您的sourcemaps到他们的服务。 EAS密钥不为您最终嵌入到应用程序本身的值提供任何额外的安全性，例如AWS访问密钥或其他私有密钥。

在Expo网站上的密钥

要创建账户范围的密钥，请导航到账户设置中的密钥标签。

要创建应用程序特定的密钥，请导航到项目仪表板中的密钥标签。

使用EAS CLI添加密钥

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

终端

eas secret:create --scope project --name SECRET_NAME --value secretvalue --type string

✔️ 创建了项目@fiberjw/goodweebs上的新密钥SECRET_NAME。

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

终端

eas secret:list

此账户和项目的密钥：
┌────────────────┬────────┬─────────┬──────────────────────────────────────┬─────────────────┐
│ 名称           │ 类型   │ 范围   │ ID                                   │ 更新时间       │
├────────────────┼────────┼─────────┼──────────────────────────────────────┼─────────────────┤
│ APP_UPLOAD_KEY │ string │ account │ 366bd434-b538-4192-887c-036c0eddedec │ Oct 05 11:51:46 │
├────────────────┼────────┼─────────┼──────────────────────────────────────┼─────────────────┤
│ NPM_TOKEN      │ string │ project │ 03f4881f-88fd-4d94-9e35-a5c34d39c2f2 │ Oct 05 11:51:33 │
├────────────────┼────────┼─────────┼──────────────────────────────────────┼─────────────────┤
│ SECRET_FILE    │ file   │ project │ 72c7ac1e-78d0-4fa2-b105-229260cecc88 │ Oct 05 11:52:12 │
├────────────────┼────────┼─────────┼──────────────────────────────────────┼─────────────────┤
│ sentryApiKey   │ string │ project │ 88dd0296-9119-4d50-a91b-1f646733f569 │ Oct 05 11:51:40 │
└────────────────┴────────┴─────────┴──────────────────────────────────────┴─────────────────┘

从dotenv文件导入密钥

如果您使用**.env**文件在本地存储您的密钥，您可以使用eas secret:push命令将它们全部导入到EAS：

终端

eas secret:push --scope project --env-file ./eas/.env

✔ 在账户johndoe上创建密钥…` `✔ 在账户johndoe上创建了以下密钥：` `- ABC` `- DEF` `- GHI`

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

Doppler集成

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

doppler run --mount ./eas/.env -- eas secret:push --scope project --env-file ./eas/.env

在EAS Build中访问密钥

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

常见问题

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

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

然而，推荐的做法是在本地环境中使用**.env文件，同时在eas.json中为EAS Build定义环境变量。在eas.json构建配置文件中定义的环境变量将在运行eas build时评估您的app.config.js**，并将对EAS Build服务器上的所有构建步骤都可用。

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

在eas.json中定义的环境变量仅在运行EAS Build作业时可用。然而，您可能希望根据构建配置文件更改应用程序代码中使用的变量，同时最小化您可能保留在**.env**文件中的值，用于本地开发或发布到EAS Update。

我们的EAS Update中的环境变量指南描述了在所有这些上下文中共享环境变量的一些方法。

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

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

1. eas.json构建配置文件env字段
2. EAS Secrets中定义的环境变量
3. 提交到源代码控制且不在**.easignore中的.env**文件

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

例如，如果您创建了一个名为MY_TOKEN的密钥，值为secret，并且在您的eas.json中也设置了"env": { "MY_TOKEN": "public" }，那么EAS Build上的process.env.MY_TOKEN将评估为secret。

我的Expo开发客户端构建的环境变量如何工作？

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

我可以只在一个CI提供商上设置我的环境变量吗？

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

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

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

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

1. 将文件上传到EAS。

终端

eas secret:create --scope project --name GOOGLE_SERVICES_JSON --type file --value ./path/to/google-services.json

✔ 在项目@user/myproject上创建了新的密钥GOOGLE_SERVICES_JSON。

2. 使用app.config.js读取google-services.json的路径。

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