Docker Build

Docker Build — 镜像构建与管理

Complete reference for docker build and image lifecycle management. Build, tag, inspect, push, prune.

When to Use

ALWAYS use this skill when the user mentions:

• "docker build", "怎么构建镜像", "docker build 命令"
• "docker tag", "docker push", "推送镜像"
• "docker images", "镜像管理", "docker image"
• "--build-arg", "构建参数"
• "docker history", "docker inspect", "镜像查看"
• "docker image prune", "docker system prune", "清理镜像"

docker build — Complete Syntax

docker build [OPTIONS] PATH | URL | -

Essential Options

# Basic build
docker build -t myapp:v1 .

# Tag multiple tags at once
docker build -t myapp:v1.2.3 -t myapp:latest -t ghcr.io/org/myapp:v1.2.3 .

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

# Build from Git repository
docker build -t myapp https://github.com/user/repo.git#main

# Build from stdin
cat Dockerfile | docker build -t myapp -
docker build -t myapp - <<EOF
FROM alpine:3.20
CMD ["echo", "hello"]
EOF

Build Arguments (--build-arg)

# Pass build arguments
docker build --build-arg NODE_VERSION=22 --build-arg ENV=production -t myapp .

# From file
docker build --build-arg $(cat .env.build | xargs) -t myapp .

ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
ARG ENV=development
ENV NODE_ENV=${ENV}
RUN echo "Building for ${NODE_ENV}"

Build Control

# No cache (force full rebuild)
docker build --no-cache -t myapp .

# Pull base image even if cached locally
docker build --pull -t myapp .

# Quiet mode (only image ID)
docker build -q -t myapp .

# Set build target (multi-stage)
docker build --target builder -t myapp:builder .

# BuildKit output (export to local directory)
docker build --output type=local,dest=./out .

# Platform (with BuildKit)
docker build --platform linux/amd64 -t myapp .

# Add metadata
docker build --label "org.opencontainers.image.version=v1.2.3" -t myapp .

Build Context

# Current directory
docker build -t myapp .

# Specific directory
docker build -t myapp ./app

# Remote Git repo
docker build -t myapp https://github.com/user/repo.git#v1.0.0:subdir

# Pipe context via stdin (no context)
docker build -t myapp - < Dockerfile

Image Tagging — docker tag

# Tag an existing image
docker tag myapp:v1 myapp:latest
docker tag myapp:v1 ghcr.io/org/myapp:v1

# Tag with registry
docker tag myapp:v1 registry.example.com:5000/myapp:v1

# Force overwrite existing tag
docker tag myapp:v1 myapp:latest   # replaces where :latest points

Tag Naming Convention

[registry[:port]/][namespace/]name[:tag|@digest]

ghcr.io/myorg/myapp:v1.2.3
│       │     │      │
│       │     │      └── tag (semver)
│       │     └── image name
│       └── namespace
└── registry

Image Inspection

# List images
docker images
docker image ls
docker image ls --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

# Inspect image details
docker inspect myapp:v1
docker inspect --format='{{.Config.Env}}' myapp:v1
docker inspect --format='{{.Created}}' myapp:v1

# View layer history
docker history myapp:v1
docker history --no-trunc --human myapp:v1

# Show digest
docker image ls --digests myapp
docker inspect --format='{{index .RepoDigests 0}}' myapp:v1

Pushing to Registry

# Login
docker login
docker login ghcr.io -u USERNAME -p $TOKEN

# Push
docker push myapp:v1
docker push myapp --all-tags

# Push with digest
docker push myapp@sha256:abc123...

Image Cleanup

# Remove specific image
docker rmi myapp:v1
docker image rm myapp:v1

# Remove dangling images (<none>:<none>)
docker image prune

# Remove all unused images
docker image prune -a

# Full system cleanup
docker system prune -a --volumes

# Check disk usage
docker system df
docker system df -v

Workflow — 推荐构建流程

Step 1: 准备 Dockerfile: 已完成编写（或使用 docker-dockerfile 生成） Step 2: 配置构建参数: 确认 --build-arg、--label、--target Step 3: 执行构建: docker build -t myapp:v1 -t myapp:latest . Step 4: 验证镜像: docker images / docker history / docker inspect Step 5: 推送仓库: docker push 前 docker login，生产环境用 digest 固定

