Nginx Docker环境变量替换失效问题排查求助

核心原因 #

官方Nginx 1.25.3 Docker镜像的默认模板替换逻辑，仅会自动替换以NGINX_开头的环境变量。你的模板中包含LINUX_、WINDOWS_开头的自定义变量，这些不在默认替换范围内，因此envsubst不会处理它们，导致${变量名}保留在生成的配置文件中。Nginx启动时会将其视为未定义的内置变量，从而抛出unknown 'xxx' variable错误。

解决方法 #

方法1：统一变量命名前缀 #

将所有自定义变量改为以NGINX_开头，例如：

• LINUX_EXAMPLE_SERVICE_ROUTE → NGINX_LINUX_EXAMPLE_SERVICE_ROUTE
• WINDOWS_EXAMPLE_SERVICE_ROUTE → NGINX_WINDOWS_EXAMPLE_SERVICE_ROUTE

修改后，官方镜像的默认envsubst逻辑会自动识别并替换这些变量，无需额外修改启动命令。

方法2：显式指定要替换的变量 #

自定义envsubst执行命令，列出所有需要替换的变量，确保它们都被处理。

方式A：修改Dockerfile

在自定义Dockerfile中覆盖默认启动命令：

# 假设模板文件名为default.conf.template
CMD ["sh", "-c", "envsubst '${NGINX_CONFIG_SERVER_NAME} ${LINUX_EXAMPLE_SERVICE_ROUTE} ${NGINX_CONFIG_LINUX_HOST} ${LINUX_EXAMPLE_SERVICE_PORT} ${WINDOWS_EXAMPLE_SERVICE_ROUTE} ${NGINX_CONFIG_WINDOWS_HOST} ${WINDOWS_EXAMPLE_SERVICE_PORT}' < /etc/nginx/templates/default.conf.template > /etc/nginx/conf.d/default.conf && nginx -g 'daemon off;'"]

方式B：在Docker Compose中覆盖command

在docker-compose.yml中添加command字段，注意转义变量避免Compose提前解析：

services:
  nginx:
    # ... 其他配置
    command: >
      sh -c "envsubst '\$$NGINX_CONFIG_SERVER_NAME \$$LINUX_EXAMPLE_SERVICE_ROUTE \$$NGINX_CONFIG_LINUX_HOST \$$LINUX_EXAMPLE_SERVICE_PORT \$$WINDOWS_EXAMPLE_SERVICE_ROUTE \$$NGINX_CONFIG_WINDOWS_HOST \$$WINDOWS_EXAMPLE_SERVICE_PORT' < /etc/nginx/templates/default.conf.template > /etc/nginx/conf.d/default.conf && nginx -g 'daemon off;'"

额外检查项 #

• 确认模板文件后缀为.template（例如default.conf.template），官方镜像仅处理该后缀的模板文件。
• 进入容器后执行echo $变量名，验证环境变量是否已正确注入。

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