Docker 镜像构建参数如何传

ARG 指令定义构建参数，通过 --build-arg 传值，仅构建时生效且不存入镜像；需在使用前声明，支持默认值；作用域限于当前构建阶段，不可跨阶段继承；敏感信息禁用 ARG，应改用 --secret。

用 ARG 指令定义参数，再通过 docker build --build-arg 传值，是最标准、最安全的方式。参数只在构建时生效，不会留在最终镜像里，适合传版本号、环境名、配置路径等非敏感信息。

在 Dockerfile 中声明 ARG

ARG 必须写在使用它的指令之前，支持设默认值（推荐），避免因漏传导致构建失败：

1. ARG APP_VERSION=1.0.0 —— 有默认值，不传参时自动用 1.0.0
2. ARG CONFIG_PATH —— 无默认值，构建时必须用 --build-arg CONFIG_PATH=... 显式传入，否则该变量为空
3. 可在 RUN、COPY、LABEL 等指令中引用，比如：COPY $CONFIG_PATH /app/config.yaml

构建时用 --build-arg 传参

命令行传参要和 ARG 名称完全一致（区分大小写），可传多个：

1. docker build --build-arg APP_VERSION=2.3.1 --build-arg ENV=staging -t myapp:2.3.1 .
2. 如果参数含空格或特殊字符，建议加引号：--build-arg "BUILD_TIME=$(date)"
3. 多次传同一个 ARG，后面值会覆盖前面的（按命令顺序）

多阶段构建中注意作用域

ARG 只对当前阶段有效，不能跨阶段自动继承：

1. 若想在第二阶段也用 APP_VERSION，需在每个阶段开头重新声明：ARG APP_VERSION
2. 可以在 FROM 前声明 ARG，这样它能被后续的 FROM 引用（如 FROM node:$NODE_VERSION）
3. 不要指望第一阶段 RUN echo $APP_VERSION 的结果能在第二阶段直接读到

别把敏感信息塞进 ARG

ARG 值虽不存入镜像，但在构建日志、CI 系统历史记录里可能明文可见：

1. 密码、token、私钥等请改用 docker build --secret（需启用 BuildKit）
2. 临时调试可用 RUN echo "DEBUG: $APP_VERSION" 输出验证，但上线前删掉
3. 用 ARG + ENV 组合时要小心：ENV 会让变量进入运行时镜像，而 ARG 不会