Nginx容器启动失败 配置嵌入变量为空导致参数缺失报错

在Nginx配置中使用proxy_set_header指令添加请求头后，Nginx容器启动失败抛出配置错误。进入容器检查实际加载的Nginx配置，发现配置中引用的嵌入变量未被解析、显示为空值，Nginx判定对应指令缺少必填参数，从而触发启动错误。

配置中使用的${DOMAIN_NAME_CLIENT}、${PRIVATE_IP_CLIENT}是Shell风格的环境变量占位符，原生Nginx不支持直接在配置中读取、解析系统环境变量。容器启动加载Nginx配置时，这些占位符没有被提前替换为实际有效值，直接被解析为空字符串，导致server_name、proxy_pass等强制要求传入参数的指令缺失必填值，触发配置校验失败，容器无法正常启动。

方案1：使用官方Nginx镜像内置的模板替换能力（推荐） #

官方Nginx容器镜像默认自带环境变量模板替换逻辑，无需额外安装工具：

• 将现有nginx.conf文件重命名为nginx.conf.template
• 通过挂载卷或者构建镜像的方式，将该模板文件放置到容器内/etc/nginx/templates/目录下
• 启动容器时正常传入DOMAIN_NAME_CLIENT、PRIVATE_IP_CLIENT两个环境变量即可，容器启动阶段会自动将模板中的占位符替换为环境变量实际值，生成最终生效的Nginx配置

启动示例：

docker run -d \
  -e DOMAIN_NAME_CLIENT=实际绑定域名 \
  -e PRIVATE_IP_CLIENT=后端服务内网IP \
  -v /本地存储路径/nginx.conf.template:/etc/nginx/templates/nginx.conf.template:ro \
  -p 80:80 \
  nginx:稳定版本号

方案2：启动阶段手动执行变量替换 #

如果不需要用官方模板机制，可以在容器启动入口手动调用envsubst完成替换后再启动Nginx，自定义启动脚本参考：

#!/bin/sh
# 注意必须显式指定要替换的变量列表，禁止无参数调用envsubst，否则会误替换Nginx内置的$remote_addr、$status等变量
envsubst '${DOMAIN_NAME_CLIENT} ${PRIVATE_IP_CLIENT}' < /etc/nginx/nginx.conf > /tmp/nginx_rendered.conf
cp /tmp/nginx_rendered.conf /etc/nginx/nginx.conf
exec nginx -g 'daemon off;'

将该脚本作为容器的启动入口即可，启动时传入对应环境变量就能完成配置渲染。

方案3：静态配置直接写死值 #

如果部署环境固定、不需要动态调整配置，直接将配置文件中${DOMAIN_NAME_CLIENT}、${PRIVATE_IP_CLIENT}两个占位符替换为实际的域名、IP地址，重载配置即可正常启动，不需要额外的变量解析逻辑。

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;


events {
    worker_connections  1024;
}


http {
    server_names_hash_bucket_size  256;
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [cache:$upstream_cache_status] [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;


    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    gzip on;
    gzip_disable "msie6";
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_buffers 16 8k;
    gzip_http_version 1.1;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/rss+xml text/javascript font/truetype font/opentype application/vnd.ms-fontobject image/svg+xml;

    include /etc/nginx/conf.d/*.conf;
    
server {

   listen 80;
   server_name ${DOMAIN_NAME_CLIENT};

   large_client_header_buffers 4 16k;

   proxy_buffer_size          128k;
   proxy_buffers              4 256k;
   proxy_busy_buffers_size    256k;

   proxy_read_timeout          1800;
   proxy_connect_timeout       1800;


   location /graphql {
       auth_basic off;
       proxy_pass http://${PRIVATE_IP_CLIENT}:3000;
       proxy_set_header HOST nginx;
       proxy_pass_request_headers       on;

       limit_except GET POST OPTIONS { deny all; }
   }

   location / {
         auth_basic off;

         limit_except GET POST { deny  all; }

         proxy_pass http://${PRIVATE_IP_CLIENT}:3000;
         proxy_pass_request_headers on;
         proxy_set_header proxied nginx;
      }
   }
}

内容的提问来源于stack exchange，提问作者ilovetoask