docker buildのキャッシュと.dockerignore設計｜Dockerfileの命令順序でCIビルドを高速化する実践手順

この記事のポイント

・Dockerのキャッシュは命令が変わった行以降すべて無効化される
・変更頻度の低い命令（apt install）を上に、ソースのCOPYを最後に書く
・.dockerignoreでビルドコンテキストを削減し転送時間を大幅に短縮できる
・BuildKitの--mount=type=cacheでパッケージキャッシュを永続化できる

# NG例：ソースコードを最初にコピーしてしまっている
FROM python:3.12-slim
WORKDIR /app
COPY . .                        # ここでソースが変わるたびにキャッシュ無効
RUN pip install -r requirements.txt  # 毎回フルインストールになる

# NG：ソースをまとめてコピーしてからインストールしている
FROM python:3.12-slim
WORKDIR /app
COPY . .                          # ソース変更のたびにここでキャッシュ無効
RUN pip install -r requirements.txt
CMD ["python", "app.py"]

# OK：依存関係ファイルを先にコピーしてインストール
FROM python:3.12-slim
WORKDIR /app

# requirements.txt だけ先にコピー（変更頻度が低い）
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# ソースコードは最後にコピー
COPY . .
CMD ["python", "app.py"]

# 最適化前（ソースコードを変更した後の再ビルド）
$ docker build -t myapp:ng .
[+] Building 47.2s (7/7) FINISHED
 => [internal] load build context                                  0.0s
 => => transferring context: 1.24GB                              12.3s
 => CACHED [1/3] FROM docker.io/library/python:3.12-slim          0.0s
 => [2/3] COPY . .                                                 0.3s  # キャッシュ無効
 => [3/3] RUN pip install --no-cache-dir -r requirements.txt     33.8s  # 再インストール
 => exporting to image                                             0.8s

# 最適化後（ソースコードを変更した後の再ビルド）
$ docker build -t myapp:ok .
[+] Building 0.7s (8/8) FINISHED
 => [internal] load build context                                  0.0s
 => => transferring context: 13.4kB                               0.0s
 => CACHED [1/4] FROM docker.io/library/python:3.12-slim          0.0s
 => CACHED [2/4] COPY requirements.txt .                          0.0s  # キャッシュ使用
 => CACHED [3/4] RUN pip install --no-cache-dir -r requirements.txt 0.0s # キャッシュ使用！
 => [4/4] COPY . .                                                0.1s
 => exporting to image                                             0.4s

# apt のベストプラクティス：update と install を同一RUNにまとめる
RUN apt-get update && apt-get install -y \
    curl \
    git \
    build-essential \
  && apt-get clean \
  && rm -rf /var/lib/apt/lists/*

# .dockerignore がない状態でのビルド
$ docker build .
[+] Building 18.4s (2/2)
 => [internal] load build context
 => => transferring context: 1.23GB    # .git や node_modules が丸ごと転送されている

# .dockerignore の例（プロジェクトルートに置く）

# バージョン管理
.git
.gitignore

# 依存パッケージ（コンテナ内で再インストールするため不要）
node_modules
__pycache__
*.pyc
*.pyo
.venv
venv/

# テスト・品質管理
.pytest_cache
.coverage
htmlcov/
tests/

# IDE・エディタの設定ファイル
.idea/
.vscode/
*.swp

# ビルド成果物
dist/
build/
*.egg-info/

# ローカル設定・シークレット
.env
.env.local
*.pem
*.key

# Docker自身のファイル（Dockerfile等は転送不要）
Dockerfile
docker-compose*.yml
.dockerignore

# ドキュメント
docs/
README*

# .dockerignore 設定後
$ docker build .
[+] Building 0.9s (2/2)
 => [internal] load build context
 => => transferring context: 14.2kB    # 1.23GB から 14kB に削減

# コンテキストサイズの変化
# 設定前: 1.23 GB（node_modules + .git が大半）
# 設定後:  14.2 kB（ソースコードのみ）

# BuildKit の有効確認（Docker 23.0+ ではデフォルトで有効）
$ docker buildx version
github.com/docker/buildx v0.14.1 081af9c

# Docker 22.x 以前で BuildKit を有効化する
$ export DOCKER_BUILDKIT=1
$ docker build .

# Debian/Ubuntu系（apt）のキャッシュマウント
FROM ubuntu:24.04
RUN --mount=type=cache,target=/var/cache/apt \
    --mount=type=cache,target=/var/lib/apt \
    apt-get update && apt-get install -y \
    curl \
    git \
    build-essential

# Python（pip）のキャッシュマウント
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

# Node.js（npm）のキャッシュマウント
FROM node:20-slim
WORKDIR /app
COPY package*.json .
RUN --mount=type=cache,target=/root/.npm \
    npm ci --prefer-offline
COPY . .
CMD ["node", "server.js"]

# すべてのレイヤーを再ビルドする
$ docker build --no-cache -t myapp:latest .

# 特定のステージからキャッシュを無効化したい場合
# ARG CACHEBUST を使う方法
ARG CACHEBUST=1
RUN curl -sf https://example.com/install.sh | sh
# ビルド時に --build-arg CACHEBUST=$(date +%s) を指定するとこの行以降のキャッシュが無効化される

# キャッシュが使われない ADD（URL指定）
ADD https://example.com/app.tar.gz /app/    # 毎回ダウンロードが走る

# COPY を使う（キャッシュが有効）
COPY app.tar.gz /app/
RUN tar -xzf /app/app.tar.gz -C /app/ && rm /app/app.tar.gz

# ビルドコンテキストのサイズを確認する
$ docker build --progress=plain . 2>&1 | grep "transferring context"
#2 [internal] load build context
#2 transferring context: 852.40MB    # 大きすぎる場合は .dockerignore を追加

# 大きいディレクトリを確認する
$ du -sh node_modules/ .git/ __pycache__/ 2>/dev/null
412M    node_modules/
 38M    .git/
1.2M    __pycache__/