Docker Compose 构建镜像时无法读取环境变量，是因为构建阶段默认不继承宿主机或.env文件中的变量；必须通过build.args显式传递，并在Dockerfile中用ARG声明接收，必要时用ENV转为运行时变量。
在 Docker Compose 构建镜像时无法读取环境变量，通常不是因为环境变量“不存在”，而是因为 构建阶段（build stage）默认不自动继承宿主机或 Compose 文件中的环境变量。Docker 构建本身是隔离的，除非显式传递，否则 Dockerfile 中的 ARG 或 ENV 看不到你本地 terminal 或 .env 文件里设的值。
确认变量来源和作用域
Docker Compose 中环境变量有多个来源，需分清用途：
-
宿主机 shell 变量（如
export MY_VAR=abc）：默认不传入 build 过程，需手动用args显式传递 -
.env文件变量：仅用于替换docker-compose.yml中的${VAR}占位符，不会自动进构建上下文 -
environment字段：只影响容器运行时，对build阶段完全无效 -
args字段：唯一能将变量传入docker build的标准方式，对应Dockerfile中的ARG
在 docker-compose.yml 中正确传递构建参数
必须在服务的 build 下使用 args，把变量从 compose 层“推”进构建过程：
services:
app:
build:
context: .
dockerfile: Dockerfile
args:
- MY_VERSION=${MY_VERSION:-1.0.0}
- BUILD_ENV=${BUILD_ENV:-dev}
注意：${VAR:-default} 是 compose 的变量展开语法，依赖 .env 或 shell 环境；如果想强制用 shell 变量，可直接写 - MY_VERSION=$MY_VERSION（Linux/macOS 支持，Windows PowerShell 不支持）。
在 Dockerfile 中接收并使用参数
ARG 必须在 FROM 之后、且在被使用前声明（Docker 23.0+ 支持全局 ARG，但兼容性起见建议就近声明）：
ARG MY_VERSION ARG BUILD_ENV <h1>可选：转为运行时环境变量</h1><p>ENV APP_VERSION=$MY_VERSION ENV NODE_ENV=$BUILD_ENV</p><h1>构建时使用（例如下载特定版本）</h1><p>RUN echo "Building version $MY_VERSION for $BUILD_ENV" </p>
⚠️ 注意：ARG 在构建结束后即失效，若需运行时也生效，必须用 ENV 显式赋值（如上），或在启动命令中重新注入。
调试技巧：验证变量是否真正传入
临时修改 Dockerfile 加一行诊断输出：
RUN echo "DEBUG: MY_VERSION = $MY_VERSION" && \
echo "DEBUG: BUILD_ENV = $BUILD_ENV" && \
env | grep -i 'version\|env'
然后运行 docker compose build --no-cache app，观察日志中是否打印出预期值。如果为空，说明 args 没配对或变量未定义。
不复杂但容易忽略：构建和运行是两个独立阶段，环境变量不会自动跨阶段流动。只要明确用 args + ARG 搭桥，99% 的“读不到变量”问题都能解决。
