Dockerfile用ARG替换Python版本硬编码值致COPY失败问题

核心问题 #

你遇到的报错是因为ARG构建参数的作用域仅限定义它的构建阶段，且stage2的基础镜像baseimage:tag可能自带了值为3.10.13的PYTHON_VERSION环境变量，导致stage2解析${PYTHON_VERSION}时，用的是基础镜像的环境变量，而非你在stage1定义的3.10。

解决步骤 #

1. 跨阶段传递ARG参数 #

ARG是分阶段隔离的，stage1的ARG不会自动传递到stage2，需要在stage2中重新声明该参数，确保两个阶段使用相同的Python版本：

FROM base-image:tag as stage1

COPY requirements.txt requirements.txt
ARG PYTHON_VERSION=3.10

RUN gcc \
    && pip install -r requirements.txt \
    && rm -f requirements.txt 

# 把硬编码路径改成变量，保持与后续逻辑一致
RUN mkdir -p /usr/local/lib/python${PYTHON_VERSION}/site-packages/

FROM baseimage:tag as stage2
# 重新声明ARG，继承默认值或允许构建时传入自定义值
ARG PYTHON_VERSION=3.10
# 使用变量拷贝路径，确保与stage1的路径匹配
COPY --from=stage1 /usr/local/lib/python${PYTHON_VERSION}/site-packages/ /usr/local/lib/python${PYTHON_VERSION}/site-packages/

COPY . /my_dir
WORKDIR /my_dir

RUN chmod +x my_script.sh

2. 规避基础镜像环境变量干扰 #

如果stage2的基础镜像本身存在PYTHON_VERSION环境变量，可在stage2中显式覆盖该变量，确保解析路径时使用构建参数：

FROM baseimage:tag as stage2
ARG PYTHON_VERSION=3.10
# 覆盖基础镜像自带的同名环境变量
ENV PYTHON_VERSION=${PYTHON_VERSION}
COPY --from=stage1 /usr/local/lib/python${PYTHON_VERSION}/site-packages/ /usr/local/lib/python${PYTHON_VERSION}/site-packages/

3. 统一路径变量使用 #

将stage1中所有涉及Python版本的硬编码路径替换为${PYTHON_VERSION}变量，避免出现路径不一致的情况。

额外提示 #

构建时如需指定其他Python版本，无需修改Dockerfile，直接通过构建参数传入即可：

docker build --build-arg PYTHON_VERSION=3.9 .

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