Skip to main content

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

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

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

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

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

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

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

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

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

  1. 動いてる？
docker compose ps
  1. 落ちてるならログ！
docker compose logs --tail=200 api
docker compose logs --tail=200 db
  1. 設定の最終形を見る（環境変数の展開ミスを炙り出す🔥）
docker compose config
  1. コンテナ内から疎通（自分の目で確かめる👀）
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章）は、ここで作ったチェックリストを使って「自力で直せる人」になって卒業だよ🏆🎓✨