Contents
スポンサードリンク
Docker Desktop ダウンロードとインストール
Docker Desktop は公式サイトから最新版（2024/04 以降）を取得します。インストーラは Windows 10 2004 以上、または Windows 11 が対象です。古いバージョンでは WSL2 のサポートが不完全になるため、必ず最新の OS にアップデートしてから実行してください。
インストール手順
- Docker Desktop の公式ページ（https://www.docker.com/products/docker-desktop）へアクセスし Download for Windows をクリック。
- ダウンロードした
Docker Desktop Installer.exeを実行し、ウィザードの指示に従います。 - 「Enable WSL 2」チェックは必ずオンにしてください。
- インストール完了後、Docker が自動で起動するか確認します（タスクトレイにクジラアイコンが表示されれば OK）。
ポイント：インストール中に Windows の再起動が求められた場合は必ず実行してください。再起動をスキップすると WSL2 が正しく有効化されません。
WSL2 バックエンドの有効化と Linux カーネル更新
WSL2 を利用するには以下 3 つの条件が必要です。
- OS のバージョン：Windows 10 2004（ビルド 19041）以降、または Windows 11。
- CPU 仮想化支援機能 が BIOS/UEFI で有効になっていること（Intel VT‑x / AMD‑SVM）。
- 「仮想マシンプラットフォーム」機能 と 「Windows Subsystem for Linux」 の両方が有効化されていること。
BIOS/UEFI での仮想化有効化手順（概要）
| 手順 | 操作内容 |
|---|---|
| 1 | PC を再起動し、メーカー独自のキー（Del, F2, Esc 等）で BIOS/UEFI に入る。 |
| 2 | 「Virtualization Technology」や「Intel VT‑x」などの項目を Enabled に設定。 |
| 3 | 設定保存後に再起動し、Windows が仮想化機能を認識できているか確認（PowerShell systeminfo の出力に “Hyper-V Requirements: VM Monitor Mode Extensions: Yes” が含まれる）。 |
WSL2 のインストール手順
管理者権限で PowerShell を開き、以下のコマンドを実行します。
|
1 2 3 4 5 6 7 8 |
# 仮想化機能と WSL の有効化（初回のみ必要） dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # Ubuntu ディストリビューションをインストールし、WSL2 をデフォルトに設定 wsl --install -d Ubuntu wsl --set-default-version 2 |
注意：
wsl --installは Windows 10 2004 以降で利用可能です。古いバージョンの場合は Microsoft Store から手動で Ubuntu を取得してください。
インストールが完了したら Windows を再起動し、次のコマンドでバージョンを確認します。
|
1 2 |
wsl -l -v # Ubuntu が “Version 2” と表示されれば OK |
Microsoft の公式サイトから Linux カーネル更新プログラム（WSL2 Linux kernel update package）をダウンロードし、指示に従ってインストールしてください。これが不足すると「WSL 2 が有効になっていません」というエラーが発生します。
Docker Desktop のリソース割当と根拠
Docker Desktop は内部で仮想マシン（VM）を起動するため、CPU・メモリ・ディスク容量の割り当てが必要です。過不足は次のような影響を与えます。
| リソース | 過少の場合の影響 | 過多の場合の問題 |
|---|---|---|
| CPU | コンテナ起動が遅くなる、ビルド時間が長くなる | ホスト側の他アプリがレスポンス低下 |
| メモリ | MySQL のバッファ不足でクラッシュ、Xdebug がメモリ不足になる | Windows のページングが増えて全体的に遅くなる |
| ディスク | イメージプルやビルド時に「no space left on device」エラー | 不要な領域確保で SSD の寿命が縮む |
推奨設定（プロジェクト規模別）
| 規模 | CPU (コア) | メモリ (GB) | ディスク空き容量 (GB) | 根拠 |
|---|---|---|---|---|
| 小規模 (個人学習、1〜2 コンテナ) | 2 コア以上 | 4 GB（8 GB 推奨） | 20 GB | PHP + Apache のみであれば 2 コアでも問題なし。MySQL と Xdebug を同時に走らせるとメモリは最低 4 GB 必要 |
| 中規模 (チーム開発、3〜5 コンテナ) | 4 コア以上 | 8 GB（12 GB 推奨） | 30 GB | DB のバッファプールやキャッシュが増えるためメモリを余裕で確保 |
| 大規模 (マイクロサービス、複数 DB/Cache) | 6 コア以上 | 12 GB（16 GB 推奨） | 50 GB+ | 複数のデータベース・キューが同時稼働し、ビルドも頻繁に行うケース |
設定は Docker Desktop → Settings → Resources → Advanced から変更できます。変更後は必ず Docker を再起動してください。
VS Code と Remote‑Containers 拡張機能による開発環境構築（任意）
VS Code の Remote‑Containers 機能を使うと、エディタ側から直接コンテナ内に入って作業できます。以下では 最小構成 を例示しつつ、拡張機能のインストール手順も合わせて紹介します。
必要な拡張機能
| 拡張機能 | 用途 |
|---|---|
| Remote - Containers | コンテナ内で VS Code を実行 |
| PHP Intelephense | 高度なコード補完と型推論 |
| PHP Debug (felixfbecker) | Xdebug と連携したデバッグ |
インストール方法：VS Code の拡張機能パネルで上記キーワードを検索し、
Installをクリック。
devcontainer.json の雛形と解説（H3）
devcontainer 設定はプロジェクト直下の .devcontainer/devcontainer.json に配置します。以下は Docker Compose 方式の例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "name": "PHP Docker Dev", "dockerComposeFile": ["../docker-compose.yml"], // プロジェクト構造に合わせて相対パスを調整 "service": "web", // コンテナ名（docker‑compose.yml の service） "workspaceFolder": "/var/www/html/src", // コンテナ側の作業ディレクトリ "extensions": [ "ms-php.intelephense-client", "felixfbecker.php-debug" ], "settings": { "terminal.integrated.shell.linux": "/bin/bash" }, "postCreateCommand": "composer install --no-interaction || true" // 任意で依存インストール } |
dockerComposeFileは配列なので、複数ファイルをマージできる点が便利です。serviceに指定したコンテナが起動後に VS Code が接続します。
コンテナへシームレスに接続する手順（H3）
- Remote‑Containers: Open Folder in Container をコマンドパレット（Ctrl+Shift+P）で実行。
- プロジェクトフォルダを選択すると、VS Code が
docker compose up相当の処理を自動で走らせ、コンテナに接続します。 - 接続完了後はエディタ上のファイルがリアルタイムでコンテナと同期し、統合ターミナルも
/var/www/html/srcに位置付けられます。
プロジェクトフォルダ構成と Dockerfile / .dockerignore の作り方
コードと設定を整理すると、メンテナンス性が格段に向上します。ここでは 実務で広く採用されているレイアウト を示しつつ、.dockerignore の誤記修正ポイントも解説します。
推奨フォルダレイアウト（H3）
|
1 2 3 4 5 6 7 8 9 10 |
my-php-app/ ├─ src/ ← PHP ソースコード │ └─ index.php ├─ docker/ ← Docker 関連ファイル │ ├─ Dockerfile │ └─ .dockerignore ├─ .devcontainer/ ← VS Code 用設定（任意） │ └─ devcontainer.json └─ docker-compose.yml ← Compose 定義 |
srcはコンテナ起動時に マウント されるため、コード変更が即座に反映されます。- Docker 関連ファイルは
docker/に集約し、プロジェクトルートをすっきり保ちます。
Dockerfile の記述例（H3）
以下は公式 php:8.2-apache イメージをベースにした最小構成です。必要な拡張モジュールと Xdebug のオプションインストールを組み込んでいます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
# docker/Dockerfile FROM php:8.2-apache # ---- 必要パッケージ & PHP 拡張のインストール --------------------------------- RUN apt-get update && apt-get install -y \ libpng-dev libjpeg62-turbo-dev libfreetype6-dev zip unzip \ && docker-php-ext-configure gd --with-freetype --with-jpeg \ && docker-php-ext-install -j$(nproc) gd pdo_mysql mysqli zip # ---- Apache のドキュメントルートを書き換え ----------------------------------- ENV APACHE_DOCUMENT_ROOT /var/www/html/src RUN sed -ri "s!DocumentRoot /var/www/html!DocumentRoot ${APACHE_DOCUMENT_ROOT}!g" \ /etc/apache2/sites-available/000-default.conf && \ echo "ServerName localhost" >> /etc/apache2/conf-available/servername.conf && \ a2enconf servername # ---- Xdebug のオプションインストール --------------------------------------- ARG INSTALL_XDEBUG=false RUN if [ "$INSTALL_XDEBUG" = "true" ]; then \ pecl install xdebug && docker-php-ext-enable xdebug; \ fi EXPOSE 80 |
正しい .dockerignore（H3）
.dockerignore はビルドコンテキストに含めたくないファイルを列挙しますが、Dockerfile と docker-compose.yml は必ず除外対象から外す 必要があります。誤って除外するとイメージ作成時にこれらのファイルが無視され、ビルドエラーになるためです。
|
1 2 3 4 5 6 7 8 9 10 11 |
# docker/.dockerignore .git node_modules vendor *.log # ビルド対象に不要な一時ファイルだけを列挙 *.DS_Store .idea/ .vscode/ |
ポイント：
.dockerignoreはdocker/ディレクトリ内に置くと、ビルドコンテキストはプロジェクトのルート（context: .）になるため、上記パターンで問題ありません。
docker‑compose.yml による web・db・admin コンテナ定義と環境変数設定
Compose ファイル一つで PHP／MySQL／phpMyAdmin の 3 サービスを起動できます。以下は バージョン 3.9（Docker Desktop が推奨）で書いた例です。
Compose 全体像（H3）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 |
# docker-compose.yml version: "3.9" services: # -------------------------------------------------------------- # web (PHP + Apache) コンテナ # -------------------------------------------------------------- web: build: context: . dockerfile: ./docker/Dockerfile # Dockerfile のパスを明示 ports: - "8080:80" volumes: - ./src:/var/www/html/src # ソースコードのライブマウント environment: APACHE_LOG_DIR: /dev/stdout # コンテナログを Docker が取得しやすい形に depends_on: - db # -------------------------------------------------------------- # db (MySQL) コンテナ # -------------------------------------------------------------- db: image: mysql:8.0 command: --default-authentication-plugin=mysql_native_password environment: MYSQL_ROOT_PASSWORD: secret_root_pw MYSQL_DATABASE: myapp MYSQL_USER: app_user MYSQL_PASSWORD: secret_app_pw volumes: - db_data:/var/lib/mysql # データ永続化用ボリューム ports: - "3306:3306" # -------------------------------------------------------------- # admin (phpMyAdmin) コンテナ # -------------------------------------------------------------- admin: image: phpmyadmin/phpmyadmin environment: PMA_HOST: db MYSQL_ROOT_PASSWORD: secret_root_pw ports: - "8081:80" depends_on: - db volumes: db_data: |
設定のポイント（H3）
build.contextはプロジェクトルートに設定し、Dockerfile の相対パスを明示的に指定しています。これによりdocker compose build時に.dockerignoreが正しく適用されます。depends_onでサービス起動順序を保証しますが、本番環境ではヘルスチェック（healthcheck:）を併用するとさらに安全です。- ポート番号 はローカルで競合しやすいので、プロジェクトごとに
8080/8081のように変えても問題ありません。
コンテナ起動・確認手順とトラブルシューティング
Docker Compose の基本コマンドは docker compose（スペースあり）です。旧来の docker-compose はレガシー扱いとなっているため、以降はすべて docker compose 系列で統一します。
起動・停止・ログ確認（H3）
|
1 2 3 4 5 6 7 8 9 |
# バックグラウンドで全サービス起動 docker compose up -d # コンテナのリアルタイムログを表示 docker compose logs -f # 停止＋ボリューム削除（クリーンアップ） docker compose down --volumes |
動作確認用スクリプト（H3）
1. PHP 情報表示 (src/info.php)
|
1 2 3 4 |
<?php phpinfo(); ?> |
2. MySQL 接続テスト (src/db_test.php)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<?php $dsn = 'mysql:host=db;dbname=myapp;charset=utf8'; $user = 'app_user'; $password = 'secret_app_pw'; try { $pdo = new PDO($dsn, $user, $password); echo 'DB 接続 OK'; } catch (PDOException $e) { echo '接続エラー: ' . $e->getMessage(); } ?> |
ブラウザで http://localhost:8080/info.php と http://localhost:8080/db_test.php にアクセスし、期待通りの出力が得られれば環境構築は完了です。
Xdebug 連携と VS Code デバッグ設定（H3）
Docker イメージビルド時に --build-arg INSTALL_XDEBUG=true を付与すれば Xdebug が有効になります。VS Code 側の launch.json は次のように記述してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
{ "version": "0.2.0", "configurations": [ { "name": "Listen for XDebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/var/www/html/src": "${workspaceFolder}/src" }, "xdebugSettings": { "max_children": 256, "max_data": 1024, "max_depth": 5 } } ] } |
ブレークポイントを設定したら、ブラウザで XDEBUG_SESSION=1 クエリパラメータ（例：http://localhost:8080/index.php?XDEBUG_SESSION=1）を付与してアクセスします。
代表的なエラーと対策表（H3）
| エラーメッセージ | 主な原因 | 推奨対処 |
|---|---|---|
| WSL2 が起動しない | BIOS の仮想化が無効、または Windows 機能未有効 | dism.exe /online /enable-feature /featurename:VirtualMachinePlatform 後再起動 |
MySQL 初期化失敗 (Access denied) |
MYSQL_ROOT_PASSWORD が未設定・タイプミス |
docker‑compose.yml の env を見直し、docker compose down -v && docker compose up -d で再作成 |
| ポート 8080 が競合 | 他プロセスが使用中（IIS、Node 等） | netstat -ano | findstr :8080 で PID 確認 → 終了、または Compose のポートを変更 |
| ファイル権限エラー | Windows 側のフォルダが read‑only 共有になっている | Docker Desktop 設定 → Resources → File Sharing にプロジェクトパスを追加 |
| Xdebug 接続できない | xdebug.mode が off、ポートブロック |
php.ini に xdebug.mode=debug と xdebug.start_with_request=yes を追記し、ファイアウォールで 9003 開放 |
次のステップ
- 本手順をローカルで実行し、サンプルリポジトリ（GitHub:
github.com/example/php-docker-starter）をクローンしてすぐに動作確認してください。 - 疑問点や改善要望は GitHub Issue に投稿すると、開発者が随時対応します。
- Docker・PHP の最新情報は公式ブログと本リポジトリの
CHANGELOG.mdを定期的にチェックしましょう。
参考リンク集
| 項目 | URL |
|---|---|
| Docker Desktop ダウンロード | https://www.docker.com/products/docker-desktop |
| WSL2 インストールガイド（Microsoft） | https://learn.microsoft.com/windows/wsl/install |
| PHP:8.x‑apache イメージ公式ページ | https://hub.docker.com/_/php |
| VS Code Remote‑Containers 拡張機能 | https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers |
以上で、Windows 環境における Docker Desktop + WSL2 + PHP 開発環境の構築手順は完了です。快適なローカル開発をぜひ体験してください！
スポンサードリンク