第59章：よくある“詰まり”総復習（チェックリスト化）📋✨

この章は「困ったときに戻ってこれる地図🗺️」を作って、典型ミス10個を“最短ルート”で直せるようにする回だよ💪😄 やることはシンプル👇

✅ 症状 → 原因候補 → 確認 → 直す の型を固定する
✅ 直したら 再発防止の一行メモを残す
✅ AIにも「同じ型」で投げて、調査を高速化する🤖⚡

0) まず安全装備　壊して直すための保険🧯🧤

おすすめの進め方（事故っても戻れる✨）

Gitで分岐（またはcomposeファイルをコピー）
ミスを1個だけ仕込む
直す
「直し方メモ」をチェックリストに追記

危険ボタン注意⚠️ docker compose down -v は ボリューム（DBデータなど）を消す ので、やるときは意図してる時だけね😇

1) 30秒で迷子を脱出する　最短チェック手順🏃‍♂️💨

まずはこの順で見るだけで、8割は片付くよ😎✨

動いてる？

docker compose ps

落ちてるならログ！

docker compose logs --tail=200 api
docker compose logs --tail=200 db

設定の最終形を見る（環境変数の展開ミスを炙り出す🔥）

docker compose config

コンテナ内から疎通（自分の目で確かめる👀）

docker compose exec api sh -lc "node -v && env | sort | sed -n '1,80p'"
docker compose exec api sh -lc "curl -sS http://localhost:3000/health || true"
docker compose exec api sh -lc "getent hosts db || true"

2) チェックリストの核　症状別の分岐🧭✨

困ったら、見えてる症状で分けると一気に楽😄

🧱 起動しない：compose ps → logs → exit code
🚪 ブラウザで見えない：ports / アプリの待受 0.0.0.0 / Firewall
🔌 DBにつながらない：接続先が localhost になってない？ / サービス名 / 起動順
📁 反映が遅い・重い：ファイル置き場 / マウント / node_modules の扱い
🔒 Permission denied：bind mountの権限・所有者・書き込み先

特に Windows＋WSL2 だと、プロジェクトをLinux側（WSLのファイルシステム）に置くのが速度と安定の王道だよ🚀（Windows側のファイルをマウントすると遅くなりがち）(Docker) あとWSLは最新推奨で、Docker Desktopは WSL 2.1.5以上が最低ラインって明記されてるよ🧩(Docker Documentation)

10連ミス修正ミッション🔥🧩

それぞれ 仕込む→症状→確認→直す→再発防止 の順でいくよ！（全部やると強い💪 でも1日で無理しなくてOK😄）

ミッション01　ポート被りで起動失敗🔥🚪

仕込み：ホストの別アプリが 3000 を使用中にする（既に何か動いてたらそのままでもOK）

よくある症状

port is already allocated
EADDRINUSE

確認

netstat -ano | findstr :3000

直し方（どっちか）

✅ 使ってるプロセスを止める
✅ composeのホスト側ポートを変える（例：3001:3000）

再発防止メモ

「APIは3000固定」など、自分ルールを1行で📏✨

AIに投げる🤖 「このエラー文と docker compose ps の結果から、ポート被りの確認手順を3つに絞って」

ミッション02　アプリが localhost 待受で外から見えない🪤😵‍💫

仕込み：サーバを 127.0.0.1 でlistenする（ありがち）

症状

docker compose ps は running
でもブラウザが 接続できない 😭
コンテナ内 curl http://localhost:3000 は通る

原因の核 コンテナ内の localhost は「そのコンテナ自身」だよ😵 外（ホスト）から来るには、全IF待受（0.0.0.0） が必要になることが多い。 Nodeは host を省略すると 0.0.0.0（または ::）で待ち受ける挙動がドキュメントにあるよ📘(nodejs.org)

直し方（例）

Expressなら：

app.listen(PORT, "0.0.0.0");

または host 指定をやめる（フレームワーク側の推奨に合わせる）

再発防止

「コンテナで動かすサーバは 0.0.0.0 を意識」🚀

AIに投げる🤖 「“コンテナは動くがブラウザから見えない”ときの原因候補トップ5を優先順で」

