环境变量转换实战:在 .env、export、JSON 与 docker-compose 间互转

同一组环境变量,在不同环节长得完全不一样。本地开发是一个 .env 文件,CI 流水线要逐行 export,部署脚本想要 JSON 对象,docker-compose 又要缩进成 environment: 块。每次手工搬运,漏一个键、错一个引号,服务就在半夜启动失败。这篇讲的是怎么把这件事变成一次粘贴、一次切换格式的操作。

为什么 KEY=VALUE 要在四种格式间转

环境变量的核心结构其实只有一行:KEY=VALUE。但承载它的语法各不相同。

• .env 文件:纯文本,一行一个,不需要引号,适合本地。
• shell export:每行前面要加 export,值里有空格要补引号。
• JSON 对象:键值都是字符串,用于配置中心、Serverless 平台或者程序读取。
• docker-compose:挂在 environment: 下,带两层缩进。

这四种之间的转换没有难度,只有重复劳动。十几个变量手工改还行,几十上百个就开始出错。环境变量列表转换器把这一步做成确定性操作:粘进来一份,选输出格式,拿走结果。

一个真实的转换例子

假设本地 .env 是这样:

DATABASE_URL=postgres://localhost:5432/app
REDIS_URL=redis://localhost:6379
LOG_LEVEL=debug
FEATURE_FLAGS=beta,canary

要把它交给一段 CI 脚本,需要的是 shell export 形式:

export DATABASE_URL="postgres://localhost:5432/app"
export REDIS_URL="redis://localhost:6379"
export LOG_LEVEL="debug"
export FEATURE_FLAGS="beta,canary"

如果对接的是一个只吃 JSON 的配置接口,同一份变量又变成:

{
  "DATABASE_URL": "postgres://localhost:5432/app",
  "REDIS_URL": "redis://localhost:6379",
  "LOG_LEVEL": "debug",
  "FEATURE_FLAGS": "beta,canary"
}

底层的键和值一个没动,只是排版换了。FEATURE_FLAGS 里的逗号在 JSON 里被正确包进字符串,在 export 里被引号保护,不会被 shell 拆成两个参数。这正是手工改最容易翻车的地方。

本地开发到 CI 的配置迁移

迁移配置时,最痛的不是格式不同,而是看不出哪一行不合法。环境变量列表转换器有一个保留无效项的开关:像单独一个 DEBUG 缺了 =、键里混进了非法标点、或者值跨了行又没加引号,这些条目不会被默默吃掉,而是带着原因留在输出里。迁移前先扫一遍,比上线后看 CI 报红再回头查省事得多。

去重和排序也很关键。多份导出拼到一起常有重复键,后一个会悄悄覆盖前一个。先用 /zh/t/env-var-deduplicator/ 这类去重能力把唯一值留下,再统一排序,交接出去的就是一份干净、可复核的清单,而不是一团需要对方再整理的文本。

含密钥时为什么本地处理很重要

我自己最在意的一点是:环境变量里几乎一定有 token、数据库密码、API key。把这些东西粘到一个会上传到服务器的在线工具里,等于把密钥发给了不认识的第三方。这个转换器的解析、校验、去重、导出全部在浏览器当前标签页里跑,上传的本地文件也是用 File API 在本地读,不发去任何服务器。处理完关掉标签页,内容不留痕。银行卡号、JWT 这类敏感值还会在输出里脱敏,同时保留必要的校验信号。

需要专门把变量从一大段日志或网页文本里抠出来时,可以配合 /zh/t/env-var-extractor/,保留行号和原因,方便回到原文排查。整套流程的入口在 /zh/t/env-var-list-converter/。

把它接进日常工作流

这个工具不是用来一次性炫技,而是嵌进真实环节:本地调通后导出 export 给 CI,迁移平台时转成 JSON,起容器前生成 docker-compose 的 environment: 块。每一步都是粘贴加切换格式,既不手敲引号,也不漏逗号。配置这件事,少出一次错,就少一次半夜被叫起来。

---

Made by Toolora · Updated 2026-06-13