name: create-multistage-dockerfile description: > ビルド環境とランタイム環境を分離して最小限の本番イメージを作成するマルチステージDockerfileを構築する。 ビルダー/ランタイムステージの分離、成果物のコピー、scratch/distroless/alpineターゲット、 およびサイズ比較をカバーする。本番イメージが大きすぎる場合、ビルドツールが最終イメージに含まれている場合、 1つのDockerfileから開発用と本番用の別々のイメージが必要な場合、またはエッジやサーバーレスなどの 制約のある環境にデプロイする場合に使用する。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: containerization complexity: intermediate language: Docker tags: docker, multi-stage, distroless, alpine, scratch, optimization locale: ja source_locale: en source_commit: 6f65f316 translator: claude-sonnet-4-6 translation_date: 2026-03-16

マルチステージDockerfileの作成

ビルドツールとランタイムを分離して最小限の本番イメージを生成するマルチステージDockerfileを構築する。

使用タイミング

• 本番イメージが大きすぎる場合（コンパイル言語で500MB超）
• ビルドツール（コンパイラ、開発ヘッダー）が最終イメージに含まれている場合
• 1つのDockerfileから開発用と本番用の別々のイメージが必要な場合
• 制約のある環境（エッジ、サーバーレス）へのデプロイ

入力

• 必須: 既存のDockerfileまたはコンテナ化するプロジェクト
• 必須: 言語とビルドシステム（npm、pip、go build、cargo、maven）
• 任意: ターゲットランタイムベース（slim、alpine、distroless、scratch）
• 任意: 最終イメージのサイズ制限

手順

ステップ1: ビルド依存関係とランタイム依存関係の識別

ステップ2: マルチステージビルドの構造化

コアパターン：大きなイメージでビルドし、成果物をスリムなイメージにコピーする。

# ---- ビルドステージ ----
FROM <build-image> AS builder
WORKDIR /src
COPY <dependency-manifest> .
RUN <install-dependencies>
COPY . .
RUN <build-command>

# ---- ランタイムステージ ----
FROM <runtime-image>
COPY --from=builder /src/<artifact> /<dest>
EXPOSE <port>
CMD [<entrypoint>]

ステップ3: 言語固有パターンの適用

Node.js（プルーニングされたnode_modules）

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"]

Python（virtualenvコピー）

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"]

Go（scratchへの静的バイナリ）

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"]

Rust（静的muslバイナリ）

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"]

期待結果： 最終イメージにランタイムとコンパイル済み成果物のみが含まれる。

失敗時： COPY --from=builderのパスを確認する。docker build --target builderを使用してビルドステージをデバッグする。

ステップ4: ランタイムベースの選択

注意: Alpineはmusl libcを使用する。一部のPythonホイールやNodeネイティブモジュールは動作しない場合がある。インタープリタ言語には-slim（glibc）を推奨する。

ステップ5: ステージ間のビルド引数

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"]

ビルド時: docker build --build-arg APP_VERSION=1.2.3 .

注意: FROMの前のARGはグローバル。各ステージで使用するにはARGを再宣言する必要がある。

ステップ6: イメージサイズの比較

# 両方のバリアントをビルド
docker build -t myapp:fat --target builder .
docker build -t myapp:slim .

# サイズを比較
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" | grep myapp

期待結果： 本番イメージがビルドステージより50-90%小さい。

バリデーション

• docker buildがすべてのステージで完了する
• 最終イメージにビルドツール（コンパイラ、開発ヘッダー）が含まれていない
• スリムイメージからのdocker runが正しく動作する
• シングルステージと比較してイメージサイズが大幅に縮小される
• COPY --from=builderのパスが正しい
• 本番イメージにソースコードが漏洩していない

よくある落とし穴

• ランタイムライブラリの不足: コンパイルされたコードが共有ライブラリ（libc、libssl）を必要とする場合がある。スリムイメージを十分にテストする
• COPY --fromパスの誤り: 成果物のパスは正確に一致する必要がある。docker build --target builderしてからdocker run --rm builder ls /pathでデバッグする
• Alpineのmusl問題: ネイティブNode.jsアドオンや一部のPythonパッケージはAlpineで失敗する。代わりに-slimを使用する
• グローバルARGスコープ: FROMの前に宣言されたARGはFROM行でのみ利用可能。各ステージ内で再宣言する
• CA証明書の忘れ: scratchには証明書がない。ビルダーから/etc/ssl/certs/ca-certificates.crtをコピーするかdistrolessを使用する

関連スキル

• create-dockerfile - シングルステージの汎用Dockerfile
• create-r-dockerfile - rockerイメージを使用するR固有のDockerfile
• optimize-docker-build-cache - レイヤーキャッシュとBuildKit機能
• setup-compose-stack - マルチステージイメージを使用するcompose設定