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