drupal-ddev

Drupal 開発向け DDEV

ローカルの Drupal 開発環境として DDEV を使用するための包括的なパターンを紹介します。セットアップ、設定、ワークフローの最適化、トラブルシューティングを含みます。

このスキルが有効になる場面

以下を含む、DDEV を使ったローカル開発で有効になります。

• DDEV の設定（.ddev/config.yaml）
• ローカル環境のセットアップと管理
• データベースのインポート／エクスポート操作
• Drush との連携
• Xdebug とデバッグツール
• パフォーマンスの最適化
• マルチサイトとカスタムコマンド

---

利用できるトピック

基本セットアップ

• @references/config-yaml.md - .ddev/config.yaml リファレンス
• @references/workflows.md - 新規／インポート済みプロジェクトのセットアップ、リモート DB の同期、日常的なワークフロー、複数プロジェクトの管理

データベース操作

• @references/database.md - インポート、エクスポート、スナップショットのワークフロー

開発ツール

• @references/xdebug.md - Xdebug によるデバッグ
• @references/solr.md - ローカル Solr 検索のセットアップ

高度なトピック

• @references/custom-commands.md - プロジェクト固有のコマンドの作成
• @references/performance.md - DDEV のパフォーマンス最適化
• @references/load-and-recovery.md - ホスト CPU の飽和、クラッシュ後の復旧時の落とし穴、Mutagen ペイロードの削減、使い捨て DB での Kernel テスト、1 つのプロジェクトで複数のエージェントを連携させる方法

詳細なドキュメントについては、/references/ ディレクトリを参照してください。

リファレンス

タスクに該当する詳細が必要な場合は、対応するファイルを読んでください。よくある問題のセクションは、ほとんどの使用場面で必要になるため、ここに記載しています。

ファイル	読むタイミング
references/workflows.md	新規プロジェクトのセットアップ、既存プロジェクトのインポート、リモート環境からのデータベース同期、日常的な起動／停止手順の実施、複数の DDEV プロジェクトの管理、またはエージェントの git worktree ディレクトリのクリーンアップを行う場合
references/performance.md	macOS で DDEV の動作が遅い場合（Mutagen と NFS の比較）、MariaDB の調整、または PHPUnit／Kernel の実行が遅い場合（高速なブートストラップ、最小のテスト範囲、Kernel テストスイートの実行場所）
references/xdebug.md	Xdebug の有効化／無効化、または IDE（VSCode の launch.json）との接続設定を行う場合
references/custom-commands.md	.ddev/commands/web/ にプロジェクト固有の ddev <command> を作成する場合
references/config-yaml.md	以下の基本例を超えて .ddev/config.yaml を編集する場合（PHP、データベース、ポート、ホスト名、フック、サービス、環境変数）
references/database.md	データベースのインポート、エクスポート、スナップショット作成、アクセス、サニタイズを行う場合、またはデータベースのインポートが失敗する場合
references/solr.md	Search API 用のローカル Solr サービスを実行する場合
references/load-and-recovery.md	ホストの負荷が高いときにリクエストが停止する場合、Docker のクラッシュ後、Mutagen ペイロードの削減、使い捨て DB を使った Kernel テストの実行、または複数のエージェントで 1 つの DDEV プロジェクトを共有する場合

---

クイックリファレンス

必須コマンド

# Start project
ddev start

# Stop project
ddev stop

# Restart services
ddev restart

# SSH into web container
ddev ssh

# Run Drush commands
ddev drush cr
ddev drush status
ddev drush config:status

# Run Composer
ddev composer require drupal/module_name
ddev composer update

# Database operations
ddev import-db --file=backup.sql.gz
ddev export-db --file=backup.sql.gz
ddev snapshot

# View logs
ddev logs
ddev logs -f    # Follow mode

# Describe project
ddev describe

# Access URLs
ddev launch     # Open site in browser

基本的な .ddev/config.yaml

