规模化管理 Vercel 环境变量

现在是凌晨两点，你的结账流程正在报错。每一次对 Stripe 的调用都会抛出认证错误，尽管代码没有任何改动。最近的一次改动是一次常规的凭证轮换：有人重新生成了 Stripe 密钥并停用了旧密钥。

也许他们忘了更新 Vercel 中的环境变量。也许他们确实更新了，但更新落到了错误的环境中，或者没有触发重新部署。无论如何，生产环境一直在运行一个 Stripe 密钥无效的部署，没有人能付钱给你。

如果你只是一个人管理少数几个变量的简单项目，Vercel 的环境变量用起来很容易。但随着规模扩大，事情就变得棘手：环境变量的更改不会应用到已有部署，只会在下一次部署时生效。一次密钥轮换需要一次全新的部署才能生效，并且确保不破坏任何东西。如果你还要处理多个（子）域名、并行部署等情况，这只会变得更加复杂。

这个例子只是更大问题的一种表现。需要重新部署才能同步新凭证，这是 Vercel 的一个怪癖，记住这一点就好。问题在于，让环境变量保持同步是一种手动工作流，最终会变成一项没完没了的苦差事。

这不是 Vercel 的错。任何成长中的组织或项目，最终都会在跨工具、跨环境保持机密同步这件事上遇到困难。

Vercel 环境变量做得好的地方

Vercel 的内置环境变量处理在其设计目标范围内做得很好：

• 值在静态存储时经过加密。
• 共享环境变量让你可以在团队级别定义一次变量，然后链接到多个项目，避免重复工作。
• 将变量标记为 Sensitive 后，其值在创建后便无法读取。一旦设置完成，连 Vercel 自己的 API 都无法返回该值。
• 所有套餐都可以通过活动日志追踪团队范围内的变更。

如果 Vercel 是你唯一使用的工具，这确实是一种很好的环境变量管理方式。但大多数组织会使用几十甚至上百个工具，机密管理很快就会变成一团乱麻。

规模化后 Vercel 机密的失效之处

随着机密数量、工具数量和公司人员规模的增长，你最终会发现 Vercel 环境变量开始因为以下几个原因让人头疼。

共享变量是一个扁平列表

共享环境变量解决了变量重复的问题，却没有解决组织管理的问题。没有文件夹结构，也没有办法按服务或域名对变量分组。它们就只是一个可搜索、可筛选的列表。

Vercel 自己的文档也指出了这一点：共享环境变量不支持按分支设置不同的值。如果你在十几个项目中有 40 个变量，你肯定不想靠搜索去回忆哪个 DATABASE_URL 对应哪个服务。

本地开发发生漂移

运行 vercel dev 会自动将 Development 环境变量拉取到内存中。其他方式，如 next dev、npm run dev 或自定义脚本，则需要手动执行 vercel env pull 才能保持同步。

如果队友更改了一个值，你本地的 .env 文件就会在不知不觉中过期。如果某个功能突然坏了，你花 20 分钟调试应用代码后才发现真正的问题是一次密钥轮换，这就非常令人沮丧了。

审计追踪是分散的

Vercel 提供了活动日志，它记录了变更的内容、时间和操作者。但活动日志不提供环境变量的详细变更记录：之前的值是什么、之后变成了什么，等等。

更详细的日志（通过 CSV 导出的真正 diff）以及将日志流式传输到 Datadog 或 Splunk 的功能，都只存在于企业版的审计日志中。对大多数团队来说，当一次生产事故被追溯到某个环境变量时，要确切还原当时改了什么，只能在 Slack 里四处打听，而不是去查询记录。

自管理机密的轮换无法自动化

Vercel 支持密钥轮换（定期更换机密），但仅限于由 Marketplace 集成（例如控制自身凭证生命周期的托管数据库附加组件）所拥有的变量。

如果你在其他地方也用到了这些变量，它们同样不会同步回那些工具，这让你再次陷入手动工作流。

对于由你自己管理的所有机密，则没有自动化的轮换路径。大多数组织最终只能依靠周期性的日历提醒或 Slack 消息来催促某人轮换凭证，而这些提醒往往会被遗忘。

蔓延问题

机密管理不是孤立发生的。举个例子，如果你的应用从 GitHub 部署，你可能也在 GitHub Actions 中存放着同样的机密，比如用于在 CI 中运行迁移的 DATABASE_URL，或者用于集成测试的 API Key。

每一份机密副本都会被独立管理和更新。每一个存放明文凭证的地方，都意味着它可能过期并破坏某些东西，或者被粘贴到某个可能泄露的角落——比如调试日志、聊天消息，或一个被误提交的配置文件。

所有这些问题都无法在 Vercel 中解决。这并不是因为 Vercel 是个糟糕的工具，而是因为它本质上是面向构建者的基础设施，而不是像 Infisical 那样的机密管理工具。

使用 Infisical 集中管理

Vercel 环境变量的核心问题在于，机密分散在不同的地方，由此产生了一个个故障点，轻则带来不必要的手动工作，重则导致泄露和宕机。

Infisical 是一个开源的机密管理平台。机密集中存放在一个地方，按项目和环境组织，Infisical 会把它们推送到真正需要的地方，包括 Vercel。这使得 Vercel 成为众多机密消费者之一，而不是机密存储和管理的地方。在 Infisical 中更改一次值，所有连接的目标位置都会自动获得更新。

设置同步

