レイヤーキャッシュの仕組み — 行の順番でビルド時間が決まる

レイヤーキャッシュ。行の順番で、ビルドが変わる。青い層の上に浮かぶオレンジの層とストップウォッチ。

命令を書く順番でビルド時間が変わります。レイヤーキャッシュの仕組みを、実際に測って確かめます。

前回: Dockerfileの命令を1つずつ読む — EXPOSEを書いてもポートは開かない

これは深掘りです。本線の順路ではありません。 本線のDockerの導入の回でコンテナを動かせるようになった人が、「自分のアプリをイメージにしたら、1文字直すたびに2分待たされる」ところで止まったときに読む記事です。飛ばしても本線は進みます。

この記事のコマンドは、すべて Ubuntu Server の中で打ちます。 Windows の PowerShell ではありません。 プロンプトが ユーザー名@ホスト名:~$ になっていれば、Linux の中にいます。 本線で作った ~/server には一切触りません。 練習用に ~/cachelab を新しく作って、そこだけで完結させます。

自分のアプリを初めてイメージにしたとき、こうなりました。

bash
$ docker build -t myapp .
(1分52秒)

1回目はそういうものだと思いました。 問題は次でした。server.js の文字列を1つだけ書き換えて、もう一度ビルドする。

bash
$ docker build -t myapp .
(1分48秒)

4秒しか縮んでいません。 ソースコードは1文字しか変わっていないのに、インターネットから依存パッケージを丸ごと取り直しているわけです。「Docker は遅い」「VM だから遅い」と思っていました。

どちらも違いました。原因は Dockerfile の行の順番です。 実際、この記事でやる3行の並べ替えで、同じビルドが 1分48秒 → 1.4秒になります。約77倍です。

そして大事なのは速さそのものではなく、なぜそうなるのかが、はっきり決まった規則で説明できることです。規則を知らないうちは、速くなったり遅くなったりする理由が分からず、「たまたま速い日」を待つことになります。

対象レベル: 中級〜上級 / 区分: 発展

目次

この記事でわかること

  • Docker のビルドは、Dockerfile の1行ごとに結果を保存していること。だから行の順番が実行時間を決めること
  • ある行のキャッシュが外れると、その行より下は全部やり直しになること。上に戻ることはない
  • COPY はファイルの中身のハッシュで判定していて、タイムスタンプは見ていないこと(touch してもキャッシュは外れない)
  • RUN は「文字列が前と同じか」しか見ていないこと。だから apt-get update の行は、何ヶ月前の索引でも「同じ」と判定されて使い回される
  • npm install と npm ci は別のコマンドで、package-lock.json があるなら ci を使うべき理由が「速いから」ではないこと
  • CI(GitHub Actions など)には、そもそもキャッシュが1つも無いこと。手元で速くしても、CI は毎回まっさらから始まる

この記事でやること

  1. 練習用の小さな Node.js アプリを ~/cachelab に新しく作る(依存を3つ入れる)
  2. わざと遅い Dockerfile を書いて、time でビルド時間を実測する
  3. 3行を入れ替えただけの Dockerfile で同じ測定をやり直し、数字を表で並べる
  4. docker build --progress=plain で、どの行がキャッシュに当たったかを目で読む
  5. touch と1文字修正で、キャッシュが外れる条件を実験で確かめる
  6. --no-cache と --build-arg でわざと外し、後片づけをする

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
レイヤーイメージを構成する差分の1枚。Dockerfile の RUN / COPY などの命令1つが、だいたい1枚に対応する
レイヤーキャッシュ前回のビルドで作ったレイヤーを、条件が同じなら作り直さずに再利用するしくみ
キャッシュヒット / ミス再利用できた / できなかった。ミスした行から下は、全部作り直しになる
ビルドコンテキストdocker build . の . の部分。このディレクトリの中身が、まるごと Docker に送られる
.dockerignoreビルドコンテキストに含めないものを書くファイル。.gitignore と書き方が似ている
BuildKitいまの Docker が既定で使っているビルドの実行部分。古いビルダーとはキャッシュの扱いが違う
package-lock.jsonnpm が作る、依存パッケージの版を1つに固定した記録。詳しくは本線のnpmの回

練習用のアプリを作る

本線で作った ~/server は使いません。 壊すと本線の続きができなくなるからです。~/cachelab を新しく作ります。

