环境变量

环境变量能让您将变量添加到在环境中运行的应用程序进程中，而无需更改代码。环境变量被安全存储，使其非常适合以下用例：

第三方集成的 API 密钥
应用程序逻辑的功能标志
不同环境的配置或可能不是密码的配置

环境变量只能在应用服务器中访问。它们无法修改边缘服务的行为，包括代理和边缘函数。

Note

前提条件

您必须在要为其管理环境变量的项目上具有开发人员或管理员角色。如果您没有访问权限，请具有 Managed Runtime 管理员角色的人员为您提供帮助。

教程

按照这些教程设置环境变量，然后在 PWA Kit 站点中实现代码以使用这些变量。您可以根据具体要求自定义代码。这些教程演示如何：

建议在本地计算机上测试这些步骤，然后在非生产环境中测试这些步骤，然后再将更改部署到生产环境。有关更多指导，请参阅最佳实践、环境变量疑难解答和在本地调试。

管理环境变量

环境变量：

可以使用 Managed Runtime API 或 Runtime Admin 进行管理
在 Node.js 中使用 process.env 访问

引入新的环境变量时，首先要通过 API 或 Runtime Admin 进行设置。等到重新部署完成，然后部署使用它的新捆绑包。

使用 Managed Runtime API

设置、更新和取消设置环境变量

使用 projects_target_env_var_partial_update：

1curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \
2  --request 'PATCH' \
3  --header 'Content-Type: application/json' \
4  --header 'Accept: application/json' \
5  --header "Authorization: Bearer $MOBIFY_API_KEY" \
6  --data '{
7    "API_KEY": {"value": "b3Blbi1zZXNhbWU="},
8    "STOREFRONT_CONFIG": {"value": "{\"showBuyNowButton\": false}"},
9    "SLAS_CLIENT_ID": {"value": "da422690-7800-41d1-8ee4-3ce983961078"}
10}'

要取消设置现有环境变量，请将其值设置为 null。

修改环境变量会重新部署环境。部署完成后，更新的值可用。

获取所有环境变量

使用 projects_target_env_var_list：

1curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \
2  --header "Authorization: Bearer $MOBIFY_API_KEY" \
3  --header 'Accept: application/json'

使用 Runtime Admin

要创建、更新、删除或查看环境变量，请执行以下操作：

登录到 Runtime Admin。要访问 Runtime Admin，请参阅 Managed Runtime 管理。
转到项目的“概述”页面。
单击要为其管理环境变量的环境名称。
单击左侧导航栏中的**“环境变量”**。

最佳实践

选择对您的应用程序有意义的环境变量名称。使用描述性名称：为环境变量选择简洁明了的名称，以便团队易于理解。
避免在代码中对敏感信息（如 API 密钥）进行硬编码。使用环境变量来确保其安全。
不要将环境变量传递到将序列化到页面的数据中。请考虑添加一个测试，以确保您不会泄露环境变量数据。
不要从 getProps 或 react-query Hook 返回环境变量。
仅在服务器端使用环境变量。默认情况下，环境变量不会在客户端公开。可以选择在客户端公开它们（例如，在配置文件中），但请确保公开这些值符合安全实践。
在本地计算机上测试环境变量，然后在非生产环境中测试环境变量，然后再将其部署到生产环境。这有助于确保可以在本地快速解决问题，然后在部署到生产环境之前模拟站点行为、验证功能并执行任何用户验收测试。
在使用环境变量的代码中包括错误处理，以防止由于未定义的环境变量而导致故障。
控制对环境变量的访问，以防止未经授权的修改。
记录每个环境变量的用途和配置。这有助于新开发人员入职和解决问题。

限制条件

环境变量的使用受到以下约束条件限制：

每个环境的环境变量限制为 100 个。
环境变量名称只能包含字母数字字符、下划线（ _ ）和短划线（ - ）。
环境变量名称不得超过 512 个字符，并且不能以如下保留前缀开头：AWS、MRT、X_MRT、MOBIFY、X_MOBIFY、SSR_PROXY、NODE。
环境变量名不能使用任何保留名：BUNDLE_ID、DEPLOY_ID、DEPLOY_TARGET、EXTERNAL_DOMAIN_NAME、HANDLER、LAMBDA_RUNTIME_DIR、LAMBDA_TASK_ROOT、NODE_ENV、REDIRECT_BUCKET、REDIRECT_KEY、REDIRECT_UPDATE、REMOTE、X_AMZN_TRACE_ID
环境变量值必须是字符串。要存储复杂值，请将 JSON 编码为字符串。
为环境设置的环境变量值的最大大小为 32 KB。

环境变量疑难解答

本节针对使用环境变量时可能遇到的常见错误提供建议的解决方案。

未设置环境变量

您的代码会抛出一个 Error 说明，指出缺少变量。

**原因：**未设置代码调用的环境变量。

**建议的解决方案：**调用 projects_target_env_var_partial_update API 端点以设置适用的环境变量。

环境变量名称不正确

您的代码会记录一条错误消息，指出找不到环境变量。

**原因：**代码找不到环境变量，因为代码中有拼写错误或使用了不正确的环境变量名称。

**建议的解决方案：**确认您在代码中正确拼写了环境变量名称，并且使用了所需的环境变量名称。通过调用 projects_target_env_var_list API 端点检查环境变量名称，以查看设置的变量的完整列表。

不支持的环境变量名称

用于设置环境变量的 API 调用失败。

**原因：**环境变量名称可能不符合约束条件。例如，环境变量值的大小超过 32 KB。

**建议的解决方案：**确认您的环境变量符合约束条件。

无效的 API 密钥格式

执行涉及使用 API 密钥的代码时，会发生身份验证错误。

**原因：**设置环境变量时使用的 API 密钥不是预期的格式或缺少 API 密钥。

**建议的解决方案：**确认环境变量存储的 API 密钥正确无误。如果需要，请调用 projects_target_env_var_partial_update API 端点以更正 API 密钥。

API 端点的 URL 无效

fetch 请求失败，并显示网络错误。

**原因：**代码中调用的任何 API 端点的 URL 可能未正确定义或无效。例如，内容管理系统 (CMS) 端点的 URL 不正确。

**建议的解决方案：**确认代码中 API 端点的任何 URL 都正确无误。