メインコンテンツまでスキップ

第05章：Windowsで詰まりがちなポイント先回り🪟🧯

この章は、Windows + Docker/Composeで「重い・遅い・反映されない・動かない」を最初に潰す回だよ！✨ ここを先に押さえるだけで、その後の章がめちゃ快適になる👍

5-0. まず結論：Windowsで詰まりやすい“ラスボス”は2つ😈​

  1. プロジェクト（ソース）をどこに置くか（速度・監視・反映の大半がここ）
  2. 改行（CRLF/LF）（/bin/sh^M とかで急に爆発💣）

この2つを最初に制圧しよう🔥

5-1. Docker Desktopは「WSL 2エンジン」が基本🧠⚙️​

Docker Desktop for Windowsは、基本的に WSL 2ベースで動かすのが推奨ルートだよ。(Docker Documentation) （Hyper-V系より相性・速度面でラクになりがち）

ついでにWSL自体も新しめを維持すると事故が減る✨ wsl --version / wsl --update で更新できる。(Docker Documentation)

5-2. 速度とホットリロードは「置き場所」で決まる🏎️💨​

✅ いちばん効くルール​

bind mount（ソース共有）するコードは、Linux側（WSLのファイルシステム）に置くのが鉄板！ Docker公式も「bind-mountするならLinux側に置くと速いよ」って明言してる。(Docker Documentation)

何が起きるの？🤔​

  • C:\...（Windows側）に置く → コンテナ（Linux）から見ると「別OSまたぎのファイルアクセス」になって、 npm install / 起動 / 監視 / リロードが遅くなったり取りこぼしたりしやすい😵‍💫
  • \\wsl$\Ubuntu\home\...（WSL側）に置く → Linux ⇄ Linuxのアクセスに近くなって、体感が別物⚡

おすすめの運用🍀​

  • プロジェクトはWSL側に作る（例：~/projects/myapp）
  • VS Codeは WSL側のフォルダを開く（Remote WSLの流れ）

5-3. 改行（CRLF/LF）で爆発するやつ💥（先に防ぐ）​

WindowsはCRLF、LinuxはLF。ここが混ざると、シェルスクリプトが死ぬ😇 例：entrypoint.sh や *.sh が CRLF だと ^M が混ざって実行失敗しがち。

✅ 最強の防波堤：.gitattributes 🧱​

Gitはファイルごとに「この拡張子はLF固定ね」って指定できる。(Git)

プロジェクト直下に .gitattributes を置いて、最低限これを入れるのが超おすすめ👇

## Linux系スクリプトはLF固定（コンテナで確実に動かす）
*.sh     text eol=lf

## YAMLやDockerfileもLFにしておくと事故りにくい
*.yml    text eol=lf
*.yaml   text eol=lf
Dockerfile text eol=lf

## Windows専用はCRLFでもOK（必要なら）
*.bat    text eol=crlf
*.ps1    text eol=crlf

これで「Windowsで編集したらコンテナで死んだ😭」が激減する👍

5-4. 権限（chmod）でコケるパターン👟🪤​

Linuxでは「実行できるファイル」には実行権限がいるよね。 Windowsだとこの感覚が薄いから、コンテナ内で permission denied が出がち😵

よくある症状​

  • ./entrypoint.sh: Permission denied
  • exec format error（改行やshebangも絡む）

対処の型（まずこれ）​

  • Dockerfile 側で実行権限を付ける（イメージ作成時に確定させるのが安全）
## 例：entrypointを使う場合
COPY entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh

5-5. 「編集したのに反映されない」＝ファイル監視の罠👀🌀​

まず知っておくと心が折れない話🧠​

WSL2（＋WSL2バックエンドDocker）環境では、Windows側のアプリで編集した変更イベントがうまく届かないケースがある。 Vite公式が「WSL2の制約」として明記してるよ。(vitejs)

反映されない時の“3つの勝ち筋”🏆​

A) いちばんおすすめ：WSL側に置いて、WSL経由で編集📝✨​

  • プロジェクトをWSLファイルシステムに移す（5-2のやつ）
  • VS CodeもWSLで開く → これが一番スッキリ勝てるルート🥇

