Docker buildx bake怎样集中管理多镜像构建参数

当一个项目同时要构建 web、api 和 worker 三个镜像时，继续把一长串 docker buildx build 参数分别写在脚本里，很快就会出现标签不一致、平台漏配、环境变量重复的问题。Docker Buildx Bake 的做法是把这些目标和共享参数写进一个声明式文件，再用一次命令展开或构建。

把会被多个镜像复用的标签、平台和注册表参数放到 variable，把镜像目标放到 target，再用 group 组织默认入口；需要切换环境时优先用 --var 覆盖变量，不要复制第二份 Bake 文件。

官方地址：https://docs.docker.com/build/bake/

下面用一个三镜像项目演示完整路径。示例只讨论构建配置的集中管理，不把仓库凭据、生产密钥或真实镜像地址写进文件。

先把重复参数从三个命令里抽出来

假设项目目录中有三个服务，每个服务都有自己的 Dockerfile，但它们共享镜像仓库、标签和目标平台。最容易失控的写法，是分别维护三条命令：

# 三条命令分别维护，标签或平台很容易漏改
docker buildx build ./web --tag registry.example.com/team/web:dev --platform linux/amd64
docker buildx build ./api --tag registry.example.com/team/api:dev --platform linux/amd64
docker buildx build ./worker --tag registry.example.com/team/worker:dev --platform linux/amd64

这三条命令的问题不在于不能执行，而在于公共信息被复制了三次。Bake 文件可以把共享部分声明一次，把服务差异保留在各自目标中。Docker 官方文档把 Bake 描述为对复杂构建配置的声明式抽象，配置中可以定义目标、目标组和变量。

创建一个可复用的 docker-bake.hcl

在项目根目录新建 docker-bake.hcl。这里把 TAG、REGISTRY 和 PLATFORM 作为变量，把三个镜像加入默认组。HCL 中的 # 是注释，代码里的注释说明每一段为什么存在。

# 共享变量：默认值服务于本地开发，也可以在命令行覆盖
variable "REGISTRY" {
  default = "registry.example.com/team"
}

variable "TAG" {
  default = "dev"
}

variable "PLATFORM" {
  default = "linux/amd64"
}

# 默认组：不传目标名时，按这个列表构建三个镜像
group "default" {
  targets = ["web", "api", "worker"]
}

# 每个 target 只保留自己的上下文和镜像名，公共参数通过变量插值复用
target "web" {
  context    = "./web"
  dockerfile = "./web/Dockerfile"
  platforms  = [PLATFORM]
  tags       = ["${REGISTRY}/web:${TAG}"]
}

target "api" {
  context    = "./api"
  dockerfile = "./api/Dockerfile"
  platforms  = [PLATFORM]
  tags       = ["${REGISTRY}/api:${TAG}"]
}

target "worker" {
  context    = "./worker"
  dockerfile = "./worker/Dockerfile"
  platforms  = [PLATFORM]
  tags       = ["${REGISTRY}/worker:${TAG}"]
}

这里的关键关系是：group 只负责“默认要选哪些目标”，target 负责每个镜像的上下文和 Dockerfile，variable 负责会跨目标复用的值。把三者混在一起写，后面就很难判断某个参数到底是全局约定还是单个镜像的例外。

先查看目标，再展开最终配置

不要一上来就执行构建。软件教程里更稳妥的操作顺序，是先在项目根目录列出 Bake 配置里的目标和变量，再打印展开后的配置。这样可以在真正消耗构建资源前看到标签、平台和目标集合。

# 查看当前 Bake 文件暴露出的目标，避免目标名拼写错误
docker buildx bake --list=targets

# 查看声明的变量、类型和默认值
docker buildx bake --list=variables

# 展开变量和目标属性，但不开始构建
docker buildx bake --print

屏幕上应能看到默认组包含 web、api、worker，并能在展开结果中找到三个不同的 context、Dockerfile 和标签。--print 的价值是把 HCL 中的插值变成最终构建配置，排查时比直接猜命令行参数更直观。

如果只想展开某一个目标，可以在命令末尾写目标名：

