メインコンテンツまでスキップ

第12章：BuildKitの必殺技①：キャッシュマウント入門 🧠✨

この章はひとことで言うと―― **「依存インストールの“ダウンロード地獄”を、BuildKitの力でだいぶ減らす」**回です📦⚡️

🎯 この章でできるようになること​

  • RUN --mount=type=cache が 何を速くするのか を説明できるようになる😊
  • Dockerfileに たった1行 足して、npm ci / npm install の体感速度を上げる🚀
  • レイヤキャッシュとキャッシュマウントの違いで迷わなくなる🧩

1) まずイメージ：レイヤキャッシュ vs キャッシュマウント 🧱🆚🧠​

ざっくり図にするとこう👇

【レイヤキャッシュ】（Dockerの基本）
- 命令と入力が同じなら、そのRUN自体を丸ごとスキップできる（超速い）
- でも、いったんキャッシュが壊れると、また全部やり直しになりがち

【キャッシュマウント】（BuildKitの必殺技）
- RUNは実行される（レイヤキャッシュが壊れても実行されることはある）
- でも「ダウンロード済みの置き場」を残しておけるので、再DLが減って速くなる

Docker公式の説明もまさにこれで、**キャッシュマウントは“パッケージキャッシュを永続化して、再ビルド時の再ダウンロードを減らす”**ための仕組みです。(Docker Documentation)

2) 最小レシピ：npmのダウンロードキャッシュを残す 🍳📦​

Docker公式の例はこれ👇（/root/.npm が npm のデフォルトキャッシュ）(Docker Documentation)

## syntax=docker/dockerfile:1
FROM node:lts-bookworm-slim
WORKDIR /app

COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci

COPY . .
RUN npm run build

ポイントは3つだけ😍

  1. # syntax=docker/dockerfile:1 を先頭に置く（最新の安定Dockerfile構文を使うおまじない）(GitHub)
  2. package*.json を先に COPY（依存の層をキャッシュしやすく）(Docker Documentation)
  3. RUN --mount=type=cache,target=/root/.npm ...（ダウンロード置き場を残す）(Docker Documentation)

3) 🧪 ミニ演習：速くなったのを“数字で”見る ⏱️📈​

Step A：計測コマンド（Windows / PowerShell）​

Measure-Command { docker build -t cachemount-demo . }

Step B：3回ビルドして差を見る​

1回目：もちろん遅い（初回DLがある）😅 2回目：速くなる（DL済みが再利用されやすい）⚡️ 3回目：ここが面白い👇 --no-cache を付けて レイヤキャッシュをわざと無効化しても、DLが減って速くなることがある✨（＝キャッシュマウントの勝ち筋）

Measure-Command { docker build --no-cache -t cachemount-demo . }

レイヤキャッシュは「RUN自体をスキップ」、キャッシュマウントは「RUNはやるけどDLが減る」。役割が違うって体感できたら勝ち🏆

4) よくある落とし穴集 🕳️😵‍💫​

❌ (1) RUN --mount がエラーになる​

原因はだいたいこれ：BuildKitでビルドされてない（古いビルダーを踏んでる）💥 対策はまず # syntax=docker/dockerfile:1 を入れるのが安定です。(GitHub)

❌ (2) キャッシュ先がズレてて効いてない​

  • 例：USER node にしてるのに target=/root/.npm のまま → その場合、キャッシュは /home/node/.npm 側が使われがちです👀 （困ったらコンテナ内で npm config get cache を見て合わせるのが確実👍）

❌ (3) “キャッシュがある前提”でビルドが壊れる​

BuildKitの仕様として、キャッシュマウントは性能改善のためのもので、内容が別ビルドに上書きされたり、GCで消えることもあります🧹 だから キャッシュが空でも、汚れてても、ビルドが成立する作りが大事です。(GitHub)

5) ちょい理解を上げる：オプション早見 🧩✨​

BuildKitのDockerfileリファレンスに載ってる「使えるつまみ」は主にこれ👇(GitHub)

  • target=...：キャッシュとして使うパス

  • id=...：キャッシュの名前（省略すると基本 target がid扱い）

  • sharing=shared|private|locked：同時ビルド時の扱い

    • locked は apt など “同時アクセスが危ない系”で重要（公式例でも sharing=locked が出ます）(Docker Documentation)

たとえば「ステージをまたいで同じnpmキャッシュを共有したい」なら、id= を付けるとわかりやすいです😊

RUN --mount=type=cache,id=npm-cache,target=/root/.npm npm ci

6) 🤖 AI活用（コピペでOK）🧠🧰​

①「自分のDockerfileに最小で入れて」プロンプト​

次のDockerfileで、npmのダウンロードキャッシュをBuildKitの cache mount で効かせたいです。
最小変更の差分（diff形式）で提案してください。
また、USER切り替えがある場合は npm cache の target パスも合わせてください。

②「効いてるか確認ポイントだけ教えて」プロンプト​

RUN --mount=type=cache を入れました。
効果確認のために、WindowsのPowerShellでできる計測手順（Measure-Command）と、
--no-cache を使った確認観点を短く箇条書きで教えてください。

✅ まとめ（ここだけ覚えればOK）🎁​

  • RUN --mount=type=cache は **“再ビルド時の再DLを減らす”**技🧠✨ (Docker Documentation)
  • # syntax=docker/dockerfile:1 を入れると安定しやすい📌 (GitHub)
  • キャッシュは あくまで加速装置。空でも壊れないDockerfileにするのが正解✅ (GitHub)

次の章（第13章）は、このキャッシュマウントを pnpmのストアに当てて「さらに気持ちいい速度」にする定番レシピへ進みます🍳🏎️💨