name: myproject
type: drupal11
docroot: web
php_version: "8.3"
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.6"
nodejs_version: "24"

# Additional services
additional_services:
  - solr

# Custom upload/execution limits
upload_dirs:
  - web/sites/default/files

# Performance settings
performance_mode: mutagen  # For macOS

---

ベストプラクティス

1. .ddev/config.yaml をコミットする - チームで設定を共有します
2. ローカルの composer の代わりに ddev composer を使う
3. データベースのスナップショットをコミットしない - サイズが大きすぎます
4. リスクの高い操作の前にスナップショットを作成する
5. デバッグしていないときは Xdebug を無効にする - パフォーマンスに影響します
6. macOS では mutagen を使う - ファイル同期がはるかに高速です
7. 定期的に ddev poweroff を実行する - システムリソースを解放します
8. サービスのバージョンを固定する - PHP、データベース、Node.js
9. 自動化にはフックを使う - 起動後のタスク
10. カスタムコマンドを文書化する - チームメンバーの役に立ちます

---

よくある問題

サイトが読み込まれない

# Restart project
ddev restart

# Check status
ddev describe

# View logs
ddev logs

# Clear Drupal cache
ddev drush cr

データベース接続エラー

# Check database is running
ddev describe

# Verify settings.php or settings.ddev.php exists
ddev ssh
ls web/sites/default/settings*.php

ポートの競合

# Stop all DDEV projects
ddev poweroff

# Check for port conflicts
lsof -i :80 -i :443

# Change router HTTP port if needed
ddev config --router-http-port=8080 --router-https-port=8443

macOS でパフォーマンスが遅い

# Enable mutagen
ddev config --performance-mode=mutagen
ddev restart

# Or use NFS
ddev config --nfs-mount-enabled=true
ddev restart

Drush の PHP 非推奨警告

Drush コマンドの実行時に PHP の非推奨警告が表示される場合（特に PHP 8.4）、それらを抑制するためにカスタム PHP 設定ファイルを作成してください。

.ddev/php/drush.ini：

; Suppress PHP deprecation warnings for Drush commands
[PHP]
error_reporting = 22527
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /tmp/php-errors.log

次に、DDEV を再起動します。

ddev restart

仕組み：

• error_reporting = 22527 は E_ALL & ~E_DEPRECATED と同じです
• display_errors = Off により、警告が STDERR に表示されなくなります
• display_startup_errors = Off により、ブートストラップ時の警告が抑制されます
• エラーは画面に表示されず、/tmp/php-errors.log に記録されます

