跳到主内容
智客 ZICQ

技能库 智客分类:运维与云 docker-buildx

Docker Buildx

Expert guidance for Docker image building — docker build CLI, buildx for multi-platform builds, BuildKit features (secret mounts, cache mounts, SSH forwarding, inline cache), Docker Build Cloud for accelerated cloud builds, layer caching strategies (--cache-from, --cache-to, GHA cache, registry cache), and CI/CD build optimization. Use when the user asks about docker build, buildx, multi-platform, multi-arch, linux/arm64, BuildKit, Build Cloud, Docker build acceleration, or build optimization. 使用场景:docker build、buildx、多平台构建、multi-platform、linux/arm64、BuildKit、Docker Build Cloud、构建加速、build optimization.

84 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

Docker 图像构建专家指南 — docker 构建 CLI, 为多平台构建的 builtx, BuildKit 特性( 秘密挂载, 缓存挂载, SSH 转发, 内置缓存), Docker 构建云用于加速云构建, 层缓存策略( -- cache- from, -- cache- to, GHA 缓存, 注册缓存), CI/CD 构建优化

何时用

** 用户提到时总是使用这种技能:**

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Docker Buildx — 构建引擎与多平台、When to Use、Core Commands、Basic build、Build with BuildKit (default in modern Docker)、Build from specific Dockerfile。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

Docker Buildx — 构建引擎与多平台When to UseCore CommandsBasic buildBuild with BuildKit (default in modern Docker)Build from specific DockerfileNo cache rebuildBuildx — Multi-Platform BuilderSetupCreate a builder instanceInspect available platformsBuild for Multiple Platforms

· 许可:Apache-2.0

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
docker-buildx
description
Expert guidance for Docker image building — docker build CLI, buildx for multi-platform builds, BuildKit features (secret mounts, cache mounts, SSH forwarding, inline cache), Docker Build Cloud for accelerated cloud builds, layer caching strategies (--cache-from, --cache-to, GHA cache, registry cache), and CI/CD build optimization. Use when the user asks about docker build, buildx, multi-platform, multi-arch, linux/arm64, BuildKit, Build Cloud, Docker build acceleration, or build optimization. 使用场景:docker build、buildx、多平台构建、multi-platform、linux/arm64、BuildKit、Docker Build Cloud、构建加速、build optimization.
许可
Apache-2.0
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「docker-buildx」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-eb15d3c111ac4b9a-Docker-%E6%9E%84%E5%BB%BA.html
请存为 .cursor/skills/docker-buildx/SKILL.md 或 .claude/skills/docker-buildx/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/full-stack-skills/docker-skills' --list

npx skills add 'https://github.com/full-stack-skills/docker-skills' --skill 'docker-buildx'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版

name: docker-buildx description: Expert guidance for Docker image building — docker build CLI, buildx for multi-platform builds, BuildKit features (secret mounts, cache mounts, SSH forwarding, inline cache), Docker Build Cloud for accelerated cloud builds, layer caching strategies (--cache-from, --cache-to, GHA cache, registry cache), and CI/CD build optimization. Use when the user asks about docker build, buildx, multi-platform, multi-arch, linux/arm64, BuildKit, Build Cloud, Docker build acceleration, or build optimization. 使用场景:docker build、buildx、多平台构建、multi-platform、linux/arm64、BuildKit、Docker Build Cloud、构建加速、build optimization. license: Apache-2.0

Docker Buildx — 构建引擎与多平台

Expert guidance for docker build, buildx, multi-platform builds, and build optimization.

When to Use

ALWAYS use this skill when the user mentions:

  • "docker build", "buildx", "构建镜像"
  • "multi-platform", "multi-arch", "多平台构建"
  • "linux/arm64", "linux/amd64"
  • "BuildKit", "Build Cloud"
  • "构建加速", "build cache", "构建缓存"
  • "Docker build 慢", "怎么加速 docker build"
  • Need to build images for multiple CPU architectures

Core Commands

# Basic build
docker build -t myapp:v1 .

# Build with BuildKit (default in modern Docker)
DOCKER_BUILDKIT=1 docker build -t myapp:v1 .

# Build from specific Dockerfile
docker build -f Dockerfile.prod -t myapp:v1 .

# No cache rebuild
docker build --no-cache -t myapp:v1 .

Buildx — Multi-Platform Builder

Setup

# Create a builder instance
docker buildx create --name multiarch --use

# Inspect available platforms
docker buildx inspect --bootstrap

Build for Multiple Platforms

# Build and push directly (single command)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/myapp:v1.0.0 \
  --push .

# Build and load to local Docker (single platform only)
docker buildx build \
  --platform linux/arm64 \
  -t myapp:arm64 \
  --load .

# Build and export as tar
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:v1.0.0 \
  --output type=tar,dest=myapp.tar .

Platform Aliases

| Alias | Architectures | |-------|---------------| | linux/amd64 | Intel/AMD 64-bit | | linux/arm64 | ARM 64-bit (Apple Silicon, AWS Graviton) | | linux/arm/v7 | ARM 32-bit (Raspberry Pi 3) | | linux/arm/v6 | ARM 32-bit (Raspberry Pi Zero) |

BuildKit Features

Secret Mount

# Dockerfile
RUN --mount=type=secret,id=npmrc \
  cp /run/secrets/npmrc .npmrc && \
  npm ci && \
  rm .npmrc
docker buildx build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

Cache Mount (Persist Across Builds)

# Python: persist pip cache
RUN --mount=type=cache,target=/root/.cache/pip \
  pip install -r requirements.txt

# Node.js: persist npm cache
RUN --mount=type=cache,target=/root/.npm \
  npm ci

# Go: persist module cache
RUN --mount=type=cache,target=/root/.cache/go-build \
  go build -o server .

SSH Forwarding

# Clone private repo during build
RUN --mount=type=ssh \
  git clone [email protected]:org/private-repo.git
docker buildx build --ssh default -t myapp .

Inline Cache (Export Cache into Image)

# Export cache metadata into the image itself
docker buildx build \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  -t myapp:latest \
  --push .

# Later builds can use this image as cache source
docker build --cache-from myapp:latest -t myapp:v2 .

Layer Caching — Pull Before Build

# Pull previous image for layer cache
docker pull myapp:latest || true
docker build \
  --cache-from myapp:latest \
  -t myapp:${TAG} .

GitHub Actions — Multi-Platform

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: user/app:latest
    cache-from: type=gha          # GitHub Actions cache
    cache-to: type=gha,mode=max

Workflow — 推荐构建流程

Step 1: 创建 Builder: docker buildx create --name multiarch --driver docker-container --use Step 2: 选择方案: 单平台(--load)还是多平台(--push)?交叉编译还是 QEMU? Step 3: 配置 Dockerfile: 使用 --platform=$BUILDPLATFORM + ARG TARGETOS TARGETARCH Step 4: 执行构建: docker buildx build --platform linux/amd64,linux/arm64 -t app --push . Step 5: 验证: docker buildx imagetools inspect app 确认多架构 manifest

Gotchas — Common Pitfalls

  • --load with multi-platform: --load only works for a SINGLE platform. → Recovery: Use --push or --output type=oci,dest=image.tar for multi-platform; or build single platform with --load.
  • QEMU emulation is slow: Building ARM on AMD is 5-10x slower. → Recovery: Use native ARM runners in CI (ubuntu-24.04-arm on GitHub Actions); or Docker Build Cloud for native multi-arch builders.
  • BuildKit by default: Modern Docker uses BuildKit by default. → Recovery: DOCKER_BUILDKIT=1 is a no-op on Docker 23+; use docker buildx build for explicit BuildKit control.
  • --cache-from without pulling first: Docker won't pull the cache image automatically. → Recovery: docker pull myapp:latest || true before docker build --cache-from myapp:latest.

Boundary — 能力边界(适用与不适用场景)

| 分类 | 场景 | 说明 | |------|------|------| | ✅ 能做 | 多平台构建(linux/amd64,arm64) | buildx + QEMU/交叉编译/原生节点 | | ✅ 能做 | BuildKit 高级特性 | secret mount、cache mount、SSH 转发、内联缓存 | | ✅ 能做 | Docker Build Cloud 接入 | 云端构建 + 团队共享缓存 | | ⚠️ 需条件 | 多平台 + --load | 仅支持单平台,多平台需 --push | | ⚠️ 需条件 | ARM 本地无 QEMU | 需 docker run --privileged --rm tonistiigi/binfmt --install all | | ❌ 超范围 | Dockerfile 编写 | 使用 docker-dockerfile | | ❌ 超范围 | 基础 docker build/tag/push | 使用 docker-build | | ❌ 超范围 | 容器编排(Compose/Swarm) | 使用 docker-compose/docker-production |

When NOT to Use This Skill

| ❌ Skip | ✅ Use Instead | |---------|---------------| | Writing Dockerfile content | docker-dockerfile | | Compose-based builds | docker-compose | | Docker basics | docker-basics | | Running containers | docker-run |

Security & Stability

  • Never expose secrets in build logs. Use --secret for BuildKit or CI secrets masking.
  • Multi-platform images must be pushed to a registry — --load only works for single platform.
  • Cache images in CI should be pulled with || true — first build won't have a cache.

📚 官方文档参考

| 文档 | 地址 | |------|------| | Docker Build | https://docs.docker.com/build/ | | Buildx 参考 | https://docs.docker.com/reference/cli/docker/buildx/ | | BuildKit | https://docs.docker.com/build/buildkit/ | | Docker Build Cloud | https://docs.docker.com/build-cloud/ | | 多平台构建 | https://docs.docker.com/build/building/multi-platform/ | | 构建缓存 | https://docs.docker.com/build/cache/ |

🧭 Docker Skills Journey

📍 You are here: docker-buildx — 构建引擎

← Previous: docker-dockerfile — Write Dockerfiles → Next: docker-run — Run containers / docker-cicd — CI/CD

相关技能

运维与云

Docker Essentials

用于容器管理,图像操作,调试的基本道克命令和工作流程.

运维与云

Find Skills

从开放的代理技能生态系统中发现并安装技能. 使用时:(1)用户问"我如何做X",X可能拥有现有技能,(2)用户说"为X找到技能"或"是否为X有技能",(3)用户问"你能否做X",X是专门能力,(4)用户想扩展代理能力,(5)用户想搜索工具,模板,或工作流程,(6)用户提到他们希望…

运维与云

Microsoft Foundry

构建,部署,评价,优化,微调,管理微软创始代理,模型,资源最终结束. 用法:铸造、azd ai代理、azd 提供/部署、托管代理脚手架/开发/运行/部署/拖放、即时代理创建、创建代理、更新代理、添加代理工具、援引代理、代理.yaml、评估代理、批量活化、连续活化、持续监测、代理C…

运维与云

Azure Deploy

执行已有.azure/部署计划.md和基础设施文件的ALREADY-PREPARED应用程序的Azure部署。 当用户向 CREATE 请求新应用程序时, 请不要使用此技能 。 这种技能运行了 azd上行, azd 部署, trarraform 应用, 和 az 部署命令带有内置…