Create multi-stage Dockerfiles that separate build and runtime environments for minimal production images. Covers builder/runtime stage separation, artifact copying, scratch/distroless/alpine targets, and size comparison. Use when production images are too large, when build tools are included in the final image, when you need separate dev and prod images from one Dockerfile, or when deploying to constrained environments like edge or serverless.
Build multi-stage Dockerfiles that produce minimal production images by separating build tooling from runtime.
| Category | Build Stage | Runtime Stage |
|---|---|---|
| Compilers | gcc, g++, rustc | Not needed |
| Package managers | npm, pip, cargo | Sometimes (interpreted langs) |
| Dev headers | -dev packages | Not needed |
| Source code | Full source tree | Only compiled output |
| Test frameworks | jest, pytest | Not needed |
The core pattern: build in a fat image, copy artifacts to a slim image.
# ---- Build Stage ----
FROM <build-image> AS builder
WORKDIR /src
COPY <dependency-manifest> .
RUN <install-dependencies>
COPY . .
RUN <build-command>
# ---- Runtime Stage ----
FROM <runtime-image>
COPY --from=builder /src/<artifact> /<dest>
EXPOSE <port>
CMD [<entrypoint>]
FROM node:22-bookworm AS builder
WORKDIR /src
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev
FROM node:22-bookworm-slim
RUN groupadd -r app && useradd -r -g app app
WORKDIR /app
COPY --from=builder /src/dist ./dist
COPY --from=builder /src/node_modules ./node_modules
COPY --from=builder /src/package.json .
USER app
EXPOSE 3000
CMD ["node", "dist/index.js"]
FROM python:3.12-bookworm AS builder
WORKDIR /src
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
FROM python:3.12-slim-bookworm
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY --from=builder /src .
RUN groupadd -r app && useradd -r -g app app
USER app
EXPOSE 8000
CMD ["python", "app.py"]
FROM golang:1.23-bookworm AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server
FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /server /server
EXPOSE 8080
ENTRYPOINT ["/server"]
FROM rust:1.82-bookworm AS builder
RUN apt-get update && apt-get install -y musl-tools && rm -rf /var/lib/apt/lists/*
RUN rustup target add x86_64-unknown-linux-musl
WORKDIR /src
COPY Cargo.toml Cargo.lock ./
RUN mkdir src && echo "fn main() {}" > src/main.rs \
&& cargo build --release --target x86_64-unknown-linux-musl \
&& rm -rf src
COPY . .
RUN touch src/main.rs && cargo build --release --target x86_64-unknown-linux-musl
FROM scratch
COPY --from=builder /src/target/x86_64-unknown-linux-musl/release/myapp /myapp
EXPOSE 8080
ENTRYPOINT ["/myapp"]
Expected: Final image contains only the runtime and compiled artifacts.
On failure: Check COPY --from=builder paths. Use docker build --target builder to debug the build stage.
| Base | Size | Shell | Use Case |
|---|---|---|---|
| scratch | 0 MB | No | Static Go/Rust binaries |
| gcr.io/distroless/static | ~2 MB | No | Static binaries + CA certs |
| gcr.io/distroless/base | ~20 MB | No | Dynamic binaries (libc) |
| *-slim | 50-150 MB | Yes | Interpreted languages |
| alpine | ~7 MB | Yes | When shell access needed |
Note: Alpine uses musl libc. Some Python wheels and Node native modules may not work. Prefer -slim (glibc) for interpreted languages.
ARG APP_VERSION=0.0.0
FROM golang:1.23 AS builder
ARG APP_VERSION
RUN go build -ldflags="-X main.version=${APP_VERSION}" -o /server .
FROM gcr.io/distroless/static
COPY --from=builder /server /server
ENTRYPOINT ["/server"]
Build with: docker build --build-arg APP_VERSION=1.2.3 .
Note: ARG before FROM is global. Each stage must re-declare ARG to use it.
# Build both variants
docker build -t myapp:fat --target builder .
docker build -t myapp:slim .
# Compare sizes
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" | grep myapp
Expected: Production image is 50-90% smaller than the build stage.
docker build completes for all stagesdocker run works correctly from the slim imageCOPY --from=builder paths are correctlibc, libssl). Test the slim image thoroughly.COPY --from paths: The artifact path must match exactly. Use docker build --target builder then docker run --rm builder ls /path to debug.-slim instead.ARG declared before FROM is available to FROM lines only. Re-declare inside each stage that needs it.scratch has no certificates. Copy /etc/ssl/certs/ca-certificates.crt from the builder or use distroless.create-dockerfile - single-stage general Dockerfilescreate-r-dockerfile - R-specific Dockerfiles with rocker imagesoptimize-docker-build-cache - layer caching and BuildKit featuressetup-compose-stack - compose configurations using multi-stage imagesnpx skills add pjt222/create-multistage-dockerfile下载完整 Skill 目录，包含 SKILL.md 及所有相关文件
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer