Master进程启动时从父shell继承环境变量,Worker进程默认不继承,需在main上下文用env指令显式声明才能供Worker使用。

Master进程在启动时读取并继承操作系统环境变量,但Worker进程默认不继承这些变量。
Master进程如何获取环境变量
当Nginx以命令行方式启动(如 nginx 或 nginx -c /path/to/nginx.conf),Master进程会直接从父shell环境中继承所有已设置的环境变量。这包括通过 export VAR=value 设置的变量,以及系统级环境(如 PATH、USER 等)。
注意:该行为发生在Master进程创建之初,即解析配置文件之前。因此,如果配置中使用了 $ENV_VAR 这类语法(需配合 env 指令),Nginx必须明确“知道”哪些变量需要传递给后续上下文。
Worker进程默认不继承环境变量
出于安全与隔离考虑,Nginx Worker进程在fork+exec启动时会清空大部分环境变量。即使Master读到了某个变量,Worker也不会自动拥有它。
- 除非在配置文件中显式声明 env VAR_NAME;,否则该变量不会出现在Worker进程中
- 未声明的变量(如 HOME、LANG)在Worker里通常为空或被重置
- env 指令必须放在全局块(main context),不能写在 http/server/location 中
让Worker访问特定环境变量的方法
若模块或Lua脚本(如 ngx_lua)需在Worker中读取环境变量,必须提前告知Nginx:
- 在 nginx.conf 的最外层添加:env MY_API_KEY;
- 支持通配符:env LD_*;(传递所有以 LD_ 开头的变量)
- 若要清除所有继承的变量,只保留指定项,可先写 env;(清空默认列表),再逐个 env XXX;
重启Nginx后,Worker进程即可通过 os.getenv("MY_API_KEY")(Lua)或 getenv("MY_API_KEY")(C模块)安全读取。
调试环境变量是否生效
验证变量是否成功注入Worker:
- 用 ps auxf | grep nginx 查看Master进程的环境(较难直接看到)
- 更可靠的方式:在init_by_lua_block或log_by_lua_block中打印 os.getenv("VAR") 并查error.log
- 检查Nginx启动时是否报错:[emerg] unknown directive "env" 表示指令位置错误(不在main context)