Gotchas — Common Pitfalls

• `docker build -t myapp .` sends entire context: Without .dockerignore, sends node_modules/.git and everything. Use .dockerignore to minimize context.
• `docker build --no-cache` is slow: Only use when truly needed. Normal builds reuse cached layers.
• `docker tag` is mutable: Tags can be moved. For production, use digest (@sha256:...) instead of tag.
• `docker push` without login fails silently: Always docker login first, or use CI credential helpers.
• `docker system prune -a` is destructive: Removes ALL unused images, containers, networks. Don't run in production without confirmation.
• `docker build --pull` changes base image: Your build may produce different output if base image was updated.

Boundary — 能力边界（适用与不适用场景）

When NOT to Use This Skill

Security & Stability

• Always scan built images with docker scout before pushing to production registry.
• Use docker build --pull to ensure base images are up-to-date with security patches.
• Never embed secrets in build args (--build-arg is visible in image history). Use BuildKit --secret instead.
• Tag images with --label for metadata (version, git SHA, build timestamp) for audit trails.
• Remove unused images regularly with docker image prune to free disk space and reduce attack surface.

📚 官方文档参考

🧭 Docker Skills Journey

📍 You are here: `docker-build` — 镜像构建与管理

basics → dockerfile → build → buildx → run → compose → ...

→ Next: docker-buildx — Multi-platform builds and BuildKit advanced features

从零构建并推送镜像

# 1. 创建项目
mkdir myapp && cd myapp

# 2. 写 Dockerfile
cat > Dockerfile <<'EOF'
FROM nginx:1.27-alpine
COPY index.html /usr/share/nginx/html/
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost/health || exit 1
EOF

echo '<h1>Hello Docker Build</h1>' > index.html

# 3. 构建（多 tag）
docker build -t myapp:v1.0.0 -t myapp:latest .

# 4. 查看
docker images myapp
docker history myapp:v1.0.0
docker inspect --format='{{.Config.Env}}' myapp:v1.0.0

# 5. 运行验证
docker run -d -p 8080:80 --name myapp-test myapp:latest
curl localhost:8080
docker stop myapp-test && docker rm myapp-test

# 6. 推送到仓库
docker login
docker tag myapp:v1.0.0 docker.io/myuser/myapp:v1.0.0
docker push docker.io/myuser/myapp:v1.0.0
docker push docker.io/myuser/myapp:latest

构建参数与环境区分

Dockerfile

ARG NODE_VERSION=22
FROM node:${NODE_VERSION}-alpine

ARG APP_ENV=development
ENV NODE_ENV=${APP_ENV}

WORKDIR /app
COPY package*.json ./

# dev 装全部依赖，prod 仅生产依赖
RUN if [ "$APP_ENV" = "production" ]; then npm ci --production; else npm install; fi

COPY . .
EXPOSE 3000
CMD ["node", "index.js"]

构建命令

# 开发构建
docker build \
  --build-arg NODE_VERSION=22 \
  --build-arg APP_ENV=development \
  -t myapp:dev .

# 生产构建
docker build \
  --build-arg NODE_VERSION=22 \
  --build-arg APP_ENV=production \
  -t myapp:prod .

# CI 中使用 Git SHA 作为标签
docker build \
  --build-arg APP_ENV=production \
  --label "org.opencontainers.image.version=$(git rev-parse --short HEAD)" \
  -t myapp:$(git rev-parse --short HEAD) .

查看构建参数是否生效

docker inspect --format='{{.Config.Env}}' myapp:prod | grep NODE_ENV
# [NODE_ENV=production]

docker inspect --format='{{json .Config.Labels}}' myapp:prod | jq .
# {"org.opencontainers.image.version": "abc1234"}

多阶段构建目标选择

Dockerfile

FROM golang:1.23-alpine AS builder
WORKDIR /src
COPY . .
RUN go build -o /app .

FROM golang:1.23-alpine AS tester
WORKDIR /src
COPY . .
RUN go test ./...