B) どうしてもダメなら：監視を「ポーリング」に切り替える🔁​

ファイルイベント監視が落ちるなら、**定期チェック方式（Polling）**にする手があるよ。

  • chokidar系なら CHOKIDAR_USEPOLLING=true が定番。(GitHub)
  • webpack/watchpack系なら WATCHPACK_POLLING が効くことがある。(GitHub)
  • Viteは server.watch.usePolling の案内がある。(vitejs)

例（Composeで環境変数として入れるイメージ）👇

services:
  api:
    environment:
      - CHOKIDAR_USEPOLLING=true
      - WATCHPACK_POLLING=true

※ポーリングはCPUちょい増えるけど「反映されない地獄」より100倍マシ😇

C) Compose Watchを使う（編集→同期/リビルドをComposeに任せる）👀✨​

Docker公式の Compose Watch は、開発中のファイル変更を検知して同期/再ビルドする仕組み。 docker compose up --watch で動くよ。(Docker Documentation)

docker compose up --watch

「監視が怪しい環境」での保険として覚えておくと強い💪(Docker Documentation)

5-6. パス問題（Windows特有）で詰まるやつ🧷🧨​

よくある事故​

  • C:\... をComposeに書いたら **:（コロン）**でYAMLが変に解釈した
  • スペース入りパスでコケた
  • 相対パスの基準がズレた

安全運用のコツ✅​

  • なるべく 相対パス（./）を使う
  • どうしてもWindows絶対パスなら、必ずクォートする
volumes:
  - "C:\\Users\\you\\project:/app"

ただし…結局、速度/監視まで考えると「WSL側に置く」が総合最強🥳

5-7. 「なんか重い😵」のときの応急処置セット🧯​

① まず疑う：ソースがWindows側に置かれてない？📦​

→ 置かれてたら、WSL側へ移す（最優先）(Docker Documentation)

② WSLの設定で暴走を抑える（メモリ食いすぎ対策）🍽️​

WSLは .wslconfig でメモリ/CPUなどを調整できる。(Microsoft Learn)

例（ユーザーホームに .wslconfig）👇

[wsl2]
memory=8GB
processors=4
swap=4GB

変更したら wsl --shutdown して反映、が基本だよ。(Microsoft Learn)

5-8. 10秒で回す「切り分けフロー」🕵️‍♂️✨​

症状A：ホットリロードしない👀​

  1. プロジェクトはWSL側？（Yesなら次）
  2. Windowsアプリで編集してない？（WSL側で編集に寄せる）(vitejs)
  3. まだダメなら Polling（CHOKIDAR/WATCHPACK）(GitHub)
  4. それでも不安なら Compose Watch (Docker Documentation)

症状B：/bin/sh^M とか出る💥​

  • .gitattributes でLF固定（5-3）(Git)

症状C：とにかく遅い🐢​

5-9. ミニ演習（ここまでできたら勝ち）🏁🎉​

✅ チェックリスト（できたらクリア！）

  • プロジェクトがWSL側にある📁
  • .gitattributes が入ってる🧱
  • 変更したらコンテナ側の開発サーバが反応する👀
  • 反応しない場合の“逃げ道”（Polling / Compose Watch）を用意できる🛟(Docker Documentation)

5-10. Copilot / Codexに投げると強い質問テンプレ🤖✨​

そのまま貼ってOKなやつ置いとくね👇

  • 「Windows + Docker Desktop(WSL2)でホットリロードしません。Vite/webpack/chokidarの監視が落ちる条件を整理して、Polling切り替え案（環境変数/設定）を最小変更で提案して」(vitejs)
  • 「この compose.yaml のvolume指定がWindowsで安全に動くかチェックして。パス・コロン・クォートの罠があれば修正案を出して」
  • 「/bin/sh^M が出た。.gitattributes を使ってLF固定する最小セットを提案して」(Git)

ここまでできたら、次の章（Postgres追加🐘）からほぼ詰まらずに気持ちよく進めるはず！🚀✨