Docker buildx bake 用 HCL 统一多服务构建参数

当一个仓库同时维护 web 和 worker 两个镜像时，把所有参数塞进两条很长的 docker buildx build 命令，最容易出现标签、构建参数或上下文不一致。更稳妥的做法是把构建配置放进项目根目录的 docker-bake.hcl，用 target 描述服务，用 group 组织一次执行的目标，再用 --print 预览展开结果。

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

步骤1：在项目根目录写出第一版 Bake 配置

在项目根目录打开文件管理器或编辑器，路径选择“项目根目录 → 新建文件”，文件名填 docker-bake.hcl。这里的入口不是 Dockerfile 菜单，而是 Bake 文件本身；后续命令会自动读取它。

先写两个服务 target。示例中的目录名、镜像名和版本值是演示值，换成你的仓库实际路径即可。

# 这组变量集中管理两个服务共用的镜像仓库和版本
variable "REGISTRY" {
  default = "registry.example/team"
}

variable "RELEASE" {
  default = "dev"
}

# web 使用 web 目录作为构建上下文
target "web" {
  context    = "./web"
  dockerfile = "Dockerfile"
  tags       = ["${REGISTRY}/portal:${RELEASE}"]
  args = {
    APP_MODE = "web"
  }
}

# worker 使用独立上下文，避免误把 web 文件带入构建
target "worker" {
  context    = "./worker"
  dockerfile = "Dockerfile"
  tags       = ["${REGISTRY}/worker:${RELEASE}"]
  args = {
    APP_MODE = "worker"
  }
}

核对点是：context 指向各自目录，dockerfile 相对对应上下文解析，tags 的仓库和版本来自变量，args 只传构建阶段需要的值。这样以后改版本只需改一处。

步骤2：用 group 统一选择多服务目标

回到编辑器的 docker-bake.hcl 文件，在两个 target 后增加默认组。操作路径是“项目根目录 → docker-bake.hcl → 文件末尾”，新增下面的配置：

保存后，读者可以选择“构建面板 → Targets → default”查看组内目标；如果只需要一个服务，也可以在命令后写 web 或 worker。不要把运行时依赖关系误写成 group，group 只负责选择构建目标，不负责启动容器、创建网络或编排服务。

步骤3：先用 --print 检查展开后的配置

打开项目根目录的命令面板，执行：

预览结果至少要核对四项：目标是否包含 web 和 worker，标签是否带上 RELEASE，上下文是否落在正确目录，APP_MODE 是否传给了对应服务。这里看到的是配置展开结果，不等于镜像已经构建完成。

步骤4：执行构建，并用 --set 做临时覆盖

确认预览无误后，回到命令面板执行默认组：

如果日志只出现一个目标，先检查命令末尾是否误写了单个 target；如果标签不对，先用 --print 看变量展开，再确认环境变量或 --set 是否覆盖了 HCL。生产流水线建议把稳定值写入 Bake 文件，把临时发布标签留给命令行覆盖，避免把一次性参数提交到配置库。

常见问题

直接执行 docker buildx bake 为什么没有构建预期服务？

命令默认执行名为 default 的 group。检查 group 的 targets 是否包含目标；没有 group 时就显式执行 docker buildx bake web worker。

--print 显示的 tags 不对怎么办？

先看变量默认值和命令行覆盖项，再用 docker buildx bake --print 重跑。--print 只负责展示展开后的构建定义，不会替你推送镜像。

group 能代替 Docker Compose 启动服务吗？

不能。group 只组织构建 target；镜像构建完成后，容器启动、网络和运行时依赖仍应由 Compose 或其他运行时工具负责。