docker buildx 需手动安装为插件，放至 $home/.docker/cli-plugins/ 并命名为 docker-buildx；多架构构建须创建 docker-container 驱动的 builder 实例；go 交叉编译需在 dockerfile 中用 targetos/targetarch 设置 goos/goarch；推送私有仓库需显式登录并确保凭据被 buildx 加载；builder 容器需手动启停以维持活跃状态。
docker buildx install 命令没生效？检查 bin 目录和 PATH
buildx 不是 Docker Desktop 自带的子命令，它是个独立二进制，得手动装或启用。常见现象是执行 docker buildx build 报错：docker: 'buildx' is not a docker command。
实际做法很简单：下载对应平台的 buildx 二进制（比如从 https://github.com/docker/buildx/releases），重命名为 docker-buildx，放进 /usr/local/bin 或 $HOME/.docker/cli-plugins/（推荐后者）。
-
$HOME/.docker/cli-plugins/是优先级更高的插件目录，Docker 20.10+ 默认识别 - 文件名必须是
docker-buildx，不能是buildx或buildx-linux-amd64 - 确保有可执行权限：
chmod +x ~/.docker/cli-plugins/docker-buildx - 重启 shell 或运行
docker plugin list确认已加载
buildx build --platform linux/arm64,linux/amd64 构建失败？先创建并使用 builder 实例
默认的 default builder 不支持多架构，它只是调用本地 dockerd，而原生 dockerd 只能构建当前宿主机架构镜像。
必须显式创建一个支持多架构的 builder 实例，并指定 driver 为 docker-container（即用容器模拟不同 CPU）：
立即学习“go语言免费学习笔记（深入）”；
- 运行
docker buildx create --use --name mybuilder --driver docker-container - 第一次运行会自动拉取
moby/buildkit:buildx-stable-1镜像并启动 buildkitd 容器 - 确认当前 builder：
docker buildx inspect --bootstrap，输出里要有Platforms: [linux/amd64 linux/arm64] - 如果只看到宿主机架构，说明 buildkit 容器没正确启动，可加
--bootstrap强制初始化
交叉编译 Go 二进制时 CGO_ENABLED=0 不够？还得控制 GOOS/GOARCH
buildx 的 --platform 控制的是最终镜像的运行架构，但 Go 源码编译阶段仍由构建容器内的 Go 工具链决定。如果基础镜像用的是 golang:alpine，它本身不含 gcc，而某些依赖（如 net 包 DNS 解析）在 CGO 关闭时行为受限。
稳妥做法是在 Dockerfile 中显式设置构建参数：
FROM golang:1.22-alpine AS builder ARG TARGETOS ARG TARGETARCH ENV GOOS=$TARGETOS ENV GOARCH=$TARGETARCH ENV CGO_ENABLED=0 WORKDIR /app COPY . . RUN go build -o myapp .
-
TARGETOS/TARGETARCH是 buildx 内置构建参数，会随--platform自动注入 - 不设
CGO_ENABLED=0且基础镜像无 gcc，构建直接失败；设了但没配GOOS/GOARCH，二进制仍是宿主机架构 - Alpine 上若必须开 CGO（比如用 sqlite3），得换
golang:1.22（Debian）并安装gcc musl-dev
buildx build 推送镜像到私有 registry 失败？login 和 --push 要配对
buildx 不复用 docker login 凭据缓存，尤其在非交互式 CI 环境下容易 401。错误信息通常是：denied: requested access to the resource is denied 或 unauthorized: authentication required。
- 先确保已执行
docker login your-registry.example.com，且凭据写入了~/.docker/config.json - buildx builder 必须显式加载凭据：运行
docker buildx build --push ...前，先执行docker buildx imagetools create测试是否能读 config - CI 场景建议用
--secret id=regcred,src=$HOME/.docker/config.json显式传入凭据文件 - 私有 registry 若启用了 TLS 自签名证书，需把 CA 加到 builder 容器里：
docker buildx create --config ./buildkitd.toml，其中 toml 指定registry.insecure = ["your-registry.example.com"]
多架构镜像真正的麻烦不在 build 过程，而在 builder 实例生命周期管理——它背后是 buildkitd 容器，重启 Docker 或机器后可能停掉，docker buildx ls 看状态是 inactive 就得 docker buildx stop && docker buildx start。这个细节，很多人第一次遇到时查日志都找不到原因。
