容器与云原生 / 系统课时
传入构建参数
传入构建参数
同一份 Dockerfile 往往需要构建开发、测试和生产镜像。本课使用 ARG 接收构建参数,并说明它与 ENV 的作用阶段、作用域和安全边界,最终完成一个可验证的多环境镜像。
学习目标
- 使用
ARG声明默认值并通过命令行覆盖 - 区分构建参数与运行环境变量
- 避免作用域错误和敏感信息泄露
构建参数解决什么问题
构建参数只在镜像构建过程中提供可变值,适合选择基础镜像、依赖版本、构建模式或下载地址。它让 Dockerfile 保持一份,同时由流水线在构建时决定具体配置。
ARG 与 ENV 最容易混淆。ARG 主要服务于构建步骤,容器启动后默认不可用;ENV 会写入镜像配置,并在容器运行时继续存在。需要把构建选择传到运行阶段时,可以显式使用 ENV 接收 ARG 的值。
| 对比项 | ARG |
ENV |
|---|---|---|
| 主要阶段 | 镜像构建时 | 构建时和容器运行时 |
| 命令行传值 | docker build --build-arg |
docker run -e 或 Dockerfile |
| 是否默认保留到容器 | 否 | 是 |
| 适合内容 | 版本、模式、非敏感开关 | 应用运行配置 |
声明并传入参数
下面的 Dockerfile 允许调用者选择基础镜像和构建环境。BASE_IMAGE 声明在 FROM 之前,因此可用于选择基础镜像;APP_ENV 声明在构建阶段内部,并通过 ENV 保留到运行阶段。
# syntax=docker/dockerfile:1
ARG BASE_IMAGE=alpine:3.22
FROM ${BASE_IMAGE}
ARG APP_ENV=production
RUN echo "building for ${APP_ENV}" > /build-env.txt
ENV APP_ENV=${APP_ENV}
CMD ["sh", "-c", "echo runtime=$APP_ENV && cat /build-env.txt"]在 Dockerfile 所在目录执行构建命令:
docker build \
--build-arg APP_ENV=staging \
-t arg-demo:staging .预期结果:
[+] Building <TIME> FINISHED
=> => naming to docker.io/library/arg-demo:staging<TIME> 和具体日志行会随 Docker 版本、缓存状态和构建器不同而变化,但镜像标签应为 arg-demo:staging。
运行容器验证构建值是否同时写入文件和运行环境:
docker run --rm arg-demo:staging预期输出:
runtime=staging
building for staging理解作用域和默认值
FROM 之前声明的参数可用于 FROM 指令,但不会自动进入后续构建阶段。若某个参数还要在阶段内部使用,需要在对应 FROM 之后再次写出同名 ARG。
未传入 --build-arg 时,Docker 使用 Dockerfile 中的默认值。传入参数时,命令行值覆盖默认值。多阶段构建中,每个阶段都应明确声明自己需要的参数,不要依赖隐式继承。
ARG 变量在 Shell 形式的 RUN 指令中会被展开。JSON 数组形式不会启动 Shell,例如 RUN ["echo", "$APP_ENV"] 通常只会输出字面量;需要变量展开时应使用 Shell 形式或显式调用 Shell。
安全边界与常见错误
不要通过 ARG 传入密码、令牌或私钥。构建参数可能出现在构建记录、镜像元数据、来源证明或流水线日志中,不能作为密钥保护机制。
常见错误是只声明 ARG APP_ENV,却期望容器启动后仍能读取它。另一个错误是把参数写在错误的构建阶段,导致变量为空。排查时先确认声明位置,再确认构建命令确实传入了同名参数。
本课总结
ARG用于构建时选择,ENV用于需要保留到运行时的配置- 命令行参数会覆盖默认值,多阶段构建应在需要的阶段重新声明
- 构建参数不具备保密能力,敏感值必须使用 BuildKit 密钥挂载
下一课预告
下一课将使用 BuildKit 的 --secret 和 RUN --mount=type=secret 临时挂载凭据,让构建步骤可以认证,同时不把密钥写入镜像层。