docker-multi-stage
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDocker Multi-Stage Builds Skill
Docker 多阶段构建 Skill
Create optimized, minimal production images using multi-stage builds with language-specific patterns.
使用针对不同语言的模式，通过多阶段构建创建优化、轻量的生产镜像。
Purpose
目的
Reduce image size by 50-90% by separating build dependencies from runtime, following 2024-2025 best practices.
通过分离构建依赖与运行时环境，遵循2024-2025年最佳实践，将镜像大小减少50-90%。
Parameters
参数
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| language | enum | Yes | - | node/python/go/rust/java |
| target | string | No | runtime | Build target stage |
| base_runtime | string | No | - | Custom runtime base image |
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
| language | 枚举 | 是 | - | node/python/go/rust/java |
| target | 字符串 | 否 | runtime | 构建目标阶段 |
| base_runtime | 字符串 | 否 | - | 自定义运行时基础镜像 |
Multi-Stage Patterns
多阶段构建模式
Node.js (Alpine + Distroless)
Node.js（Alpine + Distroless）
dockerfile
undefineddockerfile
undefinedBuild stage
Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --production
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --production
Runtime stage (distroless = minimal attack surface)
Runtime stage (distroless = minimal attack surface)
FROM gcr.io/distroless/nodejs20-debian12 AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER nonroot
CMD ["dist/index.js"]
undefinedFROM gcr.io/distroless/nodejs20-debian12 AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER nonroot
CMD ["dist/index.js"]
undefinedPython (Slim + Virtual Environment)
Python（Slim + 虚拟环境）
dockerfile
undefineddockerfile
undefinedBuild stage
Build stage
FROM python:3.12-slim AS builder
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
FROM python:3.12-slim AS builder
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
Runtime stage
Runtime stage
FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY . .
USER nobody
CMD ["python", "main.py"]
undefinedFROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY . .
USER nobody
CMD ["python", "main.py"]
undefinedGo (Scratch = Smallest Possible)
Go（Scratch = 最小体积）
dockerfile
undefineddockerfile
undefinedBuild stage
Build stage
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app/server
Runtime stage (scratch = 0 base size)
Runtime stage (scratch = 0 base size)
FROM scratch AS runtime
COPY --from=builder /app/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
USER 65534
ENTRYPOINT ["/server"]
undefinedFROM scratch AS runtime
COPY --from=builder /app/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
USER 65534
ENTRYPOINT ["/server"]
undefinedRust (Musl for Static Linking)
Rust（Musl 静态链接）
dockerfile
undefineddockerfile
undefinedBuild stage
Build stage
FROM rust:1.75-alpine AS builder
RUN apk add --no-cache musl-dev
WORKDIR /app
COPY . .
RUN cargo build --release --target x86_64-unknown-linux-musl
FROM rust:1.75-alpine AS builder
RUN apk add --no-cache musl-dev
WORKDIR /app
COPY . .
RUN cargo build --release --target x86_64-unknown-linux-musl
Runtime stage
Runtime stage
FROM scratch AS runtime
COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/app /app
USER 65534
ENTRYPOINT ["/app"]
undefinedFROM scratch AS runtime
COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/app /app
USER 65534
ENTRYPOINT ["/app"]
undefinedJava (JRE Only Runtime)
Java（仅JRE运行时）
dockerfile
undefineddockerfile
undefinedBuild stage
Build stage
FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /app
COPY . .
RUN ./gradlew build --no-daemon
FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /app
COPY . .
RUN ./gradlew build --no-daemon
Runtime stage (JRE only, not JDK)
Runtime stage (JRE only, not JDK)
FROM eclipse-temurin:21-jre-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar
USER nobody
ENTRYPOINT ["java", "-jar", "app.jar"]
undefinedFROM eclipse-temurin:21-jre-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar
USER nobody
ENTRYPOINT ["java", "-jar", "app.jar"]
undefinedSize Comparison
镜像大小对比
| Language | Before | After | Reduction |
|---|---|---|---|
| Node.js | 1.2GB | 150MB | 87% |
| Python | 900MB | 120MB | 87% |
| Go | 800MB | 10MB | 99% |
| Rust | 1.5GB | 5MB | 99.7% |
| Java | 600MB | 200MB | 67% |
| 语言 | 优化前 | 优化后 | 缩减比例 |
|---|---|---|---|
| Node.js | 1.2GB | 150MB | 87% |
| Python | 900MB | 120MB | 87% |
| Go | 800MB | 10MB | 99% |
| Rust | 1.5GB | 5MB | 99.7% |
| Java | 600MB | 200MB | 67% |
Error Handling
错误处理
Common Errors
常见错误
| Error | Cause | Solution |
|---|---|---|
| Stage not found | Check stage name |
| Missing libs | Use alpine, not scratch |
| Non-root user | COPY --chown |
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 未找到指定阶段 | 检查阶段名称 |
运行时提示 | 缺少依赖库 | 使用alpine镜像而非scratch |
| 非root用户权限问题 | 使用COPY --chown参数 |
Fallback Strategy
回退策略
- Start with alpine instead of scratch/distroless
- Add required libraries incrementally
- Use to identify missing dependencies
ldd
- 优先使用alpine镜像而非scratch/distroless
- 逐步添加所需依赖库
- 使用命令识别缺失的依赖项
ldd
Troubleshooting
故障排查
Debug Checklist
调试检查清单
- All required files copied to runtime stage?
- SSL certificates included for HTTPS?
- User/group exists in runtime image?
- Build artifacts correctly located?
- 是否所有必需文件都已复制到运行时阶段？
- 是否包含了HTTPS所需的SSL证书？
- 运行时镜像中是否存在指定的用户/用户组？
- 构建产物是否位于正确路径？
Debug Commands
调试命令
bash
undefinedbash
undefinedCheck final image size
Check final image size
docker images myapp:latest
docker images myapp:latest
Inspect layers
Inspect layers
docker history myapp:latest --no-trunc
docker history myapp:latest --no-trunc
Compare with baseline
Compare with baseline
dive myapp:latest
undefineddive myapp:latest
undefinedUsage
使用方法
Skill("docker-multi-stage")Skill("docker-multi-stage")Assets
资源
- - Node.js template
assets/Dockerfile.node-multistage - - Python template
assets/Dockerfile.python-multistage
- - Node.js 模板
assets/Dockerfile.node-multistage - - Python 模板
assets/Dockerfile.python-multistage
Related Skills
相关技能
- docker-optimization
- dockerfile-basics
- docker-optimization
- dockerfile-basics