bind mountを使うと、node_modulesが消えます。開発時のワークフローを、実際に踏んでから直します。
これは【深掘り】の記事です。本線の順路ではありません。 読まなくても先へ進めます。 本線の コンテナは軽い仮想マシンではない — Dockerの導入 の続きとして、そこでは「イメージを作って動かす」までしかやっていない部分を、毎日コードを書く側からやり直す回です。
この記事のコマンドは、断りがない限りすべてVMの中(Ubuntu Server)で打ちます。 前提: Dockerの導入を終えて、
docker psがsudoなしで通ること。 前提2: APIの正体はJSONを返すHTTP と node_modulesは消してよい を読んでいると、この記事の題材がそのまま読めます。 本線で作ったものには触りません。 練習用に~/devlabを新しく作って、そこだけで完結させます。
Docker を覚えた直後、私は毎日こうしていました。
コードを1行直す。保存する。ターミナルに戻る。
docker compose build
docker compose up -d
40秒待つ。 ブラウザを再読み込みする。文字が1つ違う。また直す。また40秒待つ。
1日で何十回もやりました。「Docker を使うと開発が遅くなる」と本気で思っていました。
違いました。開発中にイメージを作り直すのは、そもそも間違いです。 イメージを作り直すのは「配る形にするとき」の作業で、書いている最中にやることではありません。書いている最中は、ホストのソースをコンテナの中に見せて、直したら即座に反映させるのが正しい形です。
ただし、その形にするとほぼ全員が同じ事故を踏みます。 node_modules が消えるやつです。この回は、そこを含めて全部踏みに行きます。
対象レベル: 中級〜上級 / 区分: 発展
この記事でわかること
- 開発中に
docker buildを繰り返すのは、道具の使い方が間違っている。ビルドは「配るとき」の作業 - ソースを bind mount すると、コンテナの中の
node_modulesがホスト側のもので覆い隠されて「消える」。これは Docker の不具合ではなく、マウントの定義どおりの動作 - ホストで
npm installしたものは、コンテナの中で動くとは限らない。ネイティブモジュールはOSとlibcに合わせて作られている - ファイル変更が検知されないのは、共有フォルダ越しだとOSの通知イベントが飛んでこないから。監視方式を変えれば直る
--inspectは既定で127.0.0.1にしか口を開けない。コンテナの中の127.0.0.1は外から届かない- 開発用と本番用は同じ Dockerfile で書ける。マルチステージの「途中の段」を名前で選ぶ
- 開発で当たり前にやっていることの大半は、本番でやると穴になる
この記事でやること
~/devlabに小さな Node.js のAPIを作り、直すたびにビルドし直す遅さを一度体験する- ソースを bind mount して、
--watchで自動再起動させる node_modulesが消える事故を実際に起こして、匿名ボリュームで覆って直す- 変更が検知されない場合に、ポーリング監視へ切り替える
--inspect=0.0.0.0:9229と VS Code の attach で、コンテナの中にブレークポイントを掛けて止めるdocker compose watchを使い、syncとrebuildの違いを確かめる- 開発用と本番用を
targetで分けて、最後に片づける
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| ホットリロード | ソースを保存した瞬間に、動いているプログラムへ反映させること。ここでは「保存したら自動で再起動」の意味で使う |
| bind mount | ホストの特定のフォルダを、コンテナの中の場所に直接見せる方式。中身はホスト側が正 |
| 匿名ボリューム | 名前を付けずに作られる Docker 管理の保存領域。-v /app/node_modules のように行き先だけ書くと作られる |
| ネイティブモジュール | JavaScript ではなくC/C++で書かれ、インストール時に機械語へコンパイルされる部品。bcrypt などが該当 |
| libc | OSが用意する基本の関数集。Ubuntu は glibc、Alpine は musl で別物 |
| inotify | Linux が「このファイルが変わった」とプログラムに知らせる仕組み。共有フォルダ越しには飛ばないことがある |
| ポーリング | 通知を待たず、自分から定期的に見に行く方式。確実だが遅く、CPUを食う |
| Inspector プロトコル | Node.js が持つデバッグ用の通信口。ポート 9229 で待ち受ける |
| attach(アタッチ) | 既に動いているプロセスに、あとからデバッガを繋ぐこと。プログラムを起動し直さない |
| マルチステージビルド | 1つの Dockerfile に複数の FROM を書き、段ごとに名前を付けて使い分ける書き方 |
① 練習用のAPIを作り、「毎回ビルドし直す」を一度だけ体験する
まず作業場所を作ります。本線で作ったものとは別のフォルダです。
package.json を作ります。
{
"name": "devlab",
"version": "1.0.0",
"type": "module",
"scripts": {
"start": "node src/server.js",
"dev": "node --watch src/server.js"
}
}
次にAPI本体です。
import http from 'node:http';
const PORT = 3000;
function totalPrice(items) {
let total = 0;
for (const item of items) {
total += item.price * item.count;
}
return total;
}
const server = http.createServer((req, res) => {
console.log(`${req.method} ${req.url}`);
if (req.url === '/health') {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ status: 'ok' }));
return;
}
if (req.url === '/total') {
const items = [
{ name: 'coffee', price: 480, count: 2 },
{ name: 'bagel', price: 320, count: 1 }
];
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ total: totalPrice(items) }));
return;
}
res.writeHead(404, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ error: 'not found' }));
});
server.listen(PORT, '0.0.0.0', () => {
console.log(`listening on 0.0.0.0:${PORT}`);
});
server.listenの第2引数に0.0.0.0を書いています。 ここを省略したり127.0.0.1と書いたりすると、コンテナの外から繋がりません。 理由は localhostで繋がらないのは当然 でやったとおりです。
Dockerfile を、まず素朴に書きます。
FROM node:22-alpine
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "src/server.js"]
ビルドして動かします。
{"total":1280}
ここまでは本線でやったとおりです。 問題はここからです。total の計算に消費税を足したくなったとします。src/server.js の totalPrice を1行直します。
return Math.round(total * 1.1);
そして反映させます。
{"total":1280}
変わりません。 当然です。コンテナの中で動いているのは、ビルドした瞬間にコピーされたファイルであって、いま編集したファイルではありません。反映させるには、
{"total":1408}
この3行を、1文字直すたびに打っていました。 1回あたり数十秒。1日100回直せば、それだけで1時間が消えます。
なぜ
COPY . .の行でキャッシュが効かないのかは レイヤーキャッシュは行の順番で決まる でやりました。ソースをコピーした行より下は毎回やり直しになります。キャッシュを整えても、この待ち時間はゼロにはなりません。
② ソースを bind mount して、直したら即反映させる
発想を変えます。 ビルドのたびにソースを「焼き込む」のをやめ、ホストのフォルダをコンテナの中に見せるようにします。
-v ホストの場所:コンテナの中の場所 が bind mount です。中身の正はホスト側になります。詳しくは コンテナを消すとデータも消える を見てください。
ソースを直します。今度は税率を 1.08 に変えてみます。
{"total":1408}
まだ変わりません。 ここが2段構えになっているところです。
- ファイルは確かに入れ替わっています。 それは確認できます
return Math.round(total * 1.08);
- しかし Node.js は、起動したときに読んだものをメモリに持ったままです。ファイルが変わっても勝手には読み直しません
つまり bind mount は「ファイルを届ける」ところまでしかやってくれないということです。読み直させる担当が別に要ります。
--watch で再起動させる
Node.js 18.11 以降には --watch が入っています。外部のツールを入れなくてもよくなりました。
最後の
node --watch src/server.jsは、イメージに書いてあるCMDを上書きしています。docker runの引数の順番については docker runの長い1行が読めない を見てください。
確かめます。
{"total":1382}
{"total":1408}
ビルドせずに変わりました。 ログにも再起動が残っています。
Restarting 'src/server.js'
listening on 0.0.0.0:3000
これが開発中の正しい形です。 docker build は、ライブラリを足したときにだけ打ちます。
③ node_modules が消える — 全員が踏む事故
ここまでは src だけをマウントしていたので何も起きませんでした。しかし、ふつうはこう書きたくなります。
「package.json を直したときも反映してほしいから、フォルダごとマウントしよう」
その前に、ライブラリを1つ入れておきます。
{
"name": "devlab",
"version": "1.0.0",
"type": "module",
"dependencies": {
"dayjs": "1.11.13"
},
"scripts": {
"start": "node src/server.js",
"dev": "node --watch src/server.js"
}
}
src/server.js の先頭に1行足して、使います。
import dayjs from 'dayjs';
そして /health の応答に時刻を混ぜます。
res.end(JSON.stringify({ status: 'ok', now: dayjs().format('YYYY-MM-DD HH:mm:ss') }));
イメージを作り直します。ライブラリを足したときは、ここは必要です。
さて、フォルダごとマウントします。
node:internal/modules/esm/resolve:283
throw new ERR_MODULE_NOT_FOUND(
^
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dayjs' imported from /app/src/server.js
イメージの中には確かに入れたのに、無いと言われます。
中を見ると、はっきりします。
Dockerfile
node_modules
package.json
src
Dockerfile
package.json
src
node_modules が消えています。
なぜ消えるのか
消えていません。隠れています。
bind mount は「ホストのフォルダを、コンテナの中のその場所にかぶせる」動作です。/app にホストの ~/devlab をかぶせた瞬間、/app から見えるものは、ホストの ~/devlab の中身がすべてになります。イメージに入っていた /app/node_modules は、下敷きになって見えなくなります。
ホスト側には node_modules がありません(VMでは npm install していないので)。だから無いものが見えているわけです。
これは Docker の不具合ではありません。 「かぶせる」という定義そのままの動きです。知らないと絶対に分からないだけです。
直しかた — 匿名ボリュームで覆い返す
かぶせられたのなら、その1か所だけを、さらにかぶせ返します。
{"status":"ok","now":"2026-09-23 06:11:42"}
動きました。
-v /app/node_modules は、コロンが無く、行き先だけを書いています。これは「この場所には、Docker が管理する入れ物を置け」という指定で、匿名ボリュームが作られます。
大事なのは順番ではなく深さです。マウントはパスの深いほうが勝ちます。
| 場所 | 何が見えるか |
|---|---|
/app | ホストの ~/devlab(bind mount) |
/app/node_modules | 匿名ボリューム(より深いので、こちらが勝つ) |
そして匿名ボリュームは、中身が空のときに限り、イメージの同じ場所にあったものが最初にコピーされます。 だからイメージのビルド時に npm install した結果がそこに現れます。
確かめます。
.package-lock.json
dayjs
DRIVER VOLUME NAME
local 8f3c1a...(長い16進数)
匿名ボリュームは、コンテナを消しても残ります。
docker rm -fを繰り返していると静かに溜まります。消すときはdocker rm -vを使うか、あとでdocker volume pruneします(この記事の後片づけでやります)。
Compose で書くなら、こうなります。
services:
app:
build: .
volumes:
- ./:/app
- /app/node_modules
リストの2行目、コロンの左が無い行が匿名ボリュームです。この1行の意味を知らずにコピーしている人が多いところです。
④ ホストとコンテナでOSが違うと、ネイティブモジュールが壊れる
「じゃあ、ホスト側で npm install して、その node_modules をそのまま使えばいいのでは」
そう思うのが自然です。そして、そこが2つ目の罠です。
VM(Ubuntu)側で入れてみます。
.package-lock.json
dayjs
これで匿名ボリュームを外しても動きます。
{"status":"ok","now":"2026-09-23 06:18:05"}
動いてしまいます。 dayjs は純粋な JavaScript だけでできているからです。ファイルをどこにコピーしても同じように動きます。
問題は、C/C++で書かれたライブラリを入れたときに起きます。パスワードのハッシュに使う bcrypt などが該当します。これらは npm install したその瞬間に、その環境向けに機械語へコンパイルされます。
つまり、
どこで npm install したか | できあがる部品 |
|---|---|
| VM(Ubuntu / glibc) | glibc 向けのバイナリ |
コンテナ(node:22-alpine / musl) | musl 向けのバイナリ |
| Windows 本体 | Windows 向けのバイナリ(拡張子は同じ .node だが、中身は Windows の DLL 形式) |
この3つは互換ではありません。 ホストで作ったものをコンテナに見せると、こういうエラーになります。
Error: Error loading shared library ld-linux-x86-64.so.2: No such file or directory
あるいは、
Error: /app/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node:
invalid ELF header
invalid ELF headerは「バイナリの形式が違う」という意味です。 Windows でnpm installしたものを Linux コンテナに持ち込むと、これがよく出ます。ライブラリを疑う前に、どこで install したかを疑ってください。
結論はこうです。
node_modulesはホストとコンテナで共有しない。 匿名ボリュームで分ける(③でやったこと)- ホスト側の
node_modulesは、エディタの補完のためだけに置く。動かすのはコンテナの中のもの - どちらか片方だけを正にする。 混ぜたときだけ壊れる
いま VM 側に作ってしまった node_modules は、混乱の元なので消しておきます。
消して構いません。 node_modules は package.json から何度でも作り直せます(node_modulesは消してよい)。
そして .dockerignore を置いて、うっかりホストの node_modules がイメージに入らないようにします。
node_modules
npm-debug.log
.git
.env
これはイメージを小さくするためだけの話ではありません。 ホスト側の(壊れているかもしれない)
node_modulesがCOPY . .で持ち込まれるのを防ぐためです。イメージの大きさについては 1.2GBのイメージが50MBになる を見てください。
⑤ ファイルを直しても、再起動してくれない
ここまでは順調に動いたはずです。ところが、環境によっては②の時点で再起動しません。
listening on 0.0.0.0:3000
ファイルを直しても、Restarting の行が出ません。 docker exec で中を見るとファイルは確かに変わっているのに、です。
何が起きているか
--watch も nodemon も、内部では inotify(Linux の「ファイルが変わった」通知)を使っています。この通知は、書き換えたのと同じOSのカーネルの中でしか飛びません。
だから、こういう経路だと通知が届きません。
| 経路 | 変更が検知されるか |
|---|---|
VM の中の ~/devlab を、VM 内のコンテナへ bind mount | 検知される(同じカーネル) |
| Windows のフォルダを VMware の共有フォルダ越しにマウント | 飛ばないことが多い |
| ネットワークドライブ・NFS・SMB 越し | 飛ばない |
| Docker Desktop(Windows / macOS)でホストのフォルダをマウント | 仕組み次第。落ちることがある |
ファイルは届いているのに、届いたことを知らせる人がいない状態です。
直しかた — 自分から見に行く(ポーリング)
通知が来ないなら、定期的に自分で見に行けばよいということになります。それがポーリングです。
node --watch にはポーリングへ切り替える設定がありません。ここは nodemon に替えます。
{
"name": "devlab",
"version": "1.0.0",
"type": "module",
"dependencies": {
"dayjs": "1.11.13"
},
"devDependencies": {
"nodemon": "3.1.7"
},
"scripts": {
"start": "node src/server.js",
"dev": "nodemon src/server.js"
}
}
devDependencies に入れています。 本番のイメージには入れたくないからです(⑧でその分け方をやります)。
Dockerfile の npm install --omit=dev は開発ツールを落としてしまうので、開発用には向きません。ここも⑧で分けますが、いまは確かめるためにこう打ちます。
CHOKIDAR_USEPOLLING=true は、nodemon が内部で使っている chokidar というファイル監視ライブラリへの指示です。「通知を待たず、1秒ごとに全部見に行け」という意味になります。
[nodemon] restarting due to changes...
[nodemon] starting `node src/server.js`
listening on 0.0.0.0:3000
今度は反応しました。
ポーリングは最後の手段です。 ファイル数が多いと常時CPUを食い続けます(
node_modulesを監視対象から外していないと顕著です)。まず通知方式で試し、動かないときだけ切り替えてください。そして、そもそも Windows 側のフォルダをVMへ共有して開発しないのが一番きれいな解です。ソースはVMの中に置き、VS Code の Remote – SSH でVMの中を直接編集すると、この問題は最初から起きません。
[スクリーンショット: 01_nodemon再起動ログ.png] docker logs -f devlab を出したまま別の端末でソースを保存し、[nodemon] restarting due to changes... が流れた瞬間を撮ってください。
⑥ コンテナの中の Node.js にデバッガを繋ぐ
console.log を挟んで、docker logs で見る。しばらくはそれで足ります。 ですが、変数が10個あるときや、ループの3周目だけおかしいときには限界が来ます。
動いているプロセスを止めて、その場の変数を全部見たい。 それがデバッガです。
--inspect を開く。0.0.0.0 にしないと届かない
Node.js は --inspect を付けると、ポート 9229 でデバッガの接続を待ちます。
まず、間違ったほうを先にやります。
Debugger listening on ws://127.0.0.1:9229/2f0c...
For help, see: https://nodejs.org/en/docs/inspector
VM から繋ぎに行きます。
curl: (56) Recv failure: Connection reset by peer
ポートは -p 9229:9229 で公開したのに、繋がりません。
理由は1行目に書いてあります。ws://127.0.0.1:9229。
127.0.0.1 は「自分自身」という意味です。そしてコンテナの中の「自分自身」は、コンテナの中だけを指します。ホストから来た通信は、コンテナの外側の口(0.0.0.0 側)に届くので、127.0.0.1 でしか待っていないプロセスには渡りません。
これは本線の nginx でも同じ形で出ました。
-pは「コンテナの外の口とコンテナの中の口を繋ぐ」だけで、中のプロセスがどの住所で待つかまでは面倒を見ません。 詳しくは localhostで繋がらないのは当然。
待ち受ける住所を明示します。
Debugger listening on ws://0.0.0.0:9229/9a41...
[ {
"description": "node.js instance",
"devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?ws=localhost:9229/9a41...",
"id": "9a41...",
繋がりました。
| 書き方 | 誰から繋げるか |
|---|---|
--inspect | コンテナの中からだけ(既定は 127.0.0.1:9229) |
--inspect=0.0.0.0:9229 | コンテナの外から繋げる |
--inspect-brk=0.0.0.0:9229 | 同上。ただし1行目を実行する前で止まって待つ。起動直後の処理を追いたいとき |
VS Code から attach する
ここだけ Windows 側の VS Code の作業です。 Remote – SSH でVMに繋いだ状態で ~/devlab を開いてください。
設定ファイルを1つ置きます。全文です。
{
"version": "0.2.0",
"configurations": [
{
"name": "Docker: Node にアタッチ",
"type": "node",
"request": "attach",
"port": 9229,
"address": "localhost",
"localRoot": "${workspaceFolder}",
"remoteRoot": "/app",
"skipFiles": ["<node_internals>/**"],
"restart": true
}
]
}
この設定で一番大事なのは localRoot と remoteRoot の2行です。
- VS Code が見ているファイルは
~/devlab/src/server.js - コンテナの中の Node.js が見ているのは
/app/src/server.js
同じファイルなのに、住所が違います。 この対応を教えないと、ブレークポイントは灰色の丸のままになって止まりません。 「設定したのに止まらない」の原因は、ほぼここです。
"request": "attach"は「すでに動いているものに繋ぐ」という指定です。launchにすると VS Code が Node.js を新しく起動しようとして、コンテナとは無関係のプロセスに繋ぎます"restart": trueは、nodemon が再起動したときに繋ぎ直す指定です。これが無いと、保存するたびにデバッガが外れます
ブレークポイントで止める
- VS Code で
src/server.jsを開く totalPriceの中のtotal += item.price * item.count;の行番号の左側をクリックして、赤い丸を付ける- 左のデバッグアイコン(虫のマーク)→ 上の一覧から「Docker: Node にアタッチ」→ 緑の再生ボタン
- VM の端末で叩く
curl が返ってきません。止まっているからです。 VS Code の左側「変数」に、いまの値が並んでいます。
Local
item: {name: 'coffee', price: 480, count: 2}
total: 0
F10(ステップオーバー)で1行ずつ進めると、total が 960 → 1280 と変わっていくのが見えます。F5 で最後まで流すと、curl が返ってきます。
console.log を10個仕込むより速いことが、ここで分かります。
[スクリーンショット: 02_VSCodeブレークポイント.png] VS Code でブレークポイントに止まり、左の「変数」パネルに total と item が出ている画面を撮ってください。
[スクリーンショット: 03_inspect接続確認.png] curl -s localhost:9229/json/list が JSON を返している画面を撮ってください。
-p 9229:9229は、そのポートを公開しているという意味です。 Inspector プロトコルには認証がありません。 繋げた人はコンテナの中で好きなコードを実行できます。 VM の中で閉じているうちは構いませんが、外に出るサーバーで開けてはいけません。 ⑩でまとめます。
⑦ docker compose watch — 新しいやり方
ここまでは docker run で長い1行を組み立ててきました。毎回これを打つのは現実的ではありません。 Compose にします。
services:
app:
build:
context: .
ports:
- "3000:3000"
- "127.0.0.1:9229:9229"
command: ["npx", "nodemon", "--inspect=0.0.0.0:9229", "src/server.js"]
volumes:
- ./:/app
- /app/node_modules
environment:
NODE_ENV: development
9229のほうだけ127.0.0.1:を頭に付けています。 こう書くとVM の中からしか繋げなくなります。 VS Code は Remote – SSH でVMの中にいるので、これで届きます。デバッグ用の口は、必要な範囲より広く開けないのが基本です。
さらに、Compose には watch という仕組みがあります(Compose v2.22 以降)。bind mount とは考え方が違います。
develop:
watch:
- action: sync
path: ./src
target: /app/src
- action: rebuild
path: ./package.json
compose.yaml の app: の下に、上の7行を足してください。試す間は、volumes: の - ./:/app の行を消しておきます(理由は下で説明します)。そして、
別の端末でソースを直します。
up --watch を出している側に、こう出ます。
Syncing service "app" after changes were detected
[nodemon] restarting due to changes...
次に package.json を直してみます(バージョンを上げるだけで構いません)。
Rebuilding service "app" after changes were detected
動作が変わりました。 ここが sync と rebuild の違いです。
| action | 何をするか | 何に使うか |
|---|---|---|
sync | 変わったファイルをコンテナの中へコピーするだけ。コンテナは動いたまま | ソースコード。速い |
rebuild | イメージを作り直して、コンテナを入れ替える | package.json・Dockerfile。依存が変わるとき |
sync+restart | コピーしたうえでコンテナを再起動 | 設定ファイルなど、読み直しが要るもの |
sync と bind mount の違いも押さえておきます。
bind mount(volumes:) | watch の sync | |
|---|---|---|
| ファイルの居場所 | ホスト側が正。コンテナは覗いているだけ | コンテナの中にコピーされる。中身は2つある |
| 通知が飛ばない環境 | 検知されない(⑤の問題) | Compose 自身が見張るので、比較的強い |
| 遅い共有フォルダ越し | 読み込みが遅い | コンテナ内のディスクなので速い |
| 除外指定 | できない | ignore: で node_modules などを外せる |
syncを使うなら、volumes:の bind mount は要りません。 両方書くと「ホストが正なのかコピーが正なのか」が分からなくなります。どちらか片方にしてください。
いったん止めます。
Ctrl + C
⑧ 開発用と本番用の Dockerfile を分ける
ここまでで、開発中のイメージには本番に要らないものが入り込んでいます。
nodemon(開発ツール)--inspectで開くデバッグの口- root ユーザーで動いていること
かといって、Dockerfile を2つに分けるのは失敗します。 片方だけ直して、もう片方が古くなるからです。同じ Dockerfile の中で、段を分けます。
# ---- 共通の土台 ----
FROM node:22-alpine AS base
WORKDIR /app
COPY package.json ./
# ---- 開発用 ----
FROM base AS dev
ENV NODE_ENV=development
RUN npm install
COPY . .
EXPOSE 3000 9229
CMD ["npx", "nodemon", "--inspect=0.0.0.0:9229", "src/server.js"]
# ---- 本番用 ----
FROM base AS prod
ENV NODE_ENV=production
RUN npm install --omit=dev && npm cache clean --force
COPY . .
USER node
EXPOSE 3000
CMD ["node", "src/server.js"]
FROM ... AS 名前 で段に名前を付けています。 そして FROM base AS dev のように、前の段を土台にして続きを書けます。
| 段 | 入るもの | 動かす利用者 | デバッグの口 |
|---|---|---|---|
dev | 開発ツールも入る(npm install) | root | 開ける |
prod | 本番に要るものだけ(--omit=dev) | node(一般利用者) | 開けない |
作り分けます。
REPOSITORY TAG IMAGE ID SIZE
devlab prod 3c1f9a2b7e04 142MB
devlab dev a70e5d813f6c 167MB
--targetを付けないと、最後の段(ここではprod)が使われます。 開発用を先に、本番用を後ろに書くと、うっかりビルドしたときに安全なほうができます。
Compose 側からは target: で選びます。
services:
app:
build:
context: .
target: dev
ports:
- "3000:3000"
- "127.0.0.1:9229:9229"
volumes:
- ./:/app
- /app/node_modules
environment:
NODE_ENV: development
CHOKIDAR_USEPOLLING: "false"
{"status":"ok","now":"2026-09-23 07:02:33"}
本番用の Compose ファイルでは
target: prodにして、volumes:と9229の行を消します。 ファイルの重ね方(compose.override.yaml)は depends_onを書いても落ちる でやったとおりです。
⑨ ログは標準出力に出す
デバッガを繋ぐほどではないとき、見るのはログです。
-f は「新しい行が出たら流し続ける」という意味です。別の端末で curl を打つと、その場で行が増えます。
app-1 | GET /total
app-1 | GET /health
止めるのは Ctrl + C です。これはログの表示を止めるだけで、コンテナは動き続けます。
よく使う形はこれだけです。
ログをファイルに書かない
ここが、VM に直接アプリを置いていたときとの一番大きな違いです。
コンテナの中のログファイルには、ほぼ意味がありません。
- コンテナを作り直したら消えます(コンテナを消すとデータも消える)
docker logsにもdocker compose logsにも出てきません- コンテナが3台に増えたら、3か所を別々に見に行くことになります
だから、コンテナの中のプログラムは、ログを標準出力(と標準エラー出力)に書きます。 console.log をそのまま使う、ということです。書き先を決めるのは、プログラムではなく外側の仕事になります。
プログラム → 標準出力 → Docker が受け取る → docker logs / 集約基盤へ
集めかたそのものは ログが3箇所に散っている と Prometheusは取りに行く でやりました。その入口は「アプリがファイルに書かないこと」です。
⑩ 開発でやってよくて、本番でやってはいけないこと
この記事でやったことは、ほとんどが本番では穴になります。 ここを混ぜないことが、この回の本当の要点です。
| やっていること | 開発 | 本番 | 本番でだめな理由 |
|---|---|---|---|
| ソースを bind mount する | ◯ | × | イメージが「動くものの全部」でなくなる。別のサーバーに持っていくと動かない。ホスト側を書き換えれば中身をすり替えられる |
| root で動かす | △ | × | コンテナから抜け出せる欠陥が見つかったとき、被害が広がる。USER node を書く |
--inspect の口を開ける | ◯ | 絶対に× | 認証が無い。繋げた人は任意のコードを実行できる |
npm install(開発ツール込み) | ◯ | × | 使わないものが増えるほど、直すべき欠陥も増える。--omit=dev |
nodemon で動かす | ◯ | × | 監視の分だけ無駄。落ちたときの再起動は Docker の restart: の仕事 |
CHOKIDAR_USEPOLLING | △ | × | CPUを食い続ける。開発でも、必要なときだけ |
NODE_ENV を未設定のまま | △ | × | ライブラリによってはエラーの詳細を外に返す。production を明示する |
latest タグ | △ | × | どれが動いているか分からなくなる。バージョンを固定する |
ポートを 0.0.0.0 で公開 | ◯(VM内) | △ | 必要なポートだけ。デバッグ用は 127.0.0.1: を付けて閉じる |
「開発で動いたから本番も同じでいい」が一番危ない、という一覧です。
つまずいたところ
遠回りしたところを、消さずに残します。
1. node_modules が消えたのを、Docker の不具合だと思った
docker build からやり直しました。キャッシュも消しました。docker system prune -a まで打ちました。当然ですが、何も変わりません。
原因が分かったのは、マウントする前と後で ls /app を並べて見たときです。
「マウントする前は在る」と分かった瞬間に、犯人はマウントに決まりました。 原因が分からないときは、疑っているものを外した状態と、付けた状態を並べるのが一番速いです。
2. ホストで npm install して解決したつもりになった
④でやったとおり、dayjs だけなら動いてしまいます。 そこで「解決した」と思い込みました。
数週間後、bcrypt を入れた日に invalid ELF header で止まり、そのときには原因の心当たりが多すぎて丸1日かかりました。たまたま動いたものは、いつか必ず落ちます。
3. ブレークポイントが灰色のまま止まらなかった
launch.json の port も address も合っていて、curl localhost:9229/json/list も返っていました。それでも止まりません。
原因は remoteRoot を書いていなかったことでした。VS Code は /home/user/devlab/src/server.js の何行目に止めろと言い、Node.js は /app/src/server.js しか知りません。話が噛み合っていなかっただけです。
「繋がっているのに止まらない」ならパスの対応を疑ってください。
4. --inspect を 0.0.0.0 にせず、ポートの公開を疑った
-p 9229:9229 を --network host に変えたり、ファイアウォールを止めたりしました。全部見当違いでした。
ログの1行目に ws://127.0.0.1:9229 と書いてあったのに、読んでいませんでした。エラーを読む前に設定を変え始めると、必ず遠回りします(エラーは下から読む)。
5. ポーリングを常時ONにして、VMが重くなった
⑤で直ったのが嬉しくて、すべての開発コンテナに CHOKIDAR_USEPOLLING=true を付けました。
top を見ると、何もしていないのに CPU が常に 30% ほど埋まっています。監視対象に node_modules の数万ファイルが入っていたためです。CHOKIDAR_USEPOLLING は、通知方式で動かないと確認できた場所にだけ付けてください。
後片づけ
この記事で作ったものだけを消します。
匿名ボリュームが溜まっているはずなので、数えてから消します。
6
docker volume pruneは、既定では「どのコンテナからも使われていない匿名ボリューム」を消します(Docker 23 以降。名前付きまで消すのは--allを付けたとき)。--allを付けると、本線で作ったデータベースの名前付きボリュームも、使っていたコンテナを消したあとなら巻き込みます。 消す前に必ずdocker volume lsを見てください。名前付きボリュームを残したいなら、pruneではなく名前を指定して消します。
イメージとフォルダを消します。
本線で作ったものは消していません。 この記事は
~/devlabの中だけで完結しています。
まとめ — 理解できたこと
- 開発中に
docker buildを繰り返すのは間違い。 ビルドは「配る形にするとき」の作業 - bind mount は「ファイルを届ける」までしかやらない。 読み直させる担当(
--watch/nodemon)が別に要る node_modulesは消えていない。ホスト側のフォルダをかぶせて隠しているだけ- マウントはパスの深いほうが勝つ。 だから
-v /app/node_modules(コロン無し=匿名ボリューム)で覆い返せる - 匿名ボリュームは、空のときに限りイメージの同じ場所の中身が最初にコピーされる。だから
npm installの結果が現れる - 匿名ボリュームはコンテナを消しても残る。 静かに溜まるので
docker rm -vかdocker volume prune - ネイティブモジュールは install した環境向けにコンパイルされる。 Ubuntu(glibc) と Alpine(musl) と Windows は互換ではない
invalid ELF headerは「バイナリの形式が違う」。 ライブラリより先に、どこで install したかを疑うnode_modulesはホストとコンテナで共有しない。 ホスト側のものは補完用、動かすのは中のもの- 変更が検知されないのは、inotify が共有フォルダ越しに飛ばないから。 ファイルは届いている
CHOKIDAR_USEPOLLING=trueで自分から見に行く。 CPUを食うので最後の手段。本筋はソースをVMの中に置くこと--inspectの既定は127.0.0.1。 コンテナの中の「自分自身」には外から届かない。--inspect=0.0.0.0:9229- VS Code は
request: attachで繋ぐ。localRootとremoteRootを書かないとブレークポイントは止まらない restart: trueが無いと、nodemon の再起動でデバッガが外れるcompose watchのsyncはコピー、rebuildはイメージごと作り直し。 ソースはsync、package.jsonはrebuildsyncと bind mount は併用しない。 どちらが正か分からなくなる- 開発用と本番用は Dockerfile を分けない。 マルチステージの段に名前を付けて
--target/target:で選ぶ --targetを省くと最後の段が使われる。 本番用を最後に書いておくと、うっかりが安全側に倒れる- ログはファイルに書かず標準出力へ。 書き先を決めるのは外側の仕事
- bind mount・root 実行・
--inspectの公開は、開発だけのもの。 本番に持ち込まない
参考リンク
- roadmap.sh — Docker
- Docker 公式 — Compose file watch
- Docker 公式 — Node.js の開発環境をコンテナで作る
- Docker 公式 — マルチステージビルド
- Docker 公式 — Dockerfile リファレンス
- Docker 公式 — bind mounts
- Docker 公式 — volumes
- Docker 公式 — コンテナのログを見る
- Node.js 公式 — デバッグを始める
- Node.js 公式 — コマンドラインオプション(–watch / –inspect)
- VS Code 公式 — Node.js のデバッグ
- nodemon 公式
- chokidar — 監視の設定
次に読む
この記事は 【深掘り】Docker の 9 / 11 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- bind mount とホットリロード
- コンテナの中をデバッグする
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント