Contents
前提条件と開発環境の準備
本セクションでは、ローカルマシンで PHP 8.3 + MySQL + Nginx を Docker 上に構築するために必要なツール・バージョン・インストール手順をまとめます。Docker Desktop（Windows/macOS）と Docker Engine＋WSL2（Linux）の両方に対応させ、VS Code と Remote‑Containers 拡張の最低要件も明示しますので、環境構築時の抜け漏れを防げます。
必要なツールとインストール手順
Docker と VS Code の導入は公式ドキュメントが最も信頼性があります。以下に OS 別の代表的な手順を示します。
- Docker Desktop（Windows / macOS）
- 推奨バージョンは 4.30 以降です。インストール後、設定画面で 「Use the WSL 2 based engine」 を有効にしてください。
- Docker Engine + WSL2（Linux）
- Ubuntu 22.04 系列では
sudo apt-get update && sudo apt-get install -y docker.ioで Docker 本体を入れ、sudo usermod -aG docker $USER後に再ログインすれば使用可能です。 - Visual Studio Code と Remote‑Containers 拡張
- VS Code は 1.90 以上、拡張は Marketplace の 「Remote – Containers」 をインストールします。拡張は Docker デーモンが起動していることを前提に自動検出されます。
参考: Qiita の入門記事では Windows/macOS 共通の手順が詳しく掲載されています【[Qiita]】(https://qiita.com/gachi_engineer/items/4dcee4e6416397adaf7b)。
OS・Docker Desktop／WSL2 の設定ポイント
Docker が正しく起動しない主な原因は CPU 仮想化が無効 になっていることです。以下の点を必ず確認してください。
- BIOS 設定：
Intel VT‑x/AMD‑Vを有効にする。 - リソース割当：Docker Desktop の Settings → Resources でメモリ最低 4 GB、CPU 2 コア以上 を確保。
- WSL2 ディストリビューション：
wsl --set-default-version 2後に Ubuntu 22.04 をインストールし、wsl -d Ubuntu-22.04で起動できることを確認。
バージョン確認と推奨イメージタグ
Docker Hub の公式リポジトリは頻繁に更新されますが、執筆時点（2026‑05‑20）では Nginx 1.27‑alpine と MySQL 8.3 はまだリリースされていません。実際に利用可能な最新安定タグは次のとおりです。
| コンポーネント | 現行最新版（2026‑05‑20） | 推奨タグ例 |
|---|---|---|
| Nginx | 1.26.x 系列（Alpine） | nginx:1.26-alpine または nginx:latest |
| MySQL | 8.2.x 系列 | mysql:8.2、もしくは mysql:8（マイナーバージョン自動取得） |
確認手順
|
1 2 3 4 5 6 7 |
# Nginx の利用可能タグ一覧を取得 docker manifest inspect nginx --verbose | grep -i alpine # MySQL の利用可能タグ一覧を取得 curl -s https://registry.hub.docker.com/v2/repositories/library/mysql/tags?page_size=100 \ | jq -r '.results[].name' | grep '^8\.' | sort -V | tail -n 5 |
上記コマンドで最新タグが確認できたら、docker‑compose.yml のイメージ指定を 実際に存在するタグ に置き換えてください。
プロジェクト構成と Dockerfile の作成
この章では、ディレクトリ構造・.dockerignore・マルチステージ Dockerfile の具体例を示します。ファイル配置とビルド最適化は開発効率に直結するため、ここで紹介するベストプラクティスに従うことを推奨します。
推奨ディレクトリ構成例
以下はシンプルかつ拡張しやすい構成です。src/ 配下のコードはボリュームマウントで即時反映されます。
|
1 2 3 4 5 6 7 8 9 10 11 |
my-php-app/ ├─ src/ # アプリケーションコード │ └─ index.php ├─ nginx/ # Nginx 設定ファイル │ └─ default.conf ├─ docker/ # Docker 関連ファイル │ ├─ php/ │ │ └─ Dockerfile │ └─ compose.yml └─ .env # 環境変数（Git 管理外） |
.dockerignore の設定サンプル
ビルドコンテキストから不要ファイルを除外し、キャッシュ時間とイメージサイズの両方を削減します。
|
1 2 3 4 5 6 7 8 |
.git node_modules vendor Dockerfile docker-compose.yml .env *.log |
公式 PHP 8.3 イメージを用いたマルチステージ Dockerfile
以下は pdo_mysql と intl 拡張のインストール例です。ビルドステージで必要なパッケージだけを取得し、最終イメージには拡張ファイルのみコピーすることでサイズを抑えます。
|
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 |
# ---------- Build stage ---------- FROM php:8.3-fpm-alpine AS builder # 必要なビルドツールとライブラリのインストール RUN apk add --no-cache \ icu-dev zlib-dev libzip-dev && \ docker-php-ext-configure intl && \ docker-php-ext-install pdo_mysql intl zip # Composer を公式イメージからコピー COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer WORKDIR /var/www/html COPY src/ . # ---------- Production stage ---------- FROM php:8.3-fpm-alpine AS production # ビルド済み拡張だけをコピー COPY --from=builder /usr/local/lib/php/extensions/no-debug-non-zts-*/pdo_mysql.so \ /usr/local/lib/php/extensions/no-debug-non-zts-*/intl.so \ /usr/local/lib/php/extensions/ RUN docker-php-ext-enable pdo_mysql intl WORKDIR /var/www/html COPY --from=builder /var/www/html/ . # 権限設定（開発時は www-data が書き込み可能であることが前提） RUN chown -R www-data:www-data /var/www/html |
参考: Zenn の実践記事でも同様にマルチステージで軽量化する手法が紹介されています【[Zenn]】(https://zenn.dev/yamato_snow/articles/616ba7f7594055)。
Docker Compose でサービス定義
この章では Docker Compose v2 記法を用いて、PHP、Nginx、MySQL の3 コンテナを構成します。ネットワーク・ボリュームの設定と .env の活用例も合わせて提示します。
PHP・Nginx・MySQL 各コンテナ設定
以下は docker/compose.yml の全体像です。イメージタグは 実際に存在するもの（前節参照）を使用してください。
|
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 |
services: php: build: context: ./docker/php dockerfile: Dockerfile volumes: - ./src:/var/www/html:cached environment: XDEBUG_MODE: develop,debug # .env でも上書き可能 networks: - app-net nginx: image: nginx:1.26-alpine # 実在するタグに変更 ports: - "8080:80" volumes: - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro - ./src:/var/www/html:ro depends_on: - php networks: - app-net mysql: image: mysql:8.2 # 実在するタグに変更 command: --default-authentication-plugin=mysql_native_password environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: ${MYSQL_DATABASE} MYSQL_USER: ${MYSQL_USER} MYSQL_PASSWORD: ${MYSQL_PASSWORD} ports: - "3306:3306" volumes: - mysql-data:/var/lib/mysql networks: - app-net networks: app-net: driver: bridge volumes: mysql-data: |
.env の活用例
.env ファイルはリポジトリに含めず、ローカルで管理します。機密情報は必ず .gitignore に追加してください。
|
1 2 3 4 5 6 7 8 9 |
# MySQL MYSQL_ROOT_PASSWORD=exampleRootPass MYSQL_DATABASE=app_db MYSQL_USER=app_user MYSQL_PASSWORD=exampleUserPass # Xdebug（開発時のみ有効化） XDEBUG_MODE=develop,debug |
Compose 実行時に自動で読み込まれ、環境変数の漏洩リスクを低減します。
開発体験向上の設定
この章ではデバッグ・依存管理・キャッシュ戦略について具体的な設定例を示します。特に Xdebug 3 の接続先 IP 設定は Linux 環境で注意が必要です。
Xdebug 3 のリモートデバッグ構成
PHP コンテナに xdebug.ini を配置し、IDE と通信できるようにします。Linux の場合は ホストのゲートウェイ IP が環境によって変わるため、以下の2パターンを用意してください。
|
1 2 3 4 5 6 7 8 9 10 11 |
; php/xdebug.ini（Dockerfile で COPY） zend_extension=xdebug.so xdebug.mode=debug,develop xdebug.start_with_request=yes # Docker Desktop (Windows/macOS) 用 xdebug.client_host=host.docker.internal # Linux のデフォルトブリッジ以外の場合は環境変数で上書き ; xdebug.client_host=${XDEBUG_HOST} |
docker compose up -d 時に .env に XDEBUG_HOST を設定すれば、カスタムネットワークでも自動的に正しい IP が使用されます。例:
|
1 2 3 |
# Linux (WSL2 など) 用 XDEBUG_HOST=172.18.0.1 # `docker network inspect bridge` で確認できるゲートウェイ |
VS Code 用 launch.json 設定例
以下は PHP デバッグ用の最小構成です。pathMappings によってローカルパスとコンテナ内パスを紐付けます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
{ "version": "0.2.0", "configurations": [ { "name": "Docker: PHP Xdebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/var/www/html": "${workspaceFolder}/src" }, "log": true } ] } |
コンテナ内 Composer の利用方法
公式 PHP イメージには Composer が同梱されていません。builder ステージでインストールするのがベストプラクティスです。
|
1 2 3 4 |
RUN php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" \ && php composer-setup.php --install-dir=/usr/local/bin --filename=composer \ && rm composer-setup.php |
起動後は以下コマンドで依存パッケージを取得できます。
|
1 2 |
docker compose exec php composer install --no-interaction --prefer-dist |
コード変更即時反映とキャッシュ戦略
開発環境ではファイルの同期速度と PHP の OPCache 設定が重要です。
- ボリュームマウントに
:cachedオプションを付与すると、ホスト側の変更が高速にコンテナへ伝搬します。 - OPCache は開発時は以下設定で常に再検証させます（本番環境では無効化または別途チューニングしてください）。
|
1 2 3 4 5 |
; php/opcache.ini opcache.enable=1 opcache.validate_timestamps=1 opcache.revalidate_freq=0 |
- フロント資産がある場合は
node:20-alpineコンテナでビルドし、生成物だけをsrc/publicに出力するとキャッシュの恩恵が受けやすくなります。
ビルド・起動手順と環境変数管理
この章では実際にコンテナをビルド・デタッチモードで起動するフローと、.env のベストプラクティスをまとめます。再ビルドが必要になるシーンも明示しています。
.env ファイルのベストプラクティス
| ポイント | 推奨設定 |
|---|---|
| Git 管理外 | .gitignore に必ず追加 |
| 命名規則 | 大文字・アンダースコア（例 DB_HOST, XDEBUG_MODE） |
| コメントでデフォルト提示 | 変更忘れ防止のため、各変数に説明を付与 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# ------------------------------------------------- # DB 接続情報（ローカルで必ず上書きしてください） # ------------------------------------------------- MYSQL_ROOT_PASSWORD= MYSQL_DATABASE=app_db MYSQL_USER=app_user MYSQL_PASSWORD= # Xdebug 設定（開発時は有効、CI 時は無効推奨） XDEBUG_MODE=develop,debug # Linux 環境での Xdebug ホスト IP（ブリッジ以外の場合に使用） XDEBUG_HOST= |
ビルド・起動フロー
- 環境変数のロード
bash
docker compose --env-file .env up --build -d - イメージビルド（マルチステージ Dockerfile が走り、拡張と Composer がインストールされた PHP イメージが生成）
- コンテナ起動順序は
depends_onに従い、PHP → Nginx → MySQL の順に開始されます。 - ポート確認：ホストの 8080（Web）と 3306（DB）が公開されていることを
docker compose psで確認。
再ビルドが必要になるケース
| 変更項目 | 必要な再ビルド |
|---|---|
| Dockerfile 本体や PHP 拡張の追加 | docker compose up --build -d |
ビルド時に参照する環境変数（例 XDEBUG_MODE） |
同上 |
| ベースイメージタグの更新（nginx、mysql） | 同上 |
トラブルシューティングとベストプラクティス
実務で頻出するエラーと対処法を表形式でまとめました。問題が起きたらまずこのチェックリストをご確認ください。
| カテゴリ | 代表的なエラー | 原因例 | 解決策 |
|---|---|---|---|
| 権限 | Permission denied（ファイル/ディレクトリ） |
コンテナ内 www-data とホスト側所有者が不一致 | docker compose exec php chown -R www-data:www-data /var/www/html もしくはビルド時に権限を設定 |
| ポート競合 | Bind for 0.0.0.0:8080 failed |
ホストで別プロセスが 8080 を使用中 | docker compose ps で確認後、.env の APP_PORT を変更し ports 設定を更新 |
| PHP 拡張ビルド失敗 | configure: error: intl not found |
必要な開発パッケージ（icu‑dev 等）未インストール | Dockerfile に apk add --no-cache icu-dev を追記し再ビルド |
| Xdebug 接続不能 | デバッガがブレークポイントで止まらない | xdebug.client_host が誤っている、またはカスタムネットワークのゲートウェイ IP が違う |
Windows/macOS は host.docker.internal、Linux は .env の XDEBUG_HOST を正しいゲートウェイに設定 |
| MySQL 初期化失敗 | Access denied for user 'root'@'%' |
.env のパスワード未設定または不一致 |
.env に正しい値を記入し、docker compose down && docker compose up -d で再起動 |
ベストプラクティスまとめ
- イメージタグは常に公式リポジトリで確認 →
docker manifest inspect等で実在性を検証。 - Xdebug のホスト設定は環境変数で切り替え可能に → Linux と macOS で同一 Compose ファイルが使える。
- キャッシュ問題は
--no-cacheビルドで回避 → イメージサイズやレイヤー不整合を防げます。 - 本番環境への流用時は Xdebug を完全にオフ →
XDEBUG_MODE=off、ポート公開も削除。
まとめ
以上の手順と設定例に沿って構築すれば、公式 PHP 8.3 イメージと Docker Compose v2 を活用した ローカル開発環境が数分で完成します。コード変更は即座にコンテナへ反映され、VS Code の Xdebug でシームレスにデバッグ可能です。
- バージョンタグは必ず Docker Hub で最新を確認し、本文中の例（
nginx:1.26-alpine,mysql:8.2）に置き換えること。 - Linux 環境では Xdebug の接続先 IP を環境変数
XDEBUG_HOSTで上書きし、ブリッジ以外のネットワークでも確実に動作させる。 .envは機密情報を保持したまま Git 管理から除外し、チーム全員が同一設定で起動できるようにする。
この構成は 拡張性 と 再現性 を兼ね備えているため、個人プロジェクトだけでなく小規模〜中規模の開発チームでも安心して採用できます。ぜひ試してみてください。