docker buildx bake --set 怎样临时覆盖一个目标

临时覆盖 Bake 的单个目标，可以重复传入 --set 目标名.属性=值，并在命令末尾明确选择实际构建的目标。下面只调整 api 的镜像标签和构建参数，不回写共享 HCL 文件。

# 指定文件、覆盖属性并选择 api，将单平台结果加载到本地
docker buildx bake -f docker-bake.hcl \
  --set 'api.tags=demo/api:trial' \
  --set 'api.args.BUILD_CHANNEL=trial' \
  --load api

api.tags 的 api 限定覆盖范围，末尾 api 选择构建目标，这是两个独立动作。只指定覆盖项，不代表只构建该目标。官方命令参考：https://docs.docker.com/reference/cli/docker/buildx/bake/。

1. 准备两个目标，明确默认值

在已经能使用 Docker Buildx 的环境中，为示例建立独立目录，保存以下两个文件。api 和 worker 共用上下文与默认变量，默认组包含二者，因此省略目标名时可能同时构建两者。

# docker-bake.hcl：两个目标共享默认参数
variable "CHANNEL" {
  default = "stable"
}
group "default" {
  targets = ["api", "worker"]
}
target "api" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["demo/api:stable"]
  args = { BUILD_CHANNEL = CHANNEL }
}
target "worker" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["demo/worker:stable"]
  args = { BUILD_CHANNEL = CHANNEL }
}

# Dockerfile：把参数写进元数据，便于构建后观察
FROM scratch
ARG BUILD_CHANNEL
LABEL org.example.channel=${BUILD_CHANNEL}

这个最小镜像没有应用程序和 shell，只演示构建参数进入元数据的过程。实际项目应使用自己的 Dockerfile，并确认参数确实被消费。仅传一个未被使用的 ARG，不会自动改变程序行为。

2. 指定一次性的目标属性覆盖

在示例目录执行开头的命令。显式使用 -f docker-bake.hcl，让配置来源更清楚。第一项把 api 的镜像标签改为 trial，第二项只覆盖 api 的 BUILD_CHANNEL；末尾 api 表示本次选择它构建，worker 不会因默认组而被连带构建。

--set 的目标部分支持模式匹配。这里使用精确目标名，不使用星号，避免影响多个目标。参数整体加引号也能防止 shell 先解释特殊字符。重复传入该选项，就能设置不同属性。

当前命令文档使用 tag、arg 等单数属性名，同时支持 tags、args 等复数别名。本文采用复数写法，与 HCL 字段更容易对应。不要把 HCL 列表文本 ["demo/api:trial"] 原样塞进命令值；本例直接传入一个镜像引用。

--load 用于本例的单平台、本地加载场景，配置中没有额外的输出声明。已有输出配置或多平台发布任务，应根据 builder 和镜像存储能力选择输出方式，不能直接假定本例适合所有构建流水线。

3. 核对结果，并恢复普通调用

命令成功且镜像已加载到本地后，分别检查输出名称和参数对应的镜像标签。下面提供的是执行后的核对方法，不是本文实际运行的回执。

# 检查本次输出的镜像引用
docker image inspect demo/api:trial --format '{{json .RepoTags}}'
# 检查参数经 Dockerfile LABEL 写入的 channel 值
docker image inspect demo/api:trial --format '{{index .Config.Labels "org.example.channel"}}'

对这个最小示例，第一项应能找到 demo/api:trial，第二项的预期值为 trial。镜像名称与构建参数是不同维度：标签名称变化，并不能证明应用配置变化；这里专门用 LABEL 建立一个可观察的参数结果。

找不到镜像时，先检查构建是否成功、是否进行了本地加载，以及镜像检查命令是否连接相同 Docker 上下文。channel 仍为 stable 时，检查目标名、属性路径和 Dockerfile 对参数的引用。若构建了额外目标，检查是否遗漏末尾 api，或是否使用了扩大匹配范围的模式。

下一次需要恢复文件里的默认值，去掉覆盖项即可：

# 再次读取配置文件，使用 api 的 stable 默认值
docker buildx bake -f docker-bake.hcl --load api

这会重新构建 api 并使用文件里的 stable 标签；之前生成的 trial 镜像不会自动删除。--set 的值不会成为下次调用的默认值。共享变量适合给多个目标提供统一输入；目标属性覆盖适合只改变一个目标的一次运行。把完整命令、目标名和输出镜像引用记录在构建日志中，便于追溯此次差异。

参考：Docker Buildx Bake 命令参考；Bake 配置参考。