如何利用 env 指令在 Nginx 配置中引用系统环境变量-Nginx-PHP中文网

nginx 的 env 指令仅用于传递环境变量给 worker 进程，不支持配置中直接引用如 $api_url；可用 $env{var}（日志/响应头）、envsubst 模板替换或 lua 动态读取实现变量使用。

如何利用 env 指令在 nginx 配置中引用系统环境变量

Nginx 的 env 指令不能用来在配置中“引用”或“展开”环境变量值，它只控制 worker 进程是否继承某个系统环境变量。你无法写 proxy_pass http://$API_URL; 或 root /var/www/$ENV_NAME; 让 Nginx 自动替换——这种写法会报错或被当作字面量处理。

真正能用上系统环境变量，得靠明确区分两个层面：传递（让 worker 进程拿到变量）和使用（在配置里读取并生效）。下面分三类讲清楚怎么做、为什么这么设计、以及常见踩坑点。

`env` 指令只做“传递”，不提供“引用语法”

env 必须写在 nginx.conf 最外层（main 上下文），比如：
```
env APP_ENV;
env API_HOST;
# env LD_*;  # 支持通配符
```
它的作用是告诉 Nginx：启动 worker 进程时，请把启动时 Master 进程已有的 APP_ENV 和 API_HOST 值一并传过去。
它不会让你在 server 或 location 块里写 $APP_ENV ——Nginx 配置语言本身不支持这种变量插值。
如果你写了 set $stage $APP_ENV;，Nginx 会直接报错：“unknown variable”。

能安全“使用”环境变量的三种方式

日志和响应头中用 $ENV{VAR}（Nginx ≥1.19.0）
这是唯一原生支持的引用方式，仅限于 log_format、add_header、return 等少数指令：
```
log_format main '$remote_addr - "$request" status=$status env=$ENV{APP_ENV}';
server {
    location /health {
        add_header X-App-Env $ENV{APP_ENV};
        return 200 "OK (env: $ENV{APP_ENV})\n";
    }
}
```
⚠️ 注意：不能用于 proxy_pass、root、include 等需要路径/地址解析的指令。
启动前用 envsubst 替换模板配置（推荐，最通用）
把 nginx.conf.template 里的 ${API_HOST} 替换成真实值，再启动 Nginx：
```
envsubst  /etc/nginx/nginx.conf
nginx -g "daemon off;"
```
配置模板示例：

Nginx Hosting
通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载
```
upstream api { server ${API_HOST}:8000; }
location /api/ {
    proxy_pass http://${API_HOST}:8000/;
}
```
用 Lua 动态读取（需启用 ngx_http_lua_module）
在配置中嵌入 Lua 逻辑，调用 os.getenv()：
```
set_by_lua_block $api_host {
    return os.getenv("API_HOST") or "localhost"
};
proxy_pass http://$api_host:8000;
```
需提前安装 lua-resty-env 或确保基础 Lua 支持。

容器与 systemd 环境下特别注意

Docker 中用 -e API_HOST=xxx 启动容器，Nginx 不会自动获得该变量，除非：
- nginx.conf 顶层有 env API_HOST;
- 且该变量在容器启动时已存在于 shell 环境中（Docker 的 -e 确保这点）
systemd 启动 Nginx 时，必须在 service 文件里显式声明：
```
[Service]
Environment="API_HOST=api.example.com"
EnvironmentFile=-/etc/nginx/env.conf
```
然后 nginx.conf 中仍要写 env API_HOST; 才能让 worker 继承。