最常见原因是环境变量未export——envsubst只读取已导出变量，VAR=value这种shell变量不可见；需用env | grep VAR确认导出，且建议前置校验[[ -z "$PORT" ]]避免空替换导致配置崩溃。
envsubst 为什么没替换出变量值？
最常见原因是环境变量没 export —— envsubst 只读取已导出的变量，VAR=value 这种 shell 变量它完全看不见。
检查方式很简单：env | grep VAR 能看到才说明导出了；如果只用 echo $VAR 看到值，但 env 里没有，那 envsubst 就不会替换。
- ✅ 正确：先
export PORT=8080 DOMAIN=prod.example.com，再跑envsubst - ❌ 错误：直接写
PORT=8080; envsubst ，PORT 不会被识别 - ⚠️ 注意：在 CI/CD 脚本中，有些平台（如 GitLab CI）默认不继承父 shell 的 export 状态，得显式
export或用env命令传入
怎么安全替换 Nginx 配置里的 $host 这类内置变量？
原生 envsubst 会把 $host、$remote_addr 这类 Nginx 内置变量也当环境变量去替换，结果变成空字符串，导致配置语法错误。
根本解法不是硬转义（比如写成 \$host），而是控制替换范围：
- 用白名单模式，只列你真要替换的变量：
envsubst '$PORT $DOMAIN $BACKEND' nginx.conf - 模板里统一用
${VAR}写法，避免和 Nginx 变量冲突（$host≠${host}） - 更稳妥的做法是换用
envsubst2工具（非 GNU 自带），它默认只匹配${...}格式，$host完全不动
未定义变量被替成空字符串，怎么避免配置崩掉？
envsubst 默认行为是“有就换，没有就删”，这对 listen ${PORT} 这种关键字段很危险——PORT 没设，结果变成 listen ;，Nginx 直接启动失败。
必须在调用前做校验，不能依赖 envsubst 自己报错：
- 加前置检查：
[[ -z "$PORT" ]] && echo "ERROR: PORT not set" >&2 && exit 1 - CI/CD 中建议用
set -u+export组合，让缺失变量直接中断脚本 - 若想保留未定义占位符（如
${MISSING_VAR}原样输出），原生envsubst做不到，得切到envsubst2 --force-replace=false或改用sed+printf手动处理
CI/CD 流水线里怎么写才不容易翻车？
自动化场景下，别拼超长命令，也别把变量列表硬编码在 envsubst 参数里——每次加个新变量都得改脚本，易漏易错。
推荐这个组合写法：
- 用
env动态生成白名单：envsubst "$(env | cut -d= -f1 | sed 's/^/\$/; s/$/ /' | tr '\n' ' ')" config.yml - 更清晰的做法：把要替换的变量名写进一个文件（如
required_vars.txt），然后envsubst "$(cat required_vars.txt | xargs -I{} echo \${})" config.yml - 容器内启动时，用
env前缀注入变量再执行：env PORT=8080 DOMAIN=staging envsubst /etc/nginx/conf.d/default.conf
真正容易被忽略的是：不同 shell（bash/zsh/sh）对引号和空格的解析差异，以及 sudo、docker run --user 这类操作会清空或过滤环境变量——这些地方一漏，envsubst 就静默失效。
