NGINX官方Docker镜像原生支持envsubst动态渲染配置，启动时自动执行20-envsubst-on-templates.sh脚本，将/etc/nginx/templates下以.template结尾的模板文件中${VAR}变量替换为环境变量值，并输出到/etc/nginx/conf.d/目录。
NGINX 官方 Docker 镜像原生支持环境变量动态渲染配置，关键在于利用其内置的 envsubst 机制，而非手动改写配置或自定义 entrypoint。只要用对路径、后缀和模板语法，启动时自动完成替换。
确认使用的是官方镜像并启用模板机制
必须基于 nginx:alpine、nginx:stable 或更高版本（1.21+），低版本或自建镜像默认不带该功能。容器启动时，官方 entrypoint 会自动执行 /docker-entrypoint.d/20-envsubst-on-templates.sh 脚本——它只在以下条件满足时生效：
-
模板文件放在指定目录：默认是
/etc/nginx/templates，也可通过NGINX_ENVSUBST_TEMPLATE_DIR自定义 -
文件名带指定后缀：默认为
.template（注意不是.tmpl或.conf.template），可通过NGINX_ENVSUBST_TEMPLATE_SUFFIX覆盖 -
输出目录可写：默认生成到
/etc/nginx/conf.d/，需确保该路径存在且容器有写权限
编写可变量替换的 template 文件
在宿主机准备一个 default.conf.template，放在挂载进容器的模板目录中（如 ./templates/default.conf.template）：
server {
listen ${NGINX_PORT:-80};
server_name ${SERVER_NAME:-_};
location /api/ {
proxy_pass http://${BACKEND_HOST}:${BACKEND_PORT};
proxy_set_header Host $host;
}
}
⚠️ 注意：
– 变量必须用 ${VAR} 或 $VAR 格式，不能写成 $ENV_VAR；
– 支持默认值语法 ${VAR:-default}；
– 不要在 server_name 或 proxy_pass 中混用未定义变量，否则渲染失败导致 Nginx 启动报错。
启动容器时传入环境变量
用 docker run 或 docker-compose.yml 注入变量，同时挂载模板目录：
docker run -d \
--name my-nginx \
-p 80:80 \
-e NGINX_PORT=80 \
-e SERVER_NAME=app.example.com \
-e BACKEND_HOST=backend \
-e BACKEND_PORT=3000 \
-v $(pwd)/templates:/etc/nginx/templates:ro \
nginx:alpine
或者 docker-compose.yml 片段：
services:
nginx:
image: nginx:alpine
ports: ["80:80"]
environment:
- NGINX_PORT=80
- SERVER_NAME=prod.example.com
- BACKEND_HOST=api-prod
- BACKEND_PORT=8080
volumes:
- ./templates:/etc/nginx/templates:ro
验证是否成功渲染
容器启动后，进入容器检查生成的配置：
docker exec -it my-nginx cat /etc/nginx/conf.d/default.conf
应看到变量已被实际值替换，例如 proxy_pass http://api-prod:8080;。
再执行 nginx -t 确认语法无误，说明渲染与加载均成功。
