docker-build

Docker Build — 镜像构建与管理

docker build 和镜像生命周期管理完整参考。构建、打标签、检查、推送和清理。

适用场景

用户提到以下内容时，始终使用此技能：

• “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、打标签、推送
管理本地镜像
需要 docker build CLI 参考
编写 Dockerfile 本身	docker-dockerfile
多平台构建	docker-buildx
BuildKit 高级功能	docker-buildx

docker build — 完整语法

docker build [OPTIONS] PATH | URL | -

基本选项

# 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-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-arg KEY=VALUE	传递单个参数
--build-arg-file FILE	从文件读取参数
ARG KEY=default	在 Dockerfile 中定义默认值

构建控制

# 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 .

构建上下文

# 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

镜像打标签 — 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

标签命名规范

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

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

镜像检查

# 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

推送到仓库

# 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...

镜像清理

# 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

工作流 — 推荐构建流程

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

注意事项 — 常见问题

• docker build -t myapp . 会发送整个上下文：如果没有 .dockerignore，node_modules/.git 等所有内容都会被发送。使用 .dockerignore 缩小上下文。
• docker build --no-cache 速度很慢：仅在确有需要时使用。常规构建会复用缓存层。
• docker tag 是可变的：标签可以被移动。生产环境应使用 digest（@sha256:...），而不是标签。
• 未登录时执行 docker push 会静默失败：务必先执行 docker login，或使用 CI 凭据助手。
• docker system prune -a 具有破坏性：会移除所有未使用的镜像、容器和网络。未经确认，不要在生产环境中运行。
• docker build --pull 会更改基础镜像：如果基础镜像已更新，构建可能产生不同的结果。

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

分类	场景	说明
✅ 能做	docker build 构建镜像	完整命令语法、上下文管理、多标签
✅ 能做	docker tag 打标签	命名规范、多 registry 标签
✅ 能做	docker push 推送镜像	仓库登录、digest 固定
✅ 能做	镜像管理（inspect/history/prune）	本地镜像生命周期
⚠️ 需条件	BuildKit 高级特性（secret/cache/ssh）	使用 docker-buildx
⚠️ 需条件	网络不稳定时推送大镜像	配置 max-concurrent-uploads
❌ 超范围	编写 Dockerfile	使用 docker-dockerfile
❌ 超范围	多平台构建（arm64/amd64）	使用 docker-buildx
❌ 超范围	CI/CD 流水线集成	使用 docker-cicd

不适用场景

❌ 跳过	✅ 改用
编写 Dockerfile 本身	docker-dockerfile
多平台/arm64 构建	docker-buildx
BuildKit secrets/cache/SSH	docker-buildx
运行容器	docker-run
Docker 基础知识	docker-basics

安全与稳定性

• 推送到生产仓库前，始终使用 docker scout 扫描构建的镜像。
• 使用 docker build --pull，确保基础镜像已包含最新安全补丁。
• 切勿在构建参数中嵌入机密（--build-arg 的内容会显示在镜像历史中）。应改用 BuildKit --secret。
• 使用 --label 为镜像添加元数据（版本、git SHA、构建时间戳），以便进行审计追踪。
• 定期使用 docker image prune 移除未使用的镜像，以释放磁盘空间并缩小攻击面。

📚 官方文档参考

文档	地址
Docker Build	https://docs.docker.com/build/
docker build 命令	https://docs.docker.com/reference/cli/docker/build/
docker tag	https://docs.docker.com/reference/cli/docker/image/tag/
docker push	https://docs.docker.com/reference/cli/docker/image/push/
docker image	https://docs.docker.com/reference/cli/docker/image/
Dockerfile 参考	https://docs.docker.com/reference/dockerfile/

🧭 Docker Skills Journey

📍 当前位置：docker-build — 镜像构建与管理

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

→ 下一步：docker-buildx — 多平台构建和 BuildKit 高级功能