首先在 Infisical 的仪表盘中创建一个项目。Infisical 会为你设置三个默认环境：Development、Staging 和 Production，它们可以清晰地映射到 Vercel 的 Development、Preview 和 Production。

将你的机密添加到每个环境中，可以手动添加，也可以导入现有的 .env 文件自动填充。如果你使用的是不支持 Vercel 的机密管理器（例如 AWS Secrets Manager、Azure Key Vault 或 Google Secret Manager），你可以自动同步你的机密。

接下来，连接这两个平台：

1. 在 Vercel 中，从 Account Settings > API Tokens 生成一个 API Token。

   

2. 在 Infisical 中，进入 Organization Settings > App Connections，添加一个新的 Vercel 连接，并粘贴该 Token。

这是一次性的握手。此后，你组织中的每个 Secret Sync 都可以复用同一个连接。

连接就绪后，从 Infisical 项目的 Integrations > Secret Syncs 标签页创建一个 Vercel Secret Sync。首先，设置来源（从哪个 Infisical 环境和文件夹路径拉取）和目标（推送到哪个 Vercel 项目和环境）。

有一个值得停下来关注的设置是 Initial Sync Behavior，它决定了 Vercel 中已有机密的处理方式。

对于将现有机密迁移到 Infisical 的团队来说，Import Secrets, Prioritize Infisical 是最安全的默认选项：它会拉取 Vercel 中已有的内容，发生冲突时以 Infisical 的值为准，这样在迁移过程中不会丢失任何东西。确保 Auto-Sync 已启用，否则每次更改仍然需要手动触发，这就失去了意义。

有一点值得了解：如果你在 Vercel 中有标记为 Sensitive 的变量，Infisical 无法读取它们的值，因为 Vercel 的 API 不会返回这些值。你需要手动把这些值添加到 Infisical 中。之后，Infisical 会像管理其他变量一样管理它们。

为你需要的每个环境重复同步设置。一个常见的映射是：

• Infisical Development → Vercel Development
• Infisical Staging → Vercel Preview
• Infisical Production → Vercel Production

当然，你可以按任何你想要的方式进行映射。完成这个初始设置后，你就把机密管理集中到了 Infisical 中，它解决了规模化组织在 Vercel 中管理机密所面临的所有挑战。

看它如何运作

同步开始运行后，你在 Infisical 中拥有的任何机密，Vercel 都会自动获得。这解决了成长中的团队在机密管理上面临的问题，因为你可以在一个地方更新或创建机密，然后让它出现在所有地方。如果某个 GitHub Action、CI 工具或任何其他东西需要同一个机密，Infisical 会把这个机密提供给所有这些工具，包括本地开发者。

密钥轮换就是一个很好的例子。你不再需要先让旧 Stripe 密钥失效、生成一个新密钥，再手动把新密钥复制粘贴到每一个工具中——Infisical 会将整个流程自动化。

在 Infisical 的 Production 环境中更改 STRIPE_SECRET_KEY：

Infisical > Production > STRIPE_SECRET_KEY
Updated: sk_live_NEW_VALUE_abc

切换到 Vercel 的项目设置，同一个变量已经携带了新值，无需手动编辑，也无需复制粘贴：

Vercel > Project > Environment Variables > STRIPE_SECRET_KEY
Value: sk_live_NEW_VALUE_abc (matches Infisical)

Infisical > Integrations > Secret Syncs
Status: Succeeded

整个过程中唯一的手动步骤，就是在一个地方一次性更新这个值。

本地开发不再漂移

还记得之前的问题吗：vercel dev 会自动拉取 Development 变量，但 next dev、npm run dev 和自定义脚本不会，所以本地的 .env 文件会悄悄过期，直到某个环节出问题。把 vercel env pull 换成 Infisical CLI，就能彻底把这个文件从整个流程中移除：

$ infisical run -- npm run dev

infisical run 会包装你的开发命令，在你启动它的那一刻从 Infisical 获取机密，然后将它们直接注入到进程中。磁盘上不再有 .env 文件，因此它既不会过期，也不会被不小心提交到 Git。

如果有人轮换了 STRIPE_SECRET_KEY，任何运行 npm run dev 的人或机器都会自动获得新值，包括 Vercel、开发者和任何其他工具。

单一事实来源

让我们重新看看最初的情景：一个被轮换的密钥出于某种原因没有同步到 Vercel，导致了宕机，而人们要花很长时间才能把问题追溯到过期的环境变量上。这种故障模式之所以存在，是因为总得有人记得机密的每一个存放位置、去更新它，并在之后重新部署。

在 Infisical 中集中管理机密，意味着你只需更改一次值，它就能到达 Vercel 以及任何其他需要该机密的地方。

Vercel 只是众多目标之一。Infisical 支持 50 种机密同步集成，覆盖云提供商、数据库、CI/CD 和托管平台，包括 GitHub Actions、Kubernetes、Terraform 和 AWS Parameter Store。因此，这套用于解决 Vercel 环境变量蔓延问题的方案，也能扩展到技术栈的其余部分。如果你的本地开发环境仍然依赖 .env 文件，那么不妨把这套方案与 Infisical 的 CLI 结合起来，在本地实现机密注入。

完整的视频演示（包括实时同步 demo）请观看本指南的视频版本，它会一步步带你走完相同的设置过程。

• 原文链接： infisical.com/blog/verce...
• 鸿途知科网 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～