容器与云原生 / 系统课时

怎样传递构建参数

怎样传递构建参数

构建参数用于让同一份 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:

yaml
services:
  demo:
    build:
      context: .
      args:
        APP_VERSION: "${APP_VERSION:-dev}"

这里 ${APP_VERSION:-dev} 先由 Compose 做变量插值,再把结果作为构建参数交给 Dockerfile。Dockerfile 需要声明同名 ARG APP_VERSION,才能在对应构建阶段中使用这个值。

用一个示例同时观察构建期和运行期

创建 Dockerfile。为了让构建参数的效果可以直接验证,示例把版本值写入镜像中的 /image-version 文件。

dockerfile
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 走容器运行时环境变量路径。

yaml
services:
  demo:
    build:
      context: .
      args:
        APP_VERSION: "${APP_VERSION:-dev}"
    environment:
      APP_ENV: "${APP_ENV:-local}"

运行构建,再启动一次临时容器:

bash
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

预期输出

text
build=1.2.3 runtime=staging

结果说明两个值走的是不同路径:APP_VERSION 在镜像构建时决定 /image-version 的内容;APP_ENV 到容器启动时才进入进程环境。Compose 的 environment 和 env_file 用于设置容器环境,而不是 Dockerfile 的构建参数。([Docker Documentation][3])

Build Arg 与运行时环境变量的生命周期

改运行时变量不需要重建镜像

继续使用刚才已经构建好的镜像,只改变 APP_ENV:

bash
APP_ENV=production docker compose run --rm demo 2>/dev/null

预期输出

text
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])

选择参数入口时先看生命周期:版本选择、编译开关等属于构建期;日志级别、服务地址等通常属于运行期。把两者分开后,镜像能保持稳定,部署环境也更容易按需覆盖。

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

目录与阅读设置

阅读设置

17

记录一个想法

怎样传递构建参数

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

登录哪都通