容器与云原生 / 系统课时
怎样传递构建参数
怎样传递构建参数
构建参数用于让同一份 Dockerfile 在构建阶段接收不同值,例如版本号、镜像变体或编译开关;它与容器启动后的环境变量不是一回事。本节用 Compose 同时传入 build.args 和 environment,验证两者在生命周期和可见范围上的差异。
学习目标
- 使用 Compose 的
build.args为 Dockerfile 中的ARG提供值。 - 区分 Build Arg 与运行时环境变量的生效阶段。
- 避免用构建参数传递密码、令牌等敏感信息。
build.args 对应 Dockerfile 的 ARG
Compose 在服务的 build 下使用 args 设置 Dockerfile ARG 的值,既支持映射写法,也支持列表写法。ARG 用来参数化构建指令;如果没有把它显式写入镜像文件或转成 ENV,它不会像运行时环境变量那样自动出现在最终容器中。([Docker Documentation][1])
下面是 compose.yaml 的片段示例,实际使用时还需要对应的 Dockerfile:
services:
demo:
build:
context: .
args:
APP_VERSION: "${APP_VERSION:-dev}"这里 ${APP_VERSION:-dev} 先由 Compose 做变量插值,再把结果作为构建参数交给 Dockerfile。Dockerfile 需要声明同名 ARG APP_VERSION,才能在对应构建阶段中使用这个值。
用一个示例同时观察构建期和运行期
创建 Dockerfile。为了让构建参数的效果可以直接验证,示例把版本值写入镜像中的 /image-version 文件。
FROM alpine:3.20
ARG APP_VERSION=dev
RUN printf '%s\n' "$APP_VERSION" > /image-version
CMD ["sh", "-c", "printf 'build=%s runtime=%s\\n' \"$(cat /image-version)\" \"$APP_ENV\""]再创建完整的 compose.yaml,其中 APP_VERSION 走构建参数路径,APP_ENV 走容器运行时环境变量路径。
services:
demo:
build:
context: .
args:
APP_VERSION: "${APP_VERSION:-dev}"
environment:
APP_ENV: "${APP_ENV:-local}"运行构建,再启动一次临时容器:
APP_VERSION=1.2.3 docker compose build --quiet demo >/dev/null 2>&1
APP_ENV=staging docker compose run --rm demo 2>/dev/null预期输出
build=1.2.3 runtime=staging结果说明两个值走的是不同路径:APP_VERSION 在镜像构建时决定 /image-version 的内容;APP_ENV 到容器启动时才进入进程环境。Compose 的 environment 和 env_file 用于设置容器环境,而不是 Dockerfile 的构建参数。([Docker Documentation][3])

改运行时变量不需要重建镜像
继续使用刚才已经构建好的镜像,只改变 APP_ENV:
APP_ENV=production docker compose run --rm demo 2>/dev/null预期输出
build=1.2.3 runtime=production这一次没有重新执行镜像构建,因此 /image-version 中的 1.2.3 不变;运行时变量则可以在每次启动容器时改变。反过来,如果修改 APP_VERSION 并希望镜像内容随之变化,需要再次执行 docker compose build。docker compose build 也支持 --build-arg 设置构建期变量。([Docker Documentation][4])
不要把 build args 当作 secrets
构建参数不适合承载密码、访问令牌或私钥。Docker 官方明确提醒,构建参数可能暴露在镜像历史或构建证明等信息中;需要在构建阶段读取敏感值时,应使用 BuildKit secret mount 或 SSH mount,而不是 ARG。([Docker Documentation][5])
选择参数入口时先看生命周期:版本选择、编译开关等属于构建期;日志级别、服务地址等通常属于运行期。把两者分开后,镜像能保持稳定,部署环境也更容易按需覆盖。