ミッション03　ports の左右を間違えて迷子🔁😵

仕込み：ports: "3000:3001" みたいにズラす

症状

localhost:3000 が開かない
でもコンテナ内では動いてる

確認

docker compose port api 3000
docker compose ps

直し方

たとえば「コンテナが3000で動く」なら ports: ["3000:3000"] が基本👌

再発防止

「左＝ホスト、右＝コンテナ」って一言メモ📝✨

ミッション04　DB接続先が localhost で死亡💥🐘

仕込み：接続先ホストを localhost にする

症状

ECONNREFUSED 127.0.0.1:5432（例）
APIだけ落ちる、再起動ループ🔁

確認

docker compose logs --tail=200 api
docker compose exec api sh -lc "getent hosts db || true"

直し方

Compose内の接続先は サービス名（例：db）にする DATABASE_HOST=db みたいにね🧵✨

再発防止

「コンテナ内localhost禁止」🚫🏠

AIに投げる🤖 「ECONNREFUSED 127.0.0.1 が出たときの“接続先ミス”チェック項目を短く」

ミッション05　環境変数が入ってなくて認証エラー🔑😵

仕込み：.env を読まない場所に置く／キー名を間違える

症状

パスワードが undefined
DBの認証失敗
JWT_SECRET が空で落ちる

確認（これが強い）

docker compose config
docker compose exec api sh -lc "env | sort | sed -n '1,120p'"

直し方

composeで environment: / env_file: を整理
変数名を統一（DB_HOST vs DATABASE_HOST とか）🏷️

再発防止

「必須envリスト」をREADMEに5行で残す📘✨

ミッション06　依存関係ミスで起動直後に落ちる📦💥

仕込み：lockfileと実体がズレる、node_modules が壊れる等

症状

Cannot find module ...
pnpm not found / ts-node not found
起動直後に終了（exit codeが付く）

確認

docker compose logs --tail=200 api
docker compose exec api sh -lc "node -v && npm -v && ls -la"

直し方（ありがち3点セット）

docker compose build api（必要なら --no-cache）
依存は npm ci を基準に（CIでも同じになりやすい）
node_modules を “ホスト共有しない” 方針に寄せる（次のミッションへ）✨

ミッション07　Permission denied で書けない🔒😣

仕込み：書き込み先が bind mount 配下で権限が合わない

症状

EACCES: permission denied
DBのデータディレクトリが書けない
ビルド成果物が生成できない

確認

docker compose exec api sh -lc "id && ls -ln"

直し方（安全寄り）

書き込みが必要な場所は named volume 側に逃がす
もしくは Dockerfile でディレクトリを作って適切に所有権を付ける（雑にroot運用にしない🙅‍♂️）

参考：Docker DesktopのWindows権限要件や “rootで動かす” の意味も公式が整理してるよ📘(Docker Documentation)

ミッション08　node_modules を bind mount して地獄を見る😇📦

仕込み：./:/app をマウントして、/app/node_modules もホスト共有になってる状態

症状（超あるある）

Viteなどで EACCES: permission denied, rename node_modules/.vite/... 😭

直し方（結論） node_modules は bind mountしない。 named volumeに切り離すのが安定。実例として同症状の解決が共有されてるよ🧯(Qiita)

例（イメージ）

services:
  api:
    volumes:
      - ./:/app
      - api_node_modules:/app/node_modules
volumes:
  api_node_modules:

さらに named volume はVM内に作られるので高速になりやすい、という話もあるよ🚀(Docker)

AIに投げる🤖 「Windows＋WSL2で node_modules を安全に扱うComposeの定番パターンを3案出して」

ミッション09　起動順は守るけど準備完了は待たない問題⏳🪤

仕込み：DBが温まる前にAPIが接続して落ちる

症状

ECONNREFUSED が起動直後だけ出る
リトライが無いとAPIが落ち続ける🔁

直し方（Compose側） Composeは依存順に起動はするけど、「サービスが使える状態」まで待つには healthcheck と組み合わせが大事。公式に “startup order を healthcheck で制御” の解説があるよ📘(Docker Documentation)

例（イメージ）

services:
  api:
    depends_on:
      db:
        condition: service_healthy
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 10

