容器与云原生 / 系统课时

传入构建参数

传入构建参数

同一份 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 保留到运行阶段。

dockerfile
# 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 所在目录执行构建命令:

bash
docker build \
  --build-arg APP_ENV=staging \
  -t arg-demo:staging .

预期结果:

text
[+] Building <TIME> FINISHED
 => => naming to docker.io/library/arg-demo:staging

<TIME> 和具体日志行会随 Docker 版本、缓存状态和构建器不同而变化,但镜像标签应为 arg-demo:staging。

运行容器验证构建值是否同时写入文件和运行环境:

bash
docker run --rm arg-demo:staging

预期输出:

text
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 临时挂载凭据,让构建步骤可以认证,同时不把密钥写入镜像层。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

传入构建参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通