FROM alpine:3.20 AS runtime
COPY --from=builder /app /usr/local/bin/app
CMD ["app"]

按目标构建

# 仅构建测试阶段（不产生最终镜像）
docker build --target tester -t myapp:test .

# 构建运行阶段
docker build --target runtime -t myapp:latest .

# 构建全部阶段（默认）
docker build -t myapp:latest .

场景

docker build 参数速查

完整参数表

镜像管理命令速查

构建上下文优化

# 查看上下文大小
docker build -t myapp . 2>&1 | head -1
# => [internal] load build context    transfer context: 2.56MB

# 使用 .dockerignore 减小上下文
echo "node_modules/" >> .dockerignore
echo ".git/" >> .dockerignore
echo ".env" >> .dockerignore

导出/导入镜像

# 导出（含所有层）
docker save myapp:v1 -o myapp-v1.tar
docker save myapp:v1 | gzip > myapp-v1.tar.gz

# 导入
docker load -i myapp-v1.tar
docker load < myapp-v1.tar.gz

常用构建模式

# CI 构建（拉取缓存 + 推送到仓库）
docker build \
  --pull \
  --cache-from ghcr.io/org/myapp:latest \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  --build-arg VCS_REF=$(git rev-parse --short HEAD) \
  --label "org.opencontainers.image.created=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \
  --label "org.opencontainers.image.revision=$(git rev-parse --short HEAD)" \
  -t ghcr.io/org/myapp:$(git rev-parse --short HEAD) \
  -t ghcr.io/org/myapp:latest \
  .

# 无上下文构建（仅 Dockerfile）
docker build -t myapp - < Dockerfile

镜像标签策略与生命周期

标签策略决策树

需要精确追溯？→ 是 → digest (@sha256:abc...) + git SHA tag
需要语义版本？→ 是 → semver (v1.2.3) + minor (v1.2) + major (v1)
需要自动部署？→ 是 → git SHA + latest（仅 stable 分支）
团队协作？    → docker/metadata-action 自动生成标签矩阵

推荐标签方案

# 每个 commit 打多标签
docker build \
  -t myapp:sha-$(git rev-parse --short HEAD) \
  -t myapp:v1.2.3 \
  -t myapp:v1.2 \
  -t myapp:v1 \
  -t myapp:latest \
  .

# 生产部署使用 digest
docker pull myapp@sha256:abc123def456...

不可变标签最佳实践

docker/metadata-action 标签矩阵

tags: |
  type=semver,pattern={{version}}
  type=semver,pattern={{major}}.{{minor}}
  type=sha,format=short
  type=ref,event=branch
  type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}

清理策略

# 保留最近 10 个 tag，删除其余
docker images myapp --format '{{.Tag}}' | sort -V | head -n -10 | xargs -I {} docker rmi myapp:{}

# 删除 30 天前的未使用镜像
docker image prune -a --filter "until=720h"

# 仅删除 dangling 镜像
docker image prune

BuildKit 基础：本地构建加速

启用 BuildKit

# 方式1：环境变量
export DOCKER_BUILDKIT=1
docker build -t myapp .

# 方式2：Daemon 配置（永久）
# /etc/docker/daemon.json
{ "features": { "buildkit": true } }

# 方式3：docker buildx（推荐）
docker buildx build -t myapp --load .

# 检查是否启用
docker buildx version

BuildKit 带来的提升

基础 BuildKit 用法

# 使用 registry 缓存
docker buildx build \
  --cache-from type=registry,ref=myapp:buildcache \
  --cache-to type=registry,ref=myapp:buildcache,mode=max \
  -t myapp:latest \
  --load .

# 行式输出（CI 友好）
docker buildx build --progress plain -t myapp --load .

# 仅构建不加载到本地
docker buildx build -t myapp .
# 镜像不在 docker images 中，需 --load 或 --push

迁移到 buildx

# 传统
docker build -t myapp .

# 等价 buildx
docker buildx build -t myapp --load .

# 多 tag
docker build -t myapp:v1 -t myapp:latest .
docker buildx build -t myapp:v1 -t myapp:latest --load .

常见问题