# 只查看 api 目标的展开结果，不触发构建
docker buildx bake --print api

用 --var 切换开发和发布参数

Bake 文件的共享结构不需要因为环境变化而复制。比如本地开发使用 dev 标签，准备发布候选镜像时可以通过 --var 在本次调用中覆盖 TAG 和 PLATFORM：

# 只改变本次调用的变量，不改动 docker-bake.hcl
docker buildx bake \
  --var TAG=rc-2026-11 \
  --var PLATFORM=linux/amd64,linux/arm64

# 先展开发布参数，确认三个目标会得到相同标签和平台集合
docker buildx bake \
  --var TAG=rc-2026-11 \
  --var PLATFORM=linux/amd64,linux/arm64 \
  --print

命令行显式传入的变量优先级高于环境变量和 Bake 文件中的默认值。这里的操作确认点是：展开结果中的三个标签都包含同一个 rc-2026-11，平台字段也都来自同一个覆盖值。不要把带密码的注册表地址或令牌当作普通变量提交到仓库，敏感信息应使用构建系统的密钥能力处理。

只改一个目标时使用 --set

--var 适合改声明变量，--set 适合覆盖某个目标的具体属性。比如三个服务默认构建同一平台，但临时只让 worker 使用另一个 Dockerfile，可以这样查看，不影响其他目标：

# 只覆盖 worker 的 Dockerfile，其他目标仍使用 Bake 文件原值
docker buildx bake \
  --set worker.dockerfile=./worker/Dockerfile.debug \
  --print worker

如果需求是改变所有目标的公共标签，使用 --var 更清楚；如果需求是某个目标的单点例外，使用 --set 更容易在审查时看出影响范围。不要用大量 --set 把整个 Bake 文件重新写一遍，否则集中管理的收益会被命令行覆盖消耗掉。

执行默认组并保留清晰的失败边界

确认 --print 结果后，才执行默认组：

# 使用默认组构建三个目标；失败时根据目标名定位具体服务
docker buildx bake

# 也可以显式指定两个目标，避免把 worker 放进本次构建
docker buildx bake web api

默认情况下不传目标名会选择名为 default 的组。需要在 CI 中区分服务时，可以显式传目标名，或者为不同的目标集合定义不同的 group。把目标分组后，日志中的镜像名、标签和上下文更容易和项目目录对应，失败也不必回头比较三份相似脚本。

几个容易误判的边界

还要注意，--print 只是查看解析后的构建配置，不代表镜像已经构建成功；真正的构建仍可能受到 Dockerfile、网络、缓存、注册表权限和平台支持情况影响。把“配置展开正确”和“构建上传成功”当成两个不同的确认点，排错会更快。

最后用一张清单确认集中管理生效

完成配置后，可以按下面的顺序做人工确认：

1. docker buildx bake --list=targets 能看到预期目标和默认组。
2. docker buildx bake --list=variables 能看到共享变量及默认值。
3. docker buildx bake --print 展开出的三个目标拥有各自上下文，同时复用了同一标签和平台。
4. 使用 --var 切换环境后，所有受影响目标的展开值一起变化。
5. 只需要例外时才使用 --set，并能说清它影响的是哪一个目标。

这样，Docker buildx bake 就不只是把多条命令换了一个文件名，而是把“共享参数、目标差异、默认分组和临时覆盖”分成了清晰的层次。后续增加镜像时只需新增目标，切换环境时优先覆盖变量，构建前用 --print 看最终配置即可。

常见问题

不写目标名时会构建哪些镜像？ 通常会选择名为 default 的组，具体成员以 Bake 文件中的 group "default" 为准。

--var 和 --set 应该怎么选？ 要改变声明变量及其插值结果时用 --var；只改某个目标的具体属性时用 --set。

--print 能代替真正构建吗？ 不能。它用于查看解析后的构建请求，不能证明 Dockerfile 能成功执行或镜像能推送到注册表。

可以把所有环境都写成三份 Bake 文件吗？ 可以，但通常先用变量默认值、--var 和少量 --set 表达环境差异，重复结构较少，后续维护更容易。