bash
$ mkdir ~/cachelab
$ cd ~/cachelab

Node.js が入っているか確かめます。本線のAPIの回で入れているはずです。

bash
$ node -v
$ npm -v

確認: 両方ともバージョン番号が返れば大丈夫です。command not found なら、本線のAPIの回に戻ってください。

package.json

ファイルは全文を置きます。 nano package.json で開いて、そのまま貼り付けてください。

bash
$ nano package.json
{
  "name": "cachelab",
  "version": "1.0.0",
  "private": true,
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.19.2",
    "morgan": "^1.10.0",
    "dayjs": "^1.11.11"
  }
}

依存を3つ入れているのは、わざとです。 1つも無いと npm install が一瞬で終わってしまい、キャッシュが効いているのかどうかが数字に出ません。

server.js

bash
$ nano server.js
const express = require('express');
const morgan = require('morgan');
const dayjs = require('dayjs');

const app = express();
app.use(morgan('tiny'));

const MESSAGE = 'hello from cachelab';

app.get('/', (req, res) => {
  res.json({
    message: MESSAGE,
    now: dayjs().format('YYYY-MM-DD HH:mm:ss')
  });
});

app.listen(3000, () => {
  console.log('listening on 3000');
});

あとで書き換えるのは MESSAGE の1行だけです。ここが「コードを1文字直す」の実験台になります。

package-lock.json を作る

bash
$ npm install

確認: package-lock.json と node_modules ができていれば成功です。

bash
$ ls
node_modules  package-lock.json  package.json  server.js

package-lock.json は、あとで npm ci を使うために必要です。 ここで一度だけ、VM の中で普通に npm install して作っておきます。

.dockerignore を先に置く

これを忘れると、この記事の実験そのものが成立しません。

bash
$ nano .dockerignore
node_modules
npm-debug.log
.git
Dockerfile
.dockerignore

理由は2つあります。

  • node_modules は数千〜数万ファイルあります。 ビルドコンテキストは丸ごと Docker に送られるので、これがあるだけで毎回数秒〜数十秒を捨てることになります
  • node_modules の中身は、npm を動かすたびに少しずつ変わります。 それを COPY . . で持ち込むと、何もしていないのにキャッシュが外れるという、原因の分からない状態になります

さらに、ホストで作った node_modules をコンテナに持ち込むのは、そもそも間違いです。 ネイティブモジュールを含むパッケージはOSとCPUに合わせてビルドされているため、環境が違えば動きません。コンテナの中で入れ直すのが正しいです。

① わざと遅い Dockerfile を書いて、時間を測る

まず、多くの人が最初に書く形をそのまま書きます。これが「遅い版」です。

bash
$ nano Dockerfile
FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]

読むと、何も間違っていないように見えます。 ファイルを全部置いて、依存を入れて、起動する。手作業でやる順番そのものです。

1回目を測る

time を頭に付けるだけで、かかった時間が出ます。

bash
$ cd ~/cachelab
$ time docker build -t cachelab:slow .

docker を打つと permission denied が出る場合は、本線の導入の回でやった docker グループへの追加が効いていません。一度ログアウトして入り直すか、コマンドの先頭に sudo を付けてください。

出力の最後に、こう出ます。

real    1m52.417s
user    0m0.108s
sys     0m0.061s

見るのは real だけです。 これが「実際に待たされた時間」です。user と sys が0秒に近いのは、待っているのは docker コマンド自身ではなく、裏で動いているビルダーだからです。

[スクリーンショット: 01_slow_build_time.png] time docker build -t cachelab:slow . を実行し、最後に real の行が出ている画面を撮ってください。

コードを1文字だけ直して、もう一度測る

bash
$ nano server.js

MESSAGE の行だけを、こう書き換えます。

const MESSAGE = 'hello from cachelab v2';

保存したら、まったく同じコマンドを打ちます。

bash
$ time docker build -t cachelab:slow .
real    1m48.902s
user    0m0.099s
sys     0m0.055s

4秒しか減っていません。 出力をよく見ると、npm install の行がまた全部流れています。

なぜこうなるのか。

COPY . .          ← server.js が変わった → ここでキャッシュが外れる
RUN npm install   ← 外れた行より下は、全部やり直し

