Nginx原生不支持$VAR环境变量语法，nginx -t报错因配置加载阶段不解析shell变量；正确方式是用env声明+map映射，或用envsubst生成静态配置再include。
在 Nginx 配置中使用环境变量（如 $ENV_VAR 或通过 env 指令引入）时，nginx -t 往往会报错，提示“unknown directive”或“invalid number”，根本原因在于：Nginx 在配置加载阶段（包括语法检查）不解析 shell 环境变量，也不支持直接写 $VAR 这种形式。它只在运行时由某些模块（如 ngx_http_perl_module、ngx_http_lua_module）或通过 env + map + include 间接支持——而这些机制在 nginx -t 时若未正确定义，就会失败。
确认是否误用了 shell 风格的变量语法
Nginx 原生配置文件不是 shell 脚本，$MY_PORT 或 ${DB_HOST} 这类写法直接报错且无法通过 -t。Nginx 只识别内置变量（如 $host、$request_uri）和 map 定义的变量。
- ❌ 错误示例（
nginx.conf中直接写）：
listen $PORT; 或 proxy_pass http://$BACKEND; - ✅ 正确思路：用
map将环境变量映射为 Nginx 变量，且确保该map块在http块内、早于引用位置
检查 env 和 map 是否配合正确
要让环境变量在 Nginx 中可用，需两步：先用 env 指令声明（仅限主配置上下文），再用 map 映射为可引用变量。但注意：env 不传递给子进程，也不影响 nginx -t 的变量解析逻辑——map 的 key 是字符串字面量，不是动态读取的环境值。
- 必须在
nginx.conf的顶层（main 上下文）添加：
env MY_BACKEND_HOST; - 在
http块中定义：
map $http_host $backend_host {
default $MY_BACKEND_HOST;
}
⚠️ 注意：$MY_BACKEND_HOST是 Nginx 尝试读取的环境变量名，但nginx -t时它为空 →map默认值生效；若没设default，匹配失败会报错
用 include + 外部生成配置规避 -t 问题
最稳妥、nginx -t 友好的方式是：**不在 Nginx 配置里“读环境变量”，而是用脚本把环境变量渲染成静态配置，再 include 进来**。
- 写一个生成脚本（如
gen-conf.sh），用envsubst替换模板中的${PORT}，输出为/etc/nginx/conf.d/app.conf - 主配置中写：
include /etc/nginx/conf.d/app.conf; - 执行顺序：
生成配置 →nginx -t（此时是纯静态语法）→ reload
调试技巧：快速定位哪一行触发了变量相关错误
nginx -t 报错通常只显示行号和粗略信息，比如：
nginx: [emerg] unknown directive "$MY_PORT" in /etc/nginx/conf.d/site.conf:12
- 打开对应文件第 12 行，看是否写了
$XXX—— 十有八九是误当 shell 用了 - 用
nginx -T（大写 T）输出全部展开后的配置，能帮你发现被include进来的片段里是否混入了未替换的变量占位符 - 临时注释掉疑似区域，再
-t，逐步缩小范围