DDEV は .ddev/php/*.ini ファイルを /etc/php/[version]/cli/conf.d/ と /etc/php/[version]/fpm/conf.d/ の両方にコピーするため、この設定はウェブと CLI の両方に適用されます。

ddev composer install の中断により、インストール済みと誤認されたパッケージが残る（パッチが適用されない）

ddev composer install／update が実行途中で強制終了した場合（Docker の OOM による終了コード 137、ホスト側のタイムアウト、クラッシュなど）、Composer は終了前にパッケージをインストール済みとして記録していることがあります。そのため、次回の composer install では 「インストール、更新、削除するものはありません」 と表示され、composer-patches がそのパッケージにパッチを適用しません。その結果、中途半端な状態の contrib ツリーが残り、実行時に一見あり得ないエラー（DI の ServiceCircularReferenceException や、パッチ適用前のコンストラクターによる TypeError など）が発生します。ツリーを修復すると、これらのエラーは再現しなくなります。

診断：

# Verify patch application (a verify-patches script if your project has one,
# or spot-check a known-patched file in the vendored tree)
ddev composer install                # says "Nothing to install" despite the missing patches

修正 — 該当パッケージをクリーンな状態で強制的に再インストールします（そのパッケージのパッチも再適用されます）。

ddev composer reinstall drupal/<pkg>

ルール：Composer の実行が中断された場合は、パッケージツリー全体を疑ってください。実行中だったパッケージを再インストールし、パッチが適用されていることを再確認してから、残りのエラーをデバッグしてください。問題が起きていた間に見えたエラーは、すでに解消している可能性があります。エラーログのタイムスタンプを確認し、修正に取りかかる前に、致命的なエラーが今も再現することを確認してください。

タイムアウトで強制終了した ddev drush コマンドは、コンテナー内のプロセスを孤立させます

ホスト側の ddev drush ... プロセスを終了しても（Ctrl-C、ツールのタイムアウト）、ウェブコンテナー内の php プロセスは終了しません。孤立したプロセスが蓄積して CPU を奪い合うため、その後の Drush のブートストラップがすべて極端に遅くなります（drush cr／updb／updatedb:status に 10 分以上かかることがあります。ハングしたように見えますが、実際はリソース不足です）。

診断／クリーンアップ：

ddev exec "ps aux | grep -v grep | grep -E 'vendor/bin/drush|php /var/www'"
ddev exec "pkill -f 'vendor/bin/drush'"

関連する注意点：

1. 時間のかかる Drush 操作（大規模アップグレードでの updb、キャッシュをクリアした直後の cr）は、十分なタイムアウトを設定し、バックグラウンドで一度だけ実行してください。短いタイムアウトで何度も試さないでください。終了するたびに孤立プロセスが追加されます。
2. ハングしたために終了した updb でも、実際の処理はすでに完了していることがあります。更新フックはフックごとに記録されます。再実行したり慌てたりする前に、実際に何が実行されたかを確認してください。

ddev mysql -e "SELECT value FROM key_value WHERE collection='system.schema' AND name='<module>'"
ddev mysql -N -e "SELECT value FROM key_value WHERE collection='post_update' AND name='existing_updates'" | grep -o "<module>_post_update_[a-z0-9_]*"

Docker Engine の異常（DDEV で試行錯誤する前に確認）

phpunit が終了コード 137 で終了する、バックグラウンドジョブが途中で終了する、ddev exec のたびにイメージの全面的な再ビルドが始まる、または ddev start のたびに「container name already in use」と表示される場合、DDEV の問題に見えても、実際はアプリのプロセスが残った状態で Docker Desktop の エンジン がクラッシュしていることがよくあります。まず次を確認してください。

timeout 5 docker version   # hangs on the Server section -> engine is dead
docker ps                  # if this responds while `docker version` hangs, engine is wedged

修正：killall -9 com.docker.backend && open -a Docker を実行し、応答があるまで docker ps をポーリングしてから、ddev start を実行します。エンジン自体が停止している間は、DDEV レベルの修正（poweroff、mutagen reset など）を繰り返さないでください。どれも成功しません。再起動後は、孤立したコンテナーや、最初の Drush コマンドが遅くなる現象に注意してください：クラッシュ後に注意すべき点。

ホスト CPU の飽和（コンテナーは正常だが、リクエストがハングする）

ホストの負荷がコア数を大幅に上回り、コンテナーは正常で php -v は即座に応答する一方、すべてのリクエストと Drush のブートストラップがハングします（php-fpm ワーカーが、停滞した virtiofs ブリッジ上で request_wait_answer の状態のままブロックされています）。負荷が下がるまでは、DDEV の復旧操作を行っても解決しません。負荷を下げてから、ddev poweroff && ddev start を一度だけ実行してください。詳細：load-and-recovery.md。

復旧後にルート検出の警告とともに発生する404

復旧（Docker の再起動、mutagen のリセット、コアの更新）の直後にルート検出の警告とともに404が発生し、ddev drush cr で解決しない場合、通常は APCu に古いコンパイル済みコンテナが残っています。DB の cache_container は最新でも、php-fpm のオペコードキャッシュには変更前のコードが保持されています。修正方法：docker restart ddev-<project>-web を実行して APCu を新しくします。キャッシュを再度クリアするのではありません。

コンテナが正常と報告されているのにルーターの TLS がリセットされる

ddev describe ですべて正常と表示され、docker ps で ddev-router が正常と報告されているにもかかわらず、https://<project>.ddev.site への curl がすぐに失敗し、終了コード35（TLS ハンドシェイク中に「Connection reset by peer」）が返されます。アプリには問題がなく、ルーターが応答不能になっています。

アプリとルーターを切り分ける（ルーターを完全に迂回します）：

ddev exec "curl -s -o /dev/null -w '%{http_code}' http://localhost/<path>"

修正方法：

docker restart ddev-router

Docker Desktop の overlay2 I/O エラー

Docker Desktop が不安定な状態になり、次のような overlay2 または containerd の I/O エラーが発生する場合：

Error response from daemon: error creating temporary lease: write /var/lib/desktop-containerd/daemon/io.containerd.metadata.v1.bolt/meta.db: input/output error

Error response from daemon: open /var/lib/docker/overlay2/...: input/output error

Docker Desktop を通常の方法で終了して再起動するだけでは不十分です。Activity Monitor または killall -9 Docker / killall -9 com.docker.hyperkit を使って、Docker のプロセスをすべて強制終了してから、Docker Desktop を再起動してください。破損した状態を解消できるのは、完全な強制終了だけです。

「readdirent bad message」版：一時的な overlay2 の不具合ではなく、コンテナメタデータレベルでの VM ディスク破損を示します。ddev start を繰り返しても解決しません。再起動を繰り返すのではなく、破損したコンテナのメタデータディレクトリを隔離してください（nsenter で alpine コンテナに入り、問題のある /var/lib/docker/containers/<id> ディレクトリを別の場所へ mv します）。

コンテナが Unhealthy になる／Mutagen の同期が停止する

Docker のクラッシュまたは強制終了後、DDEV が不安定な状態になり、次のような問題が発生することがあります。

• ddev start が「Starting Mutagen sync process...」で停止する
• Web コンテナが unhealthy と報告される（phpstatus:FAILED、mailpit:FAILED）
• ddev mutagen reset が「CreateOrResumeMutagenSync Failure」で失敗する

修正方法（順番に実行してください）：

# 1. Full power off to clean up all containers and networks
ddev poweroff

# 2. Start fresh
ddev start

ddev poweroff で解決しない場合：

# 1. Stop DDEV
ddev stop

# 2. Reset the Mutagen daemon
~/.ddev/bin/mutagen daemon stop
~/.ddev/bin/mutagen daemon start

# 3. Reset Mutagen sync (removes Docker volume, forces full resync)
ddev mutagen reset

# 4. Start fresh
ddev start

トラブルシューティング中の監視コマンド：

ddev mutagen status -l      # Detailed sync status
ddev mutagen monitor        # Real-time sync progress
docker inspect --format "{{ json .State.Health }}" ddev-<project>-web  # Container health

ディスク使用量：ls や du の結果を鵜呑みにしない

ls -la はスパースファイル（例：Docker.raw）の論理サイズを報告するため、実際にディスク上で使用されている容量を大幅に上回ることがあります。APFS では、スナップショット間で共有されているコピーオンライトクローンが二重にカウントされるため、du は使用量を過大に報告します。どちらも「この操作で実際にどれだけの容量が必要になるか／空くか」には答えられません。操作の直前と直後に取得した df の差分だけを信頼してください。

---

関連スキル

• @drupal-config-mgmt - 設定管理ワークフロー
• @drupal-contrib-mgmt - Composer によるモジュール管理
• @drupal-at-your-fingertips - Drupal の一般的なパターン

---

公式ドキュメント：https://ddev.readthedocs.io Drupal DDEV クイックスタート：https://ddev.readthedocs.io/en/stable/users/quickstart/ コミュニティサポート：https://discord.gg/5wjP76mBJD