これがこの記事で一番大事な規則です。

ある行でキャッシュが外れたら、そこから下の行は、内容が同じでも全部作り直される。

RUN npm install という文字列は1文字も変わっていないのに、作り直されます。上の行が変わったからです。逆に言えば、上の行さえ変わらなければ、下の行は再利用されます。

② 3行を入れ替えて、もう一度測る

やることは、順番を変えるだけです。

bash
$ nano Dockerfile
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]

変えたのは「依存の定義だけを先に持ち込んで、先に入れる」という一点だけです。

  • COPY package*.json ./ — package.json と package-lock.json だけを入れる。* を使っているのは、この2つをまとめて拾うため
  • RUN npm install — この行より上には、アプリのコードが1行も来ていない。だからコードを直しても、この行のキャッシュは外れない
  • COPY . . — 残りを全部入れる。ここでキャッシュが外れても、下には CMD しか無い

公平に測るために、一度キャッシュを捨てる

さっきのビルドのキャッシュが残ったままだと、1回目の比較になりません。

bash
$ docker builder prune -f

確認: Total reclaimed space: ... と出れば、ビルドのキャッシュが消えています。

docker builder prune はビルドのキャッシュだけを消します。 イメージやコンテナは消えません。docker system prune -a は打たないでください。 本線で作った ~/server 関連のイメージまで消えます。

bash
$ time docker build -t cachelab:fast .
real    1m55.238s

1回目は、むしろ少し遅いです。 ここで諦める人がいますが、1回目が速くなる話ではありません。

2回目 — コードを1文字直す

bash
$ nano server.js
const MESSAGE = 'hello from cachelab v3';
bash
$ time docker build -t cachelab:fast .
real    0m1.418s

1.4秒です。

[スクリーンショット: 03_fast_build_time.png] 並べ替え後の time docker build -t cachelab:fast . で real 0m1.4xxs のように出ている画面を撮ってください。

3回目 — 依存を1つ足す

「コードを直したときだけ速い」のかどうかを確かめます。 package.json に cors を足します。

bash
$ nano package.json

dependencies を、こう書き換えます。

  "dependencies": {
    "express": "^4.19.2",
    "morgan": "^1.10.0",
    "dayjs": "^1.11.11",
    "cors": "^2.8.5"
  }

package-lock.json を更新します。

bash
$ npm install
$ time docker build -t cachelab:fast .
real    1m50.771s

依存を変えたときは、ちゃんと遅くなります。 これは正しい動きです。依存が変わったのだから、入れ直すべきです。

数字を並べる

この記事の実機(VM 2コア / メモリ4GB)ではこうなりました。 絶対値は環境で変わりますが、比が変わらないことが大事です。

何をしてから測ったか遅い順番(COPY . . が先)良い順番(COPY package*.json が先)
① 初回(キャッシュ無し)1分52秒1分55秒
② server.js を1文字直した後1分48秒1.4秒
③ 依存を1つ足した後1分51秒1分50秒

読み取ることは3つです。

  • ①は変わらない。 キャッシュの話は「2回目以降」の話であって、初回を速くする方法ではない
  • ②が本番。 開発中に一番多いのは「コードだけ直す」で、そこが 77倍違う
  • ③は同じでいい。 依存が変わったときに入れ直すのは、サボってはいけない仕事

③ どの行がキャッシュに当たったのか読む

「速くなった」で終わらせると、遅くなったときに何も分かりません。 どの行が再利用されたかは、目で読めます。

bash
$ docker build --progress=plain -t cachelab:fast .

出力に、こういう行が並びます。

#8 [3/5] COPY package*.json ./
#8 CACHED

#9 [4/5] RUN npm install
#9 CACHED

#10 [5/5] COPY . .
#10 DONE 0.1s

CACHED と書いてある行が、再利用された行です。 DONE は実際に実行された行です。

[スクリーンショット: 02_cached_progress_plain.png] docker build --progress=plain の出力で CACHED の行と DONE の行が両方見えているところを撮ってください。

読み方は「上から見て、最初に CACHED でなくなった行を探す」だけです。そこがキャッシュの切れ目で、そこから下は全部やり直されています。

--progress=plain を付けないと、既定では動く進捗表示になり、終わった行が畳まれて消えます。 原因を追うときは必ず付けてください。

