自分で書いた最初の Dockerfile をビルドして、docker images を見たときの数字がこれでした。
これは深掘りです。本線の順路ではありません。 本線のDocker導入の回で docker images の見方まで進んだ人が、「自分でビルドしたイメージが、公式の nginx より10倍大きい」ところで手が止まったときに読む記事です。飛ばしても本線は進みます。
この記事のコマンドは、すべて Ubuntu Server の中で打ちます。 Windows の PowerShell ではありません。 プロンプトが
ユーザー名@ホスト名:~$になっていれば、Linux の中にいます。 Docker が入っていることと、node -vが返ることが前提です。前者はDocker導入の回、後者はビルドツールの回で入れました。 この記事は~/sizelabという新しいフォルダの中だけで作業します。 これまでに作ったプロジェクトには一切触りません。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-api v1 3f8a1c9e2b04 12 seconds ago 1.21GB
nginx latest 6a1b7c3d9e51 3 weeks ago 192MB
アプリ本体は server.js 1ファイル、40行です。 それが 1.21GB になっている。公式の nginx が 192MB なのに、自分のは6倍以上でした。
最初は「そういうものか」と流していました。困り始めたのは、次の3つが同時に来たときです。
| 何が起きたか | なぜ大きさが効くのか |
|---|---|
| VM から別のマシンへイメージを送るのに数分かかる | 転送は圧縮しても実サイズに比例する |
| CI/CD で毎回 push するとレジストリが膨らむ | 1日に何十回も同じ 1.2GB を上げ下げしている |
docker system df が 20GB を超えて VM のディスクが埋まった | 消したつもりのイメージが層として残っていた |
そして一番大きいのは、大きさそのものではありません。 1.2GB の中身の 99% は、動かすのに要らないものだということです。コンパイラも、git も、npm のキャッシュも、テスト用のソースも、全部入ったまま本番に行く。それは全部「攻撃される面」です。
この記事は、削る前にまず測って、どの層が太っているかを特定するところから始めます。当てずっぽうで alpine にするのは、この記事ではやりません。
対象レベル: 中級〜上級 / 区分: 発展
この記事でわかること
docker imagesのSIZEは「そのイメージが占めているディスク量」ではないこと。層は共有されるので、単純に足すと実際の何倍にもなるalpineは「小さいslim」ではないこと。C言語の土台(libc)が別物なので、ネイティブモジュールのビルドが落ちる。無条件で選ぶものではないRUNを分けて書くと、後から消しても1バイトも減らないこと。層は追記しかできず、削除も「消したという記録」として積み上がる- マルチステージビルドが効くのは「小さくなるから」ではなく、「ビルドに使った道具を、次の段に持ち越さない」からであること
.dockerignoreはイメージではなく、まず転送量とビルド時間に効くことscratchや distroless にすると、docker execでシェルに入れなくなること。小ささには必ず代償がある
この記事でやること
~/sizelabに React(Vite)の小さなアプリと、Node.js の API を新規に作る- わざと太った Dockerfile を1本書いてビルドし、
docker historyとdiveでどの層が太っているかを特定する - ベースイメージを
node:22→-slim→-alpineと入れ替えて、3つのサイズを並べる - 不要物の削除と
.dockerignoreを足して、それぞれ何MB効いたかを測る - マルチステージビルドに書き換える。 React は
dist/だけを nginx へ、API は本番依存だけを残す - distroless と
scratchを1回だけ試し、シェルが無いことを確かめて、全部片づける
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| 層(レイヤー) | イメージは1枚の塊ではなく、命令ごとに積み重なった読み取り専用の薄い層の集まり。下の層は後から書き換えられない |
| ベースイメージ | FROM に書く土台。そこまでの層をそのまま引き継ぐので、ここの大きさがそのまま下限になる |
| ビルドコンテキスト | docker build に渡したフォルダの中身。ビルドを始める前に、まるごと Docker に転送される |
.dockerignore | ビルドコンテキストから除外するものを書くファイル。.gitignore と書き方が似ている |
| マルチステージビルド | 1つの Dockerfile に FROM を複数書き、前の段で作った成果物だけを次の段にコピーする書き方 |
| glibc / musl libc | どちらもC言語の標準ライブラリ(プログラムがOSを呼ぶときの土台)。普通の Linux は glibc、Alpine Linux は musl を使う。別物 |
| ネイティブモジュール | JavaScript ではなくC/C++で書かれていて、インストール時にコンパイルされる npm パッケージ。libc が違うと落ちる |
| distroless | Google が配っている、パッケージ管理もシェルも入っていない実行専用のイメージ群 |
scratch | 完全に空の特別なベースイメージ。中身はゼロバイト。実行ファイル1つだけを置くときに使う |
dive | イメージを層ごとに開いて、どのファイルが何バイト増えたかを見る道具 |
練習場を作る — 既存のプロジェクトには触らない
これまでに作ったフォルダは、この記事では一切使いません。 消したり作り直したりする手順が多いので、~/sizelab を新しく作って、その中だけで完結させます。
確認: pwd が /home/ユーザー名/sizelab になり、node と docker の両方がバージョンを返せば準備完了です。
node -vが「command not found」と返る場合は、ビルドツールの回で Node.js を入れてから戻ってきてください。
① Node.js の API を作る
中身は何でもいいので、40行くらいの JSON を返すだけの API にします。 本線のNode.js の API の回と同じ形です。
動くことを、Docker を使わずに先に確かめます。 コンテナに入れてから動かないと、原因がアプリなのか Dockerfile なのか分からなくなります。
別のターミナル、または Ctrl+C で止める前に、もう1枚 SSH で繋いで打ちます。
確認: JSON が3件返れば成功です。確認したら Ctrl+C で止めてください。
② React(Vite)の小さなアプリを作る
npm create vite@latest は対話で聞いてくることがあります。 -- --template react を付けているので、通常はテンプレートの質問は出ません。パッケージを落としてよいか聞かれたら y です。
ビルドが通ることを先に確かめます。
dist/index.html
dist/assets/index-Bx7d2f1a.js
dist/assets/index-9c31ab04.css
228K dist
187M node_modules
この2つの数字が、この記事の主役です。
本番で配るのに必要なのは
dist/の 228KB だけです。node_modulesの 187MB は、それを作るために使った道具であって、利用者のブラウザには1バイトも届きません。 ビルドツールの回で「dist/はただの静的ファイル」と書いた話が、ここでそのまま効いてきます。
[スクリーンショット: 01_dist_と_node_modules.png] du -sh dist node_modules の結果が、228K と 187M のように並んでいる部分を撮ってください。
① まず測る — 犯人を特定してから削る
ここが、この記事で一番言いたいところです。 サイズを小さくする記事を検索すると、いきなり「alpine を使いましょう」から始まります。それをやると、なぜ小さくなったのか分からないまま、alpine の代償だけを踏みます。
まず、わざと太らせた Dockerfile を1本書いてビルドします。 これが基準(before)になります。
初回は数分かかります。 node:22 のダウンロードだけで 1GB 近くあるためです。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-api v1 3f8a1c9e2b04 9 seconds ago 1.21GB
1.21GB です。 ここから始めます。
docker images の SIZE は「占有量」ではない
先に、この数字の読み方を直しておきます。 これを誤解していると、後の測定が全部ずれます。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-api v1 3f8a1c9e2b04 1 minute ago 1.21GB
node 22 b4e1a09c7d23 2 weeks ago 1.12GB
node 22-slim 9c02d7f13ba8 2 weeks ago 223MB
sizelab-api:v1 の 1.21GB と、node:22 の 1.12GB を足しても 2.33GB にはなりません。 sizelab-api:v1 は node:22 の層をそのまま使っているからです。実際に増えたのは差の 90MB 分だけです。
本当のディスク使用量は、こちらで見ます。
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 3 0 1.36GB 1.36GB (100%)
Containers 0 0 0B 0B
Local Volumes 0 0 0B 0B
Build Cache 18 0 214MB 214MB
| 見るもの | 意味 |
|---|---|
docker images の SIZE | そのイメージを1から取るとしたら何バイトか(他と共有している分も含む) |
docker system df の SIZE | 重複を除いた、実際のディスク使用量 |
RECLAIMABLE | 消せば戻ってくる量 |
この記事では「イメージのサイズ」=
docker imagesのSIZEで統一します。 他人に配るときに転送される量に近いのはこちらだからです。VM のディスクを気にするときだけdocker system dfを見ます。
docker history — どの命令が何バイト積んだか
イメージは層の積み重ねです。 どの層が太っているかは、これで一発で出ます。
IMAGE CREATED CREATED BY SIZE
3f8a1c9e2b04 2 minutes ago CMD ["node" "server.js"] 0B
<missing> 2 minutes ago EXPOSE map[3000/tcp:{}] 0B
<missing> 2 minutes ago RUN /bin/sh -c npm install 2.34MB
<missing> 2 minutes ago COPY . . # buildkit 84.7MB
<missing> 2 minutes ago WORKDIR /app 0B
<missing> 2 weeks ago /bin/sh -c #(nop) CMD ["node"] 0B
<missing> 2 weeks ago ... 1.12GB
読み方はこうです。
| 行 | 何が分かるか |
|---|---|
| 一番下の 1.12GB | FROM node:22 そのもの。自分では1行も書いていないのに、これが下限 |
COPY . . の 84.7MB | ローカルの node_modules を、まるごとイメージに入れてしまっている |
RUN npm install の 2.34MB | 既に node_modules があるので、ほとんど何もしていない |
0B の行 | メタデータだけ(CMD や EXPOSE は容量を持たない) |
犯人が2人、名前入りで出ました。
- ベースイメージ 1.12GB — 全体の 92%
COPY . .の 84.7MB —.dockerignoreを書いていないので、ホスト側のnode_modulesがそのまま入った
「なんとなく大きい」が「1.12GB と 84.7MB」に変わりました。 ここから先は、この2つを順に潰すだけの作業です。
dive を入れて、層の中身をファイル単位で見る
docker history は「どの命令が何バイトか」までしか分かりません。 層の中に何が入っているかを見るには dive を使います。
dive は Ubuntu の apt には入っていません。 配布元の .deb を1つ取って入れます。
sudo dpkg -iではなくsudo apt install ./ファイル名.debを使っています。./を付けてローカルファイルを渡すと、依存があっても apt が解決してくれます。
入れずに済ませたい場合は、コンテナで動かすこともできます。
これは Docker のソケットをコンテナに渡しています。 Docker導入の回で「
dockerグループは root と同じ」と書いた話と同じで、渡した相手にホストの全権を渡すのと同じです。自分の練習用 VM でだけやってください。
操作は3つだけ覚えれば十分です。
| キー | 動き |
|---|---|
Tab | 左(層の一覧)と右(ファイルツリー)を行き来する |
Ctrl+U | その層で増えたファイルだけを表示する(一番使う) |
Ctrl+C | 終了 |
COPY . . の層を選んで Ctrl+U を押すと、/app/node_modules が丸ごと並びます。 これが 84.7MB の正体です。
画面の右上に、こういう数字が出ます。
Image Details
Total Image size: 1.2 GB
Potential wasted space: 2.1 MB
Image efficiency score: 99 %
efficiency scoreを上げるのが目的ではありません。 これは「同じファイルを別の層で何度も置いていないか」の指標です。「そもそも要らないものが入っている」ことは検出できません。 実際、いま 99% と出ていますが、中身は 1.2GB のうち 99% が不要です。道具の数字を目的にしないでください。
[スクリーンショット: 02_dive_のレイヤー画面.png] dive sizelab-api:v1 で、左に層の一覧、右に node_modules が並んでいる画面を撮ってください。
② ベースイメージを変える
犯人の92%はベースイメージでした。 ここから手を付けます。
Node.js の公式イメージには、同じバージョンでも土台違いのタグがあります。
| タグ | 土台 | 何が入っているか |
|---|---|---|
node:22 | Debian(bookworm)フルセット | gcc・make・git・curl・python3 など開発道具が一式 |
node:22-slim | Debian を最小構成に削ったもの | Node.js を動かすのに要るものだけ |
node:22-alpine | Alpine Linux | Node.js + musl libc + BusyBox。土台そのものが別物 |
3つとも実際にビルドして、数字で並べます。
確認: それぞれ FROM node:22-slim と FROM node:22-alpine になっていれば成功です。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-api v3 7d2e91f0ac33 8 seconds ago 216MB
sizelab-api v2 a01c47b9e2fd 40 seconds ago 308MB
sizelab-api v1 3f8a1c9e2b04 6 minutes ago 1.21GB
1行変えただけで、1.21GB が 308MB になりました。
| Dockerfile | ベース | サイズ | v1 比 |
|---|---|---|---|
Dockerfile.v1 | node:22 | 1.21GB | — |
Dockerfile.v2 | node:22-slim | 308MB | −75% |
Dockerfile.v3 | node:22-alpine | 216MB | −82% |
3つとも同じように動くことを確かめます。
確認: 3つとも {"ok":true} を返せば、サイズが5分の1になっても動作は同じだと確かめられました。
alpine の代償 — musl libc
ここで「じゃあ全部 alpine でいい」とはなりません。 この記事の API は express しか使っていないので、たまたま動いただけです。
Alpine Linux は、C言語の標準ライブラリに glibc ではなく musl libc を使っています。 これは「小さい glibc」ではなく、別の実装です。
何が起きるか、実際に踏みます。 インストール時にC++のコンパイルが走るパッケージを1つ足してみます。
npm error gyp ERR! find Python
npm error gyp ERR! find Python Python is not set from command line or npm configuration
npm error gyp ERR! stack Error: Could not find any Python installation to use
npm error gyp ERR! not ok
ビルドが落ちました。狙いどおりです。
これは「エラーを直せば済む」話ではありません。 何が違うのかを分解します。
| 状況 | node:22 / node:22-slim | node:22-alpine |
|---|---|---|
| JavaScript だけのパッケージ | 動く | 動く |
| ネイティブモジュール(ビルド済みバイナリが配られている) | 公式が配っているのは glibc 版なので、そのまま使える | musl 版が無いことが多く、その場で全部コンパイルし直しになる |
| コンパイルに必要なもの | node:22 には最初から入っている | python3 make g++ を自分で足す必要がある |
「じゃあ足せばいい」をやってみます。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-alpine-fix latest ce41b3902da7 1 minute ago 464MB
通りましたが、464MB になりました。 node:22-slim(308MB)より大きいです。
これが alpine の一番よくある結末です。 「小さいから」で選んで、ビルドが落ちて、道具を足して、結果的に slim より大きくなる。 しかも
g++が入ったイメージを本番に出しているので、セキュリティの回で書いた「余計なものを置かない」に真っ向から反しています。
musl と glibc の違いは、大きさ以外にも出ます。
- DNS の引き方が違う。 検索ドメインの扱いが glibc と異なり、社内ネットワークで名前が引けないという形で出ることがあります
- スレッドのスタックが既定で小さい。 深い再帰や一部のライブラリで、glibc では動くものが落ちる
- 時刻の扱い(タイムゾーンデータ)が既定で入っていない。
tzdataを別途入れないと、日付と時刻の回で書いたずれ方をします
この記事の結論はこうです。
迷ったら
-slim。alpineを選ぶのは「ネイティブモジュールを1つも使っていないと確認できたとき」だけにします。-slimは Debian のままなので、普段の Ubuntu と同じ知識がそのまま通じます。aptも使えます。「調べたことがそのまま効く」というのは、サイズ以上に価値があります。
以降は node:22-slim(308MB, v2)を基準に進めます。
(sizelab-alpine-fail はビルドに失敗しているので No such image と返ります。それで正常です。)
③ 不要物を消す — 同じ RUN の中でないと消えない
次はイメージの中に残っているゴミです。 ここには層の性質そのものが関わってきます。
層は追記しかできません。 一度書き込まれた層は、後の層から書き換えられません。「消す」という操作は、「消したという印を上に重ねる」だけです。下の層のファイルは、そこに残ったままです。
これを実演します。 同じことをする Dockerfile を2本作って、RUN の分け方だけを変えます。
やっていることは1文字も違いません。 違うのは、3つを別々の RUN で書いたか、&& で1つの RUN にまとめたかだけです。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-clean good 1a0d7c93be82 5 seconds ago 331MB
sizelab-clean bad 5e9b2f10ca47 22 seconds ago 354MB
23MB 違います。 rm -rf を書いたのに、bad のほうは減っていません。
なぜかは docker history で目に見えます。
IMAGE CREATED CREATED BY SIZE
5e9b2f10ca47 1 minute ago CMD ["node" "-e" "console.log('ok')"] 0B
<missing> 1 minute ago RUN /bin/sh -c rm -rf /var/lib/apt/lists/* 0B
<missing> 1 minute ago RUN /bin/sh -c apt-get install -y curl 11.4MB
<missing> 1 minute ago RUN /bin/sh -c apt-get update 22.9MB
<missing> 2 weeks ago ... 223MB
rm -rf の層が 0B です。 そしてその下の apt-get update の層は 22.9MB のまま残っています。
IMAGE CREATED CREATED BY SIZE
1a0d7c93be82 1 minute ago CMD ["node" "-e" "console.log('ok')"] 0B
<missing> 1 minute ago RUN /bin/sh -c apt-get update && apt-get... 11.5MB
<missing> 2 weeks ago ... 223MB
good のほうは、3つの操作が1つの層(11.5MB)になっています。 層が閉じる前に消したので、消したものは最初から積まれていません。
これが「同じ
RUNの中で消さないと意味がない」の正体です。rmが効かないのではなく、rmの結果が「新しい層」として上に乗るだけです。下の層は誰も削れません。 後から「イメージが大きいからrmを足そう」は、原理的に効きません。 消したい層そのものを書き直すしかありません。
同じことが npm のキャッシュにも起きます。 npm install は ~/.npm にダウンロードしたパッケージを溜めます。これも同じ RUN の中で消します。
RUN npm ci --omit=dev && npm cache clean --force
apt-get の場合の定型はこの3つです。 意味は分けて覚えます。
| 書くもの | 何のためか |
|---|---|
apt-get update && apt-get install -y ... を同じ RUN に | 索引の取得とインストールを分けると、古い索引を使ってしまう。サイズ以前の問題 |
--no-install-recommends | 「推奨」扱いのパッケージまで入れない。 ドキュメントやエディタが芋づるで入るのを止める |
rm -rf /var/lib/apt/lists/* | apt-get update が取ってきた索引を消す。 コンテナの中で apt を使う予定が無いなら不要なもの |
alpine の apk には --no-cache という1語があります。 apk add --no-cache python3 と書くだけで、索引を残しません。先ほど alpine の例で使ったのはこれです。
④ .dockerignore の効果を測る
もう1人の犯人、COPY . . の 84.7MB に戻ります。
docker build は、最初に「ビルドコンテキスト」を Docker に転送します。 これは docker build の最後に書いた .(=カレントディレクトリ)の中身まるごとです。
まず、いま何が転送されているか測ります。
89M .
#1 [internal] load build context
#1 transferring context: 88.62MB 3.1s done
88.62MB を毎回送っています。 中身はほぼ node_modules です。
.dockerignore を書きます。
同じコマンドをもう一度打ちます。
#1 transferring context: 3.42kB done
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-api v2-ignored 0b8f39ce1d47 7 seconds ago 311MB
sizelab-api v2 a01c47b9e2fd 9 minutes ago 308MB
転送量は 88.62MB → 3.42kB。約26,000分の1です。
ところがイメージのサイズは、308MB → 311MB と、少し増えました。
驚くところですが、理由は単純です。
COPY . . で入るもの | RUN npm install | |
|---|---|---|
.dockerignore 無し | ホストで作った node_modules がそのまま入る | 既にあるので、ほぼ何もしない |
.dockerignore 有り | server.js と package.json だけ | コンテナの中で1から入れる → その分の層ができる |
つまり .dockerignore は、イメージを小さくする道具ではありません。
.dockerignoreの本当の効果は3つです。1. ビルドが速くなる。 88MB の転送が毎回消える
2..envや.gitをイメージに入れない。 これが一番大事です。COPY . .は.envも.gitも持っていきます。docker historyは誰でも読めます
3. ホストのnode_modulesを持ち込まない。 ホストが Windows や macOS だと、そこでビルドされたネイティブモジュールが Linux のコンテナで動きません
.git を入れてしまう危険は、実際に確かめられます。 Git の回で、履歴には消したはずのファイルも残っていると書きました。.git ごとイメージに入れると、過去に一度でもコミットした認証情報が、イメージを持っている全員に渡ります。
.dockerignore は、サイズのためではなく、事故を防ぐために必ず書きます。
⑤ マルチステージビルド
ここまでで 1.21GB → 308MB になりました。 しかし 308MB のうち、動かすのに要るのは何MBでしょうか。
node:22-slim には npm が入っています。 本番で npm は使いません。開発用の依存パッケージも入っています。 本番では読み込まれません。React 側に至っては、node_modules の 187MB が全部「ビルドの道具」です。
マルチステージビルドは、これを分けるための書き方です。
1つの Dockerfile に
FROMを複数書きます。 前の段(builder)で好きなだけ道具を入れてビルドし、最後の段には、できた成果物だけをCOPY --from=で持ってきます。 最後のFROMから下だけが、完成品のイメージになります。 前の段は丸ごと捨てられます。
React の場合 — dist/ だけを nginx に移す
まず、マルチステージにしない版を作って、比較の基準にします。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-web v1 2c7f04ab918e 30 seconds ago 1.43GB
1.43GB です。 中身は 228KB の dist/ と、それを作るための 1.43GB です。
動くことは確かめておきます。
確認: 200 が返れば動いています。
マルチステージに書き換えます。
この Dockerfile の読み方が、この記事の山場です。
| 行 | 何をしているか |
|---|---|
FROM node:22-slim AS builder | 1段目に builder という名前を付ける。 ここでは道具を好きなだけ使ってよい |
RUN npm ci | npm install ではなく npm ci。 package-lock.json の通りに、寸分違わず入れる |
RUN npm run build | /app/dist ができる。 ここまでが道具の世界 |
FROM nginx:alpine | ここで前の段を捨てて、まっさらから始める。 node も npm も、もう存在しない |
COPY --from=builder /app/dist /usr/share/nginx/html | builder の段の /app/dist を、いまの段にコピーする。 持ってくるのはこれだけ |
COPY --from=builder の左側は「builder という段の中のパス」、右側は「いま作っている段のパス」です。 ホストのファイルではありません。 ここは最初に必ず間違えます。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-web v2 9e3a08d1c745 12 seconds ago 51.8MB
sizelab-web v1 2c7f04ab918e 4 minutes ago 1.43GB
1.43GB → 51.8MB。 28分の1です。桁が2つ変わりました。
動くことを確かめます。
確認: 200 が返り、<!doctype html> から始まる HTML が出れば成功です。
中身が本当に dist/ だけになっているか、目で見ます。
index.html
assets
vite.svg
exit=1
node はもう入っていません。 ビルドには使ったのに、完成品には無い。 これがマルチステージの効き方です。
React Router を使っている場合は、これだけでは
/tasks/3を直接開くと 404 になります。 nginx に「知らない URL はindex.htmlを返す」と教える設定が別途必要です。この記事はサイズの話なので踏み込みませんが、「小さくしたら壊れた」の代表例なので覚えておいてください。
[スクリーンショット: 03_web_v1とv2のサイズ比較.png] docker images sizelab-web で、v1 の 1.43GB と v2 の 51.8MB が並んでいる部分を撮ってください。
Node.js の API の場合 — npm ci --omit=dev
React は「成果物が静的ファイルだけ」なので極端に効きました。 API は Node.js 本体が必要なので、そこまでは減りません。 それでも削れるものがあります。
まず、開発用の依存を1つ入れて、差が出る状態を作ります。
devDependencies に vitest が入りました。 テスト用なので、本番のコンテナでは1度も読み込まれません。
3段になりました。 増えた分の意味はこうです。
| 段 | 役割 | なぜ分けるか |
|---|---|---|
builder | 全部の依存を入れて、テストやビルドをする段 | vitest はここでだけ要る |
deps | --omit=dev で本番依存だけを入れ直す段 | builder の node_modules には dev が混ざっている。持ってきてはいけない |
| 最終段 | node_modules と server.js だけを受け取る | npm を1度も使わない。ソースの余計なファイルも入らない |
npm ci と npm install の違いも、ここで効きます。
| 挙動 | |
|---|---|
npm install | package.json を見て解決する。package-lock.json を書き換えることがある |
npm ci | package-lock.json の通りに入れる。 node_modules を消してから入れ直す。ロックと package.json がずれていたら失敗する |
コンテナのビルドでは常に npm ci です。 npm の回で「package-lock.json はコミットする」と書いた理由が、ここで回収されます。ロックが無いと、同じ Dockerfile が来月には別のものを作ります。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-api v4 4b19d7ce03a2 10 seconds ago 241MB
sizelab-api v2 a01c47b9e2fd 14 minutes ago 308MB
sizelab-api v1 3f8a1c9e2b04 23 minutes ago 1.21GB
308MB → 241MB。 派手ではありませんが、中身の質が変わっています。
確認: JSON が返り、最後の行が NO-VITEST になれば、開発用の依存が入っていないことが確かめられました。
USER nodeを1行入れました。 これはサイズの話ではありませんが、node:系の公式イメージには最初からnodeという一般ユーザーが用意されています。 既定のままだとコンテナの中で root で動きます。 権限の回の話と同じで、要らない権限は最初から持たないのが原則です。
⑥ distroless と scratch — どこまで削れるか
241MB のうち、Node.js 本体と Debian の土台が大部分です。 ここを削る道具が2つあります。
distroless — シェルもパッケージ管理も無い
Google が配っている distroless は、「言語のランタイムと、それが必要とするライブラリだけ」のイメージです。 apt も sh も ls も入っていません。
CMD の書き方が違います。 ["node", "server.js"] ではなく ["server.js"] です。distroless の nodejs イメージは、node が最初から起動コマンドとして設定されているためです。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-api v5 d70c1a3b8f92 6 seconds ago 174MB
241MB → 174MB。動きます。
代償を確かめます。
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh": executable file not found in $PATH: unknown
中に入れません。 sh が存在しないからです。
本線のDocker導入の回で docker exec -it web bash を打ちました。 あの手が使えなくなります。
| 使えなくなるもの | 代わりにどうするか |
|---|---|
docker exec -it ... bash | docker logs と、アプリ自身が出す /health のようなエンドポイントで見る |
curl でコンテナの中から疎通確認 | 別のコンテナを同じネットワークに立てて、そこから叩く |
ls でファイルの有無を見る | docker cp でホストに取り出す |
本番に出すなら distroless は良い選択です。 練習中の VM で、まだ何度も中を覗きたい段階では、
-slimのほうが学習効率が高いと思っています。「本番用は distroless、開発用は slim」と Dockerfile の段を分けるのが実務でよく見る形です。
scratch — 実行ファイル1つなら数MB
ここで Go の回が回収されます。
あの回で、Go の実行ファイルに ldd を打ったら not a dynamic executable と返りました。 外から読むものが何も無い、という意味でした。そのとき「だから土台すら要らない」と書きました。それを実際にやります。
| 書いたもの | 意味 |
|---|---|
CGO_ENABLED=0 | C言語のコードを一切使わずにビルドする。 これを付けないと glibc に依存した実行ファイルになり、scratch では動きません |
-ldflags="-s -w" | デバッグ用の情報を実行ファイルから落とす。 数MB効きます |
FROM scratch | 完全に空の土台。 ファイルは1つも入っていない |
Go をホストに入れる必要はありません。 ビルドも golang:1.27 のコンテナの中で行われます。
REPOSITORY TAG IMAGE ID CREATED SIZE
sizelab-go scratch 8f1e0b47a2c9 4 seconds ago 6.71MB
6.71MB です。 最初の 1.21GB の 180分の1です。
確認: JSON が返れば、OSのファイルが1つも入っていないイメージでプログラムが動いたことになります。
scratchが使えるのは、静的リンクされた実行ファイル1つで完結する言語だけです。Go や Rust では現実的、Node.js や Python では不可能です。インタプリタ本体と大量のファイルが要るからです。 代償は distroless より重いです。シェルが無いのはもちろん、TLS の証明書も、タイムゾーンのデータも、/tmpすらありません。 HTTPS で外部 API を叩くだけでx509: certificate signed by unknown authorityが出ます。証明書は自分でCOPYして入れる必要があります。
⑦ 最終的な比較 — 小ささは目的ではない
ここまでの実測を全部並べます。
| # | 手法 | イメージ | サイズ | 手間 | 代償 |
|---|---|---|---|---|---|
| 1 | そのまま | node:22 | 1.21GB | なし | 全部入り。中身の99%が不要 |
| 2 | ベースを -slim に | node:22-slim | 308MB | 1行 | ほぼ無し。まずこれをやる |
| 3 | ベースを -alpine に | node:22-alpine | 216MB | 1行 | musl。ネイティブモジュールで落ちる |
| 4 | alpine + ビルド道具 | node:22-alpine | 464MB | 数行 | slim より大きい。本末転倒 |
| 5 | 不要物を同じ RUN で消す | node:22-slim | −23MB | 数文字 | 無し。必ずやる |
| 6 | .dockerignore | — | ±0MB | 数行 | 無し。サイズではなく事故防止のためにやる |
| 7 | マルチステージ(API) | node:22-slim | 241MB | 中 | 書き方を覚える必要がある |
| 8 | マルチステージ(React → nginx) | nginx:alpine | 51.8MB | 中 | SPA のルーティング設定が別途要る |
| 9 | distroless | distroless/nodejs22 | 174MB | 小 | シェルが無い。docker exec できない |
| 10 | scratch(Go) | scratch | 6.71MB | 中 | 証明書・TZ・シェルが全部無い。言語を選ぶ |
この表から読み取ってほしいのは、順位ではありません。
「1行で75%減る手(#2)」と「書き方を覚える必要がある手(#7・#8)」は、費用が全然違います。 どこまでやるかは、何に困っているかで決まります。
サイズを小さくする目的は、3つしかありません。
| 目的 | 何がどう良くなるか |
|---|---|
| 転送時間 | CI/CD で毎回 push/pull する。レジストリの容量も減る。Kubernetes で Pod が別のノードに移るとき、イメージを取り直すのが起動時間 |
| 攻撃される面 | 入っていないものは、脆弱性を持てない。 curl も gcc も sh も無ければ、侵入されても次の手が打てない |
| ディスク | VM やビルドマシンが埋まらない |
逆に言えば、この3つで困っていないなら、-slim にして .dockerignore を書いて終わりで十分です。
小ささを競うと、必ずどこかで壊れます。 alpine にしてネイティブモジュールが落ちる。
scratchにして HTTPS が通らない。distroless にしてデバッグできなくなる。 この記事で全部やったのは、「壊れ方を先に知っておくため」です。本番で最初に選ぶのは #2 + #5 + #6 + #8 の組み合わせで、それで大半は足ります。
つまずいたところ
最初にやったのは、当てずっぽうの alpine でした。 サイズの記事を3つ読んで、全部 alpine と書いてあったので、何も測らずに FROM node:22-alpine にしました。ビルドが落ちて、エラーを検索して、apk add python3 make g++ を足して、通って、満足していました。 後で測ったら slim より大きかったと分かったのは、この記事を書くために全部並べたときです。測っていなかったので、間違いに気付く機会がありませんでした。
rm -rf が効かないのは、しばらく信じられませんでした。 「消したのにサイズが変わらない」ので、キャッシュのせいだと思って --no-cache を付けて何度もビルドし直しました。 変わりません。docker history を見て rm の層が 0B になっているのを見て、やっと「層は後から削れない」という一文の意味が分かりました。説明としては読んだことがあったのに、自分の症状と結び付いていませんでした。
COPY --from=builder のパスを、ホストのパスだと思っていました。 COPY --from=builder ./dist /usr/share/nginx/html と書いて、"/dist": not found で落ちました。--from を付けた瞬間に、左側は「その段の中のパス」になります。 ホストのファイルシステムとは無関係です。/app/dist と絶対パスで書くようにしてから、間違えなくなりました。
マルチステージにしたのに、全然小さくならないことがありました。 最終段で COPY --from=builder /app /app と書いていました。/app ごと持ってきていたので、node_modules の dev 依存もソースも全部入っていました。 持ってくるものを1行ずつ列挙する、が正解でした。「builder から持ってくる」ではなく「builder から何を持ってくるか」です。
docker images の合計を足して、ディスクが足りないと騒ぎました。 v1 から v5 まで並べて合計 2.1GB だと思っていたのに、df -h を見ると 1.4GB しか減っていない。層が共有されているという話を、数字で確かめて初めて理解しました。docker system df を先に覚えていれば、混乱しませんでした。
docker image rm したのに容量が戻りませんでした。 ビルドキャッシュが残っていました。docker system df の Build Cache の行が 3GB を超えていたのに、Images の行だけを見ていました。docker builder prune を知らなかったのが原因です。
後片づけ
この記事は10個以上のイメージを作りました。全部消します。 練習用の VM でも、ビルドキャッシュを含めて数GBになっています。
まず、何が残っているかを目で見ます。
確認: docker ps -a に api- や web- や go- で始まるものが残っていたら、次で消します。
コンテナを止めて消す
既に消したものは No such container と返ります。 それで正常です。 docker ps -a が空(ヘッダ行だけ)になれば成功です。
作ったイメージを全部消す
確認: grep sizelab が何も返さなければ、作ったイメージは全部消えています。
引っ張ってきたベースイメージも消す
これは残しても構いません。 次に Docker を触るときに再ダウンロードが要らなくなります。VM のディスクが厳しいときだけ消してください。
ビルドキャッシュを消す
ここが一番容量を持っています。 消し忘れると、後日「何も無いのにディスクが無い」になります。
確認: Build Cache の SIZE が 0B になっていれば成功です。
docker system prune -aという一括のコマンドもあります。 停止中のコンテナ・使われていないイメージ・ネットワーク・ビルドキャッシュを全部消します。 強力すぎるので、この記事では使いません。 他の練習で作ったものまで消えます。
練習場のフォルダを消す
確認: ls ~ に sizelab が無く、これまでに作った他のフォルダがそのまま残っていれば片づけ完了です。
dive を消す
残しておくと、今後イメージを調べるときに便利です。 消す場合はこちらです。
まとめ
- 削る前に測る。
docker historyで「どの命令が何バイト積んだか」を見れば、犯人は必ず1つか2つに絞れる docker imagesのSIZEは占有量ではない。 層は共有される。実際のディスク使用量はdocker system dfdocker historyで0Bの行はメタデータ。 一番下の巨大な行がFROMそのもので、そこが下限になるdiveは層の中身をファイル単位で見る道具。Ctrl+Uで「その層で増えたもの」だけが出る。efficiency scoreは目的ではない- ベースイメージを変えるのが一番効く。
node:22(1.21GB)→node:22-slim(308MB)は 1行で75%減 alpineは「小さい slim」ではない。 musl libc という別の土台で、ネイティブモジュールのビルドが落ちる- alpine で落ちて
python3 make g++を足すと、slim より大きくなる。 しかも本番にコンパイラを出荷している - 迷ったら
-slim。 Debian のままなので、Ubuntu で覚えたことがそのまま通じる - 層は追記しかできない。 後の
RUNでrmしても、下の層のファイルは残る。rmの層が0Bになるのがその証拠 - 消すなら同じ
RUNの中で。apt-get update && apt-get install -y --no-install-recommends ... && rm -rf /var/lib/apt/lists/*を1つのRUNに npm cache clean --forceも同じRUNの中で。 別の行に書いたら1バイトも減らない.dockerignoreはサイズのためではない。.envと.gitをイメージに入れないため。docker historyは誰でも読める.dockerignoreの実測効果は、転送 88.62MB → 3.42kB。 ビルド時間に効く- マルチステージは「ビルドの道具を持ち越さない」書き方。
FROMを複数書き、最後のFROMから下だけが完成品 COPY --from=builderの左側は「その段の中のパス」。 ホストのパスではない。絶対パスで書く- 持ってくるものは1行ずつ列挙する。
/appごとコピーすると、dev 依存もソースも全部付いてくる - React は
dist/だけを nginx に移す。 1.43GB → 51.8MB。28分の1。完成品にnodeは1バイトも入らない - API は
npm ci --omit=devの段を分ける。 builder のnode_modulesには dev が混ざっているので、そこからコピーしてはいけない - コンテナのビルドでは常に
npm ci。package-lock.jsonが無いと、同じ Dockerfile が来月には別のものを作る - distroless はシェルが無い。 174MB になる代わりに
docker exec ... shが使えなくなる scratchは完全に空。 Go でCGO_ENABLED=0なら 6.71MB。証明書もタイムゾーンも/tmpも無いscratchが使えるのは静的リンクできる言語だけ。 Node.js や Python では不可能- 小ささが目的ではない。目的は転送時間と攻撃面。 困っていないなら
-slim+.dockerignore+ マルチステージで十分 - 後片づけは
docker builder pruneまで。docker imagesを空にしてもビルドキャッシュは残る
参考リンク
- roadmap.sh — DevOps
- Docker 公式 — マルチステージビルド
- Docker 公式 — Dockerfile の書き方のベストプラクティス
- Docker 公式 — Dockerfile リファレンス
- Docker 公式 — ビルドコンテキスト
- Docker Hub — node イメージ
- Docker Hub — nginx イメージ
- GoogleContainerTools/distroless
- wagoodman/dive
- musl libc — glibc との機能差の一覧
- npm ドキュメント — npm ci
- Vite 公式 — 本番ビルド
次に読む
この記事は 【深掘り】Docker の 4 / 11 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- ベースイメージの選び方(slim / alpine)
- マルチステージビルドと distroless
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント