Dockerfile中envsubst环境变量替换异常，终端执行正常求助

核心原因 #

• 构建阶段无环境变量：Dockerfile的RUN指令在镜像构建阶段执行，此时容器未启动，不会自动加载本地.env文件，也无法获取docker run时传递的环境变量。而你在Docker Desktop Exec终端执行命令时，处于容器运行阶段，环境变量已通过docker run -e或手动export设置完成，因此envsubst能正常读取变量完成替换。
• 变量未注入构建上下文：即使本地存在.env文件，构建过程默认不会将这些变量注入到RUN指令的执行环境中，导致envsubst找不到$API_HOST和$API_PORT，最终输出的nginx.conf仍保留原始占位符，触发nginx的URL格式错误。

解决方案 #

场景1：构建时固定API地址（镜像内置配置） #

若API地址固定，无需运行时修改，可在构建阶段传递变量完成替换：

1. 修改Dockerfile，添加构建参数与环境变量声明：

FROM nginx:alpine
RUN apk add --update gettext
WORKDIR /etc/nginx/conf.d/
COPY nginx.conf.template .

# 声明构建参数，可设置默认值（可选）
ARG API_HOST=localhost
ARG API_PORT=8080
# 将构建参数转为环境变量，供envsubst读取
ENV API_HOST=$API_HOST
ENV API_PORT=$API_PORT

# 执行环境变量替换
RUN envsubst < nginx.conf.template > ../nginx.conf

CMD ["nginx", "-g", "daemon off;"]

2. 构建镜像时传递参数：

docker build --build-arg API_HOST=your-api-domain --build-arg API_PORT=9000 -t custom-nginx .

场景2：运行时动态替换配置（适配多环境） #

若需要在运行时切换API地址，建议将替换逻辑放到启动脚本中，容器启动时执行：

1. 创建启动脚本start.sh：

#!/bin/sh
# 仅替换指定环境变量，避免误替换nginx原生变量（如$host）
envsubst '$API_HOST $API_PORT' < /etc/nginx/conf.d/nginx.conf.template > /etc/nginx/nginx.conf
# 用exec保证信号能传递到nginx进程
exec nginx -g "daemon off;"

2. 修改Dockerfile，复制脚本并设置启动命令：

FROM nginx:alpine
RUN apk add --update gettext
WORKDIR /etc/nginx/conf.d/
COPY nginx.conf.template .
# 复制启动脚本并赋予执行权限
COPY start.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/start.sh

# 执行启动脚本
CMD ["start.sh"]

3. 运行容器时传递环境变量（或加载.env文件）：

# 直接传递变量
docker run -e API_HOST=prod-api.com -e API_PORT=80 -p 80:80 custom-nginx

# 加载本地.env文件
docker run --env-file .env -p 80:80 custom-nginx

额外注意事项 #

若nginx.conf.template中包含nginx原生变量（如$request_uri、$host），必须在envsubst后指定需要替换的变量列表（如envsubst '$API_HOST $API_PORT'），否则这些nginx变量会被envsubst清空，导致配置失效。

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