④ キャッシュが外れる条件を、正確に

ここまでを「コードを直すと COPY のキャッシュが外れる」と覚えると、半分間違えます。 命令の種類で判定のしかたが違うからです。

命令何を見て「同じ」と判定するか
COPY / ADD入れるファイルの中身のハッシュ(+パーミッションなどの属性)
RUNDockerfile に書かれた文字列が前回と同じか。それだけ
すべて共通1つ上のレイヤーが同じかどうか

実験1 — touch してもキャッシュは外れない

「更新日時が変わったから作り直される」と思っていました。確かめます。

bash
$ cd ~/cachelab
$ touch server.js
$ docker build --progress=plain -t cachelab:fast . 2>&1 | grep -E "CACHED|DONE"

server.js の更新日時は、いま変わりました。それでも COPY . . の行は CACHED のままです。

次に、中身を1文字だけ変えます。

bash
$ nano server.js
const MESSAGE = 'hello from cachelab v4';
bash
$ docker build --progress=plain -t cachelab:fast . 2>&1 | grep -E "CACHED|DONE"

今度は COPY . . が CACHED ではなくなります。

COPY はタイムスタンプを見ていません。中身のハッシュを見ています。

これが分かると、「触っただけのファイルが混ざっていてもいい」と分かります。逆に、内容が1バイトでも違えば、見た目が同じでも外れます。

実験2 — RUN は文字列しか見ていない

ここが、実務で一番刺さる落とし穴です。 こういう Dockerfile を考えます。

FROM node:22-slim
RUN apt-get update
RUN apt-get install -y --no-install-recommends curl

この形は、動く日と動かない日があります。

apt-get update は、パッケージの索引(どのバージョンがどこにあるか、の一覧)を取ってくるコマンドです。本線のパッケージ管理の回で扱ったとおり、ソフト本体は更新しません。

問題は、Docker が RUN apt-get update を「文字列が同じだから前と同じ」と判定することです。

  • 3ヶ月前にビルドしたときの apt-get update の結果が、そのまま再利用される
  • その古い索引には、いまはもう存在しないバージョンが書いてある
  • 下の行の apt-get install が 404 Not Found で落ちる

Docker は「このコマンドはネットから最新を取ってくるものだ」ということを知りません。 知りようがありません。文字列を比べているだけだからです。

対策は1つです。同じ RUN に入れる。

RUN apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*

こうすると update と install が1枚のレイヤーになり、片方だけ古いという状態が作れません。 rm -rf /var/lib/apt/lists/* は、もう使わない索引をイメージに残さないためです。

この書き方は、apt-get に限りません。 「外の世界を見に行く行」は、それを使う行と必ず同じ RUN にまとめる、と覚えてください。

実験3 — 上が外れれば、下は必ず外れる

もう一度確かめます。 Dockerfile の WORKDIR /app を WORKDIR /srv/app に変えて、ビルドしてください。

bash
$ nano Dockerfile
FROM node:22-slim
WORKDIR /srv/app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]
bash
$ time docker build -t cachelab:fast .

2行目を変えただけで、また2分近くかかります。 COPY も RUN も1文字も変えていません。

元に戻しておいてください。

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]

キャッシュは「その行だけ」では決まりません。 その行までの積み重ね全体が同じかどうかで決まります。だから変わりやすいものほど下に書く、が原則になります。

変わる頻度で並べると、こうなります。

上から順に変わる頻度
FROM(ベースイメージ)数ヶ月に一度
OSのパッケージを入れる RUN数ヶ月に一度
COPY package*.json ./ → RUN npm install依存を足したとき
COPY . .(アプリのコード)1日に何十回も

⑤ npm install と npm ci

ここまで npm install を使ってきました。package-lock.json があるなら、Dockerfile で使うべきなのは npm ci です。

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]

「ci のほうが速いから」ではありません。 理由は再現性です。

npm installnpm ci
何を見るかpackage.json(^4.19.2 のような範囲)package-lock.json(確定した版)
lock ファイル書き換えることがある書き換えない。合っていなければエラーで止まる
node_modules差分を足す一度消してから入れ直す
lock が無いとき作るエラーで止まる

^4.19.2 は「4.19.2 以上、5.0.0 未満」という意味です。 つまり npm install は、同じ package.json から、日によって違う版を入れます。

手元では 4.19.2、3週間後のビルドでは 4.21.0。 これが「手元では動くのに、ビルドしたイメージだけ落ちる」の正体になります。npm ci は lock に書いてある版しか入れないので、いつ何回やっても同じものが入ります。

「lock がずれていたらエラーで止まる」のは、不便ではなく機能です。 package.json だけ直して lock を更新し忘れたまま出荷する、という事故がビルドの時点で止まります。

bash
$ nano Dockerfile

上の npm ci 版に書き換えて、動くことを確かめます。

bash
$ docker builder prune -f
$ time docker build -t cachelab:fast .

確認: エラーなく終われば成功です。npm ci can only install packages when your package.json and package-lock.json are in sync と出たら、npm install を1回打って lock を更新してから、やり直してください。

動作も確かめておきます。

bash
$ docker run --rm -d -p 3000:3000 --name cachelab cachelab:fast
$ curl http://localhost:3000
{"message":"hello from cachelab v4","now":"2026-09-21 14:03:11"}
bash
$ docker stop cachelab

失敗したときの戻し方: docker stop cachelab で止まらないときは docker rm -f cachelab を打ってください。イメージは残りますが、後片づけの節で消します。

⑥ わざとキャッシュを外す

キャッシュは、効かせるだけでなく「意図して外す」ほうも要ります。 外し方は2つあり、効く範囲が違います。

全部外す — --no-cache

bash
$ time docker build --no-cache -t cachelab:fast .

1行目から全部やり直します。 毎日使うものではありません。使うのはこの3つの場面だけです。

使う場面なぜ
リリース用のイメージを作るとき古い索引や古いベースが混ざっていないことを保証したい
「手元では通るのに変だ」を切り分けるときキャッシュのせいなのか、コードのせいなのかを分ける
FROM のタグを更新したとき(node:22-slim の中身が変わったとき)タグは同じでも中身は入れ替わる

3つ目は分かりにくいので補足します。 node:22-slim は同じ名前のまま中身が更新されます。 手元にあるものが使われ続けるので、docker pull node:22-slim を先に打つか、docker build --pull を付けます。

途中から外す — --build-arg

「FROM からやり直したくはないが、この行から下だけはやり直したい」というときがあります。ARG を使います。

FROM node:22-slim
ARG CACHEBUST=0
RUN echo "cachebust=$CACHEBUST" \
 && apt-get update \
 && apt-get install -y --no-install-recommends curl \
 && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]
bash
$ docker build --build-arg CACHEBUST=$(date +%s) -t cachelab:fast .

$(date +%s) は「いまの時刻を秒で表した数」です。 打つたびに違う値になります。

仕組みはこうです。 ARG の値が変わると、それを使っている RUN の文字列が変わったのと同じ扱いになります。だから ARG を書いた場所より下だけがやり直され、FROM とその上は再利用されます。

ARG を書く位置が、そのまま「ここから下を捨てる」という線になります。 上に書けば広く、下に書けば狭く捨てられます。

注意: ARG の値は docker history で見えます。パスワードやトークンを --build-arg で渡さないでください。 秘密を渡す方法は別にあります(BuildKit の --secret)。

この節の Dockerfile は実験用です。 curl はこの記事では使わないので、⑤の npm ci 版に戻してから先へ進んでください。

⑦ CI にはキャッシュが無い

ここまでの話は、全部「手元のマシンに前回の結果が残っている」前提です。

本線のGitHub ActionsとCI/CDの回で使ったランナー(ワークフローを実行するマシン)は、毎回まっさらな状態で起動して、終わったら消えます。

CI には、前回のビルドのレイヤーが1枚も残っていません。

つまり、手元で1.4秒になったビルドが、CI では毎回2分かかります。 「行の順番を直したのに CI が速くならない」は、設定漏れではなく、そういう仕組みです。

解決は「キャッシュを外に置いて、毎回持ってくる」です。

  • --cache-from — すでにあるイメージを、キャッシュの元として使う。レジストリに上げた前回のイメージを指定する
  • --cache-to — 今回作ったキャッシュを、外に書き出す

GitHub Actions では、公式のアクションが GitHub のキャッシュ置き場(type=gha)を使えます。ワークフローに足すのは、この2行です。

      - uses: docker/build-push-action@v6
        with:
          context: .
          cache-from: type=gha
          cache-to: type=gha,mode=max

mode=max は「途中のレイヤーも全部書き出す」という指定です。 既定の min は最終レイヤーしか保存しないので、途中でキャッシュが切れたときに効きません。

ただし、いいことばかりではありません。

  • キャッシュのダウンロードにも時間がかかります。 依存が小さいプロジェクトでは、取ってくるほうが遅いことがあります
  • GitHub のキャッシュには容量の上限があり、古いものから消えます。 週に1回しか動かないワークフローでは、毎回キャッシュが無いということが起こります

だから「入れれば速くなる」ではなく、入れる前と後で時間を測ってください。 手元で time を打ったのと同じことです。測らずに設定を足すのは、この記事の逆をやっていることになります。

イメージをどこに置くかという話は、本線のレジストリの回にあります。

⑧ BuildKit の RUN --mount=type=cache

npm ci は、依存が変わるたびに毎回インターネットから取り直します。 ここまでの構成では、それは避けられません。レイヤーのキャッシュは「行が同じなら丸ごと再利用」しかできないからです。

BuildKit(いまの Docker が既定で使っているビルダー)には、もう一段別のしくみがあります。

# syntax=docker/dockerfile:1
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
CMD ["node", "server.js"]

1行目の # syntax=docker/dockerfile:1 は、コメントではなく指定です。 この行があると、ビルドの前に最新の安定版の Dockerfile 構文を取ってきて解釈します。--mount は構文 1.2 以降の機能なので、無い場合は Docker に同梱された版で解釈され、古い Docker では通らないことがあります。必ずファイルの1行目に置いてください。

/root/.npm は、npm がダウンロードしたパッケージを溜めている場所です。ここをビルドをまたいで持ち越すと、依存を1つ足しただけのときに、残りの依存はネットに取りに行かなくなります。

bash
$ nano Dockerfile
$ docker builder prune -f
$ time docker build -t cachelab:cache .

そのあと package.json に依存を1つ足して、もう一度測ってみてください。「依存を変えたら毎回2分」だったところが、目に見えて縮みます。

ここで必ず押さえること。

--mount=type=cache の中身は、イメージのレイヤーには入りません。

ビルド中だけ見える置き場です。だから、

  • イメージは大きくなりません(キャッシュがイメージに焼き付かない)
  • docker save や docker push で他のマシンに持っていっても、キャッシュは付いてきません
  • CI では、⑦の type=gha とは別枠です。何もしなければ、CI では毎回空です

「イメージの中に入っていない」ことを確かめるなら、こう打ってください。

bash
$ docker run --rm cachelab:cache ls /root/.npm
ls: cannot access '/root/.npm': No such file or directory

ビルド中にあれだけ使った場所が、出来上がったイメージには存在しません。 これが「レイヤーに残らない」という意味です。

つまずいたところ

最初、COPY . . を上に書いていることが問題だと気付くまでに、何日もかかりました。 やっていたのは「npm install を速くする方法」の検索です。ミラーサーバーを変えたり、--prefer-offline を付けたりしていました。速くしようとしていた行は、そもそも実行される必要が無かったわけです。遅い原因を、遅い行の中に探していました。

.dockerignore を書き忘れて、1日つぶしました。 行を並べ替えたのに 2回目が速くならない。--progress=plain を打ったら COPY . . が毎回 CACHED になっていない。ホストの node_modules が、npm を打つたびに少しずつ変わっていたのが原因でした。中身のハッシュで判定されると知っていれば、すぐ分かったはずです。規則を知らないと、症状から原因に戻れません。

apt-get update の問題は、他人のリポジトリで踏みました。 3ヶ月前まで通っていたビルドが、コードを1行も変えていないのに 404 で落ちる。「GitHub Actions が壊れた」と思って半日調べました。Dockerfile の RUN apt-get update が、古い索引のまま CACHED になっていただけです。CI では毎回まっさらだと思い込んでいたのですが、そのときはキャッシュを設定してあったので、まっさらではありませんでした。

--no-cache を癖で付けるようになった時期があります。 「これを付ければ確実」だからです。確実ですが、毎回2分です。 1日に30回ビルドすれば1時間になります。確実さと速さのどちらを取るかを、場面ごとに決めていないだけでした。いまは手元では付けない、リリースでは付けるにしています。

ARG を FROM の上に書いて、効かなくて悩みました。 FROM より前に書いた ARG は、FROM の行でしか使えません(ベースイメージの名前を変数にするためのもの)。ビルドの中で使うなら FROM より後に書く必要があります。「どこに書くか」が「どこから下を捨てるか」だと分かってから、迷わなくなりました。

--mount=type=cache を入れて、イメージが小さくなると思っていました。 関係ありません。ビルドが速くなるだけです。逆に「キャッシュがイメージに入って重くなる」と心配していた時期もあり、どちらも間違いでした。ls /root/.npm を打って、自分の目で確かめるまで納得できませんでした。

後片づけ

この記事で作ったものを、全部消します。~/server には触りません。

まず、何ができたかを目で見ます。

bash
$ docker image ls | grep cachelab
$ docker ps -a | grep cachelab
$ ls ~/cachelab

コンテナを止めて消す

bash
$ docker rm -f cachelab

確認: docker ps -a | grep cachelab が何も返さなければ成功です。まだ動いていた場合でも、-f で止めて消します。

イメージを消す

bash
$ docker image rm cachelab:slow cachelab:fast cachelab:cache

No such image が出るものがあっても構いません。 作らなかったタグです。

ベースイメージも消すなら、こうします。

bash
$ docker image rm node:22-slim

残しておいても害はありません。 次に Node.js のイメージを作るときに、また取り直さずに済みます。VM のディスクが厳しいときだけ消してください。

ビルドキャッシュを消す

bash
$ docker builder prune -f

確認: Total reclaimed space: 1.2GB のように、回収した容量が出ます。この数字が、この記事で溜めたキャッシュの大きさです。

いま何が残っているかは、これで見えます。

bash
$ docker system df

練習場を消す

bash
$ rm -rf ~/cachelab

確認: ls ~ に cachelab が無く、server が残っていることを確かめてください。

bash
$ ls ~

server が消えていたら、消すディレクトリを間違えています。 その場合は本線のGitHubに上げる回で上げたリポジトリから git clone で戻せます。

まとめ

  • ビルドが遅いのは Docker のせいではなく、Dockerfile の行の順番のせい。 直すのは1箇所で、効果は測れる
  • キャッシュは行ごとに保存され、外れた行より下は全部やり直される。 上に戻ることはない
  • だから「変わりやすいものほど下に書く」。 ベースイメージ → OSのパッケージ → 依存の定義 → アプリのコード、の順
  • COPY は中身のハッシュで判定する。 touch では外れず、1バイト違えば外れる
  • RUN は文字列が同じかどうかだけを見る。 中で何をしているかは知らない
  • だから apt-get update は、何ヶ月前の索引でも「同じ」として使い回される。 update と install は必ず同じ RUN にまとめる
  • .dockerignore に node_modules を書く。 書かないと何もしていないのにキャッシュが外れるという、原因の分からない状態になる
  • package-lock.json があるなら npm ci。 速さの話ではなく、同じ版が入ることを保証する話
  • --no-cache は全部、--build-arg は書いた ARG より下だけを捨てる。 手元では使わず、リリースと切り分けで使う
  • --build-arg の値は docker history で見える。 秘密を渡してはいけない
  • CI には前回のレイヤーが1枚も無い。 手元が速くなっても CI は毎回まっさら。--cache-from / type=gha で外に置く
  • キャッシュを外に置いても、取ってくる時間はかかる。 入れる前と後で必ず測る
  • RUN --mount=type=cache は、ビルド中だけの置き場。 イメージのレイヤーには残らないし、push しても付いてこない
  • # syntax=docker/dockerfile:1 を1行目に書いておくと、--mount などの新しい構文を Docker の版に左右されずに使える
  • 速くなったかどうかは、time と --progress=plain で確かめる。 CACHED が並んでいるかを目で読む

参考リンク


次に読む

この記事は 【深掘り】Docker の 3 / 11 本目です。

記事
← 前の記事Dockerfileの命令を1つずつ読む — EXPOSEを書いてもポートは開かない
→ 次の記事Dockerイメージを小さくする — 1.2GBが50MBになる

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

DevOps›Docker — Layer Caching
  • 行の順番でビルド時間が変わる
  • CIでのキャッシュと BuildKit

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次