再発防止（超重要）

Composeで待つ＋アプリ側も軽くリトライ、が最強💪

ミッション10　リソース不足で謎落ち　ビルド激遅🐢💥

仕込み：メモリが少ない設定で重めのビルドをする（または他アプリが食ってる）

症状

Killed / exit code 137っぽい
ビルドが極端に遅い、固まる
起動が不安定

確認

docker compose logs
Docker Desktopのリソース設定を見る👀

Docker DesktopはCPU/メモリ/Swap/Disk上限を設定できて、デフォルトはメモリがホストの50%まで、などの説明があるよ🧠(Docker Documentation) さらにWSL全体のリソース配分は .wslconfig でも調整できる（公式）⚙️(Microsoft Learn)

再発防止

「ビルドが重いときは ①リソース ②ファイル置き場 ③node_modules分離」を疑う✅

自分用チェックリストの作り方　ここまでやれば一生モノ🌱📋✨

最後に、あなたのチェックリストを“育つ形”にしよう😄

✅ ミッション01〜10のうち、実際に刺さったものに⭐を付ける
✅ その項目だけ「確認コマンド」を1行追記
✅ 「直し方の決め手」も1行追記（例：config見たら env が空だった）

AI活用テンプレ🤖✨（コピペ用）

以下を見て、原因候補を優先順に3つ。
そして「最短の確認手順」をコマンド付きで5ステップにして。
- docker compose ps の結果:
- docker compose logs --tail=200 の結果:
- docker compose config の該当部分:

これだけで、AIがかなり良い“診断役”になるよ🩺✨

まとめ🏁🎉

この章で一番大事なのはこれ👇😄

✅ **型（症状→原因→確認→対処）**を固定
✅ config と logs を最優先で見る
✅ Windows＋WSL2は ファイル置き場 と node_modules分離 が超効く(Docker)
✅ 起動順は healthcheck で“準備完了”まで待つ(Docker Documentation)

次の最終章（第60章）は、ここで作ったチェックリストを使って「自力で直せる人」になって卒業だよ🏆🎓✨

0) まず安全装備 壊して直すための保険🧯🧤​

1) 30秒で迷子を脱出する 最短チェック手順🏃‍♂️💨​

2) チェックリストの核 症状別の分岐🧭✨​

10連ミス修正ミッション🔥🧩​

ミッション01 ポート被りで起動失敗🔥🚪​

ミッション02 アプリが localhost 待受で外から見えない🪤😵‍💫​

ミッション03 ports の左右を間違えて迷子🔁😵​

ミッション04 DB接続先が localhost で死亡💥🐘​

ミッション05 環境変数が入ってなくて認証エラー🔑😵​

ミッション06 依存関係ミスで起動直後に落ちる📦💥​

ミッション07 Permission denied で書けない🔒😣​

ミッション08 node_modules を bind mount して地獄を見る😇📦​

ミッション09 起動順は守るけど準備完了は待たない問題⏳🪤​

ミッション10 リソース不足で謎落ち ビルド激遅🐢💥​

自分用チェックリストの作り方 ここまでやれば一生モノ🌱📋✨​

まとめ🏁🎉​

0) まず安全装備　壊して直すための保険🧯🧤

1) 30秒で迷子を脱出する　最短チェック手順🏃‍♂️💨

2) チェックリストの核　症状別の分岐🧭✨

10連ミス修正ミッション🔥🧩

ミッション01　ポート被りで起動失敗🔥🚪

ミッション02　アプリが localhost 待受で外から見えない🪤😵‍💫

ミッション03　ports の左右を間違えて迷子🔁😵

ミッション04　DB接続先が localhost で死亡💥🐘

ミッション05　環境変数が入ってなくて認証エラー🔑😵

ミッション06　依存関係ミスで起動直後に落ちる📦💥

ミッション07　Permission denied で書けない🔒😣

ミッション08　node_modules を bind mount して地獄を見る😇📦

ミッション09　起動順は守るけど準備完了は待たない問題⏳🪤

ミッション10　リソース不足で謎落ち　ビルド激遅🐢💥

自分用チェックリストの作り方　ここまでやれば一生モノ🌱📋✨

まとめ🏁🎉