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

この記事のポイント

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

# 上位ほどコンテナに近い（後から重ねたレイヤー）
[ 書き込みレイヤー ] ← コンテナ起動時に追加（コンテナ固有・削除で消える）
[ COPYレイヤー    ] ← イメージの読み取り専用レイヤー
[ RUNレイヤー     ] ← イメージの読み取り専用レイヤー
[ FROM（ベース）  ] ← 読み取り専用（python:3.12-slim などのベースイメージ）

$ docker build --progress=plain -t myapp:test . 2>&1 | head -6
#0 building with "default" instance using docker driver

#1 [internal] load build context
#1 transferring context: 247.3MB 9.1s done
#1 DONE 9.4s

# 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 の基本構造（コメントは # で始める）
node_modules        # プロジェクトルート直下を除外
**/__pycache__      # 全階層の __pycache__ を除外（** グロブ）
*.log               # 拡張子一致（サブディレクトリは含まない）
.git
.env

# tests/ ディレクトリ全体を除外するが fixtures/ だけはコンテキストに残す
tests/
!tests/fixtures/

# NG例：否定パターンが除外パターンより先だと効果がない
!src/config.toml   # こちらが先に評価され…
src/               # このパターンで後から除外されるので結局除外される

# OK例：除外パターンを先に書いてから否定パターンで戻す
src/               # まずフォルダ全体を除外
!src/config.toml   # 次に特定ファイルを戻す ← こちらが最終評価なので有効

# .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（ソースコードのみ）

# ビルドコンテキストのルートで上位を確認する
$ du -sh * .* 2>/dev/null | sort -rh | head -10
421M    node_modules
6.4M    .git
1.2M    dist
348K    src
 12K    .env

# 一時的なDockerfileを渡してコンテキストサイズだけ確認する（ドライラン）
$ echo "FROM scratch" | docker build --progress=plain --no-cache -f- . 2>&1 | grep "transferring context"
#1 transferring context: 14.2kB 0.0s done

# Node.js プロジェクト用 .dockerignore

# 依存パッケージ（コンテナ内で再インストールするため不要）
node_modules
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# ビルド成果物（コンテナ内でビルドするため不要）
dist
build
.next
.nuxt

# 開発・テスト用
.env
.env.local
.env.*.local
coverage
.nyc_output

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

# IDE・エディタ設定
.vscode
.idea
*.swp

# Python プロジェクト用 .dockerignore

# バイトコード・キャッシュ
__pycache__
*.pyc
*.pyo
*.pyd

# 仮想環境
.venv
venv
env
.env

# テスト・カバレッジ
.pytest_cache
.coverage
htmlcov
.tox

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

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

# IDE設定
.vscode
.idea
*.swp

# Java プロジェクト用 .dockerignore

# Mavenローカルリポジトリ（コンテナ内でダウンロードするため不要）
.m2

# ビルド成果物
target
build

# Gradle
.gradle
gradle/wrapper/gradle-wrapper.jar

# IDE設定
.idea
*.iml
.classpath
.project
.settings

# 環境設定
.env
*.properties.local

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

# イメージ内の .env を docker run で確認できてしまう例
$ docker run --rm myapp cat /app/.env
DB_PASSWORD=supersecret123
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY

# セキュリティ観点で必ず除外すべきパターン
.env
.env.*
.envrc
.ssh
*.pem
*.key
*.p12
*.pfx
id_rsa
id_ed25519
id_ecdsa
.git
# クラウド認証情報
.aws/
.kube/
# OS固有の一時ファイル
.DS_Store

# イメージのレイヤー履歴を確認する
$ docker history --no-trunc myapp:latest
IMAGE          CREATED         CREATED BY                                      SIZE
sha256:a3f...  3 minutes ago   COPY . . # buildkit                             249MB
sha256:b7c...  3 minutes ago   RUN /bin/sh -c npm install # buildkit            78MB

# 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 * .* 2>/dev/null | sort -rh | head -10
412M    node_modules/
 38M    .git/
1.2M    __pycache__/

# NG例：ビルドのたびにタイムスタンプが変わるファイルをCOPY
# build-info.txt（内容例）: "Built at 2026-08-17 12:00:00"
COPY build-info.txt /app/

# 対処: .dockerignore で除外し、RUN で生成する方式に変更
# .dockerignore に追加:
#   build-info.txt

# Dockerfile 内で生成に変更:
RUN echo "Built at $(date)" > /app/build-info.txt

# NG: latestは予期しないタイミングでダイジェストが変わる
FROM python:latest

# OK: パッチバージョンまで固定して意図しないキャッシュ無効を防ぐ
FROM python:3.12.3-slim

# サイズの大きいレイヤーを上位5件表示
$ docker history --format "{{.Size}}	{{.CreatedBy}}" myapp:latest | sort -rh | head -5

# 実行結果の例
492MB   /bin/sh -c apt-get update && apt-get install -y build-essential gcc g++ cmake ...
134MB   /bin/sh -c pip install torch==2.1.0
 27MB   /bin/sh -c #(nop) ADD file:d37ff24540ea66a19...
8.2MB   /bin/sh -c pip install --no-cache-dir -r requirements.txt

# 命令全文を省略なしで表示する
$ docker history --no-trunc myapp:latest

# OK: ビルドコンテキスト（カレントディレクトリ）のルートに置く
$ ls -la
.dockerignore   ← ここに置く
docker/
  Dockerfile
src/

$ docker build -f docker/Dockerfile .

# 改行コードを確認する
$ file .dockerignore
.dockerignore: ASCII text, with CRLF line terminators

# LFに変換する（dos2unixが使える場合）
$ dos2unix .dockerignore

# dos2unixがない場合
$ sed -i 's/\r//' .dockerignore

# 変換後の確認
$ file .dockerignore
.dockerignore: ASCII text

# NG: ルート直下の __pycache__ しか除外できない
__pycache__

# OK: 全階層の __pycache__ を除外する
**/__pycache__