## 10.2 使用 buildx 构建镜像

### 10.2.1 使用

Buildx 的使用非常直观，绝大多数情况下可以替代 `docker build` 命令。

你可以直接使用 `docker buildx build` 命令构建镜像。

```bash
$ docker buildx build .
[+] Building 8.4s (23/32)
 => ...
```
Buildx 使用 [BuildKit 引擎](10.1_buildkit.md)进行构建，支持许多新的功能，具体参考 [Buildkit](10.1_buildkit.md) 一节。

需要注意的是，默认 `docker` driver 会把构建结果加载到本地镜像存储；使用 `docker-container`、remote、cloud 等 builder 时，如未指定 `--load`、`--push` 或 `--output`，结果通常只保留在构建缓存中。

#### 构建前检查

Buildx 0.15 起支持构建检查：常规构建会默认检查 Dockerfile 与构建参数；如果只想做检查而不真正构建，可以使用 `--check`：

```bash
$ docker buildx build --check .
```
这适合作为 CI 的快速门禁：普通构建中的检查告警默认不会让构建失败，但 `--check` 发现问题会以非零状态退出；需要把告警提升为错误时，可在 Dockerfile 顶部配合 `# check=error=true`。

#### 使用 `bake`

`docker buildx bake` 是一个高级构建命令，支持从 HCL、JSON 或 Compose 文件中定义构建目标，实现复杂的流水线构建。

```bash
## 从 Compose 文件构建所有服务

$ docker buildx bake

## 仅构建指定目标

$ docker buildx bake web
```

#### 生成 SBOM

Buildx 支持在构建时直接生成 SBOM (Software Bill of Materials)，这对于软件供应链安全至关重要。

```bash
$ docker buildx build --sbom=true -t myimage .
```
该命令会把 SBOM 作为构建 attestation 附加到构建结果中；BuildKit 默认使用 SPDX SBOM attestation。需要 CycloneDX 文件时，可使用 Syft、Docker Scout 等工具另行生成或转换。

> **⚠️ 注意与失败模式**：
> 要使 SBOM (或其它 attestation 元数据) 成功附着并可见，对底层的存储格式有前置要求：默认的 classic image store 不支持 manifest list/index 这种存放 attestation 的结构。
>
> 如果只简单运行上述命令，你可能会面临 **“命令成功执行，但本地镜像中看不到 SBOM”** 的体会落差。
>
> **正确的解决路径有两条**：
> 1. **推送到远端仓库**：使用 `docker buildx build --sbom=true --push -t myimage:tag` 时，SBOM 会正确保存到远端仓库。远端 OCI 兼容的镜像仓库能够完整存储这些元数据。
> 2. **启用 containerd image store**：在 Docker 守护进程中启用 `containerd image store` 特性（Docker 29+，新安装场景默认启用，Docker Desktop 上也更容易直接使用），可以在本地查看和管理 SBOM 等 attestation 元数据。

### 10.2.2 官方文档

* [Docker buildx 命令文档](https://docs.docker.com/engine/reference/commandline/buildx/)