多阶段构建的核心是配置分离、环境解耦与产物可控，而非堆砌阶段数量；构建只做确定性编译，配置由运行时注入，同一镜像复用全环境。
多阶段构建处理复杂多环境配置打包，关键不在“多阶段”本身，而在于把配置分离、环境解耦、产物可控。它不是靠增加阶段数量来应对复杂性，而是用阶段职责划分，把“谁负责什么”理清楚——构建归构建，配置归配置，运行归运行。
配置与代码必须分离，不能硬编码进镜像
环境差异（开发/测试/预发/生产）主要体现在配置项上：数据库地址、密钥、超时时间、特征开关等。这些内容：
- 绝对不能写死在 Python 代码或 requirements.txt 里
- 不应通过 RUN 命令在构建时注入（如 ENV DB_URL=...），否则不同环境得打多个镜像
- 推荐方式是：所有配置由外部注入，镜像只提供“可运行的二进制+结构化占位能力”
常见做法是让应用启动时读取标准位置的配置文件（如 /config/app.yaml）或环境变量。Docker 运行时用 -e 或 --env-file 注入，Kubernetes 用 ConfigMap/Secret 挂载，这样同一镜像可复用于全部环境。
构建阶段只做“确定性编译”，不参与环境决策
比如一个需要连接不同云服务的 Python 智能体，它的 SDK 依赖（boto3、google-cloud-core）是通用的，但认证方式（IAM Role / Service Account Key / API Token）因环境而异。这时：
- builder 阶段只装 pip、编译 C 扩展、生成字节码，不做任何条件判断
- 不在 Dockerfile 里写
RUN if [ "$ENV" = "prod" ]; then pip install ...; fi—— 这破坏可重现性 - 所有环境相关逻辑下沉到应用层（如用 pydantic-settings 动态加载配置）
多环境可借助“配置阶段”作为中间桥接（非必需但实用）
当配置本身也需要预处理（如模板渲染、密钥解密、URL 拼接），可以增设一个轻量级“config stage”：
# 阶段1：构建代码和依赖 FROM python:3.11-slim-bookworm AS builder WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir --target /deps -r requirements.txt COPY . . RUN python -m compileall -q . # 阶段2：生成环境专属配置（可选） FROM alpine:3.20 AS config-gen RUN apk add --no-cache gettext jq COPY --from=builder /app/config/templates/ /templates/ ARG ENV=dev RUN envsubst < /templates/app.conf.tmpl > /output/app.conf # 阶段3：组装运行镜像 FROM python:3.11-slim-bookworm WORKDIR /app COPY --from=builder /deps /usr/local/lib/python3.11/site-packages/ COPY --from=builder /app/src/ . COPY --from=config-gen /output/app.conf /app/config/ CMD ["python", "main.py"]
这个 config-gen 阶段不装 Python，只用 shell 工具做文本处理，体积小、速度快、无残留风险。
构建参数（--build-arg）仅用于控制构建过程，不可替代运行时配置
--build-arg ENV=prod 可以用来：
- 选择不同的 requirements-prod.txt
- 切换前端构建命令（
npm run build:prod） - 启用/禁用调试工具安装（如 ptvsd）
但它不能用来设置数据库密码、API 密钥等敏感信息（会留在镜像历史中），也不该影响最终镜像的内容结构。敏感项一律交由运行时注入。
总结几个落地要点
- 同一 Dockerfile + 同一 git commit → 构建出完全相同的镜像，这是多环境可靠部署的前提
- 环境差异必须收敛到最少入口：通常是 1 个配置文件 + 若干环境变量
- 如果项目真需要“为每个环境打一个镜像”，说明配置管理已失控，应回头重构应用的配置加载机制
- 多阶段不是越多越好，三个以内（builder / config-gen / runner）足够覆盖绝大多数场景
