ddev

Name: ddev
Author: michtio

github.com/michtio開発8677 回インストール1 日前に更新

リポジトリ

ddev について

Craft CMS 開発者向けの DDEV ワークフローガイドです。プロジェクト設定、コマンド、プラグイン開発、デバッグを扱い、安全なコンテナ運用と Craft CLI の活用を重視します。

主な機能

01Craft プロジェクトの初期設定
02DDEV の基本コマンド案内
03Craft CLI の操作方針
04プラグイン依存関係とテスト分離
05ブラウザデバッグの手順

活用シーン

01Craft CMS の新規プロジェクト開始
02コンテナ内での依存関係導入とテスト実行
03テンプレート、DOM、ネットワークリクエストのデバッグ

MCP 対応

Chrome DevTools MCP を設定し、Claude Code からページ、コンソールログ、ネットワークリクエスト、DOM を調査する方法を説明します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/michtio/craftcms-claude-skills --skill ddev

インストール後、Claude Code で/ddevを入力して読み込まれたか確認します。

詳細

Craft CMS 開発向け DDEV

ドキュメント

DDEV ドキュメント：https://docs.ddev.com/en/stable/
Craft CMS クイックスタート：https://docs.ddev.com/en/stable/users/quickstart/#craft-cms
設定リファレンス：https://docs.ddev.com/en/stable/users/configuration/config/
カスタムコマンド：https://docs.ddev.com/en/stable/users/extend/custom-commands/
追加サービス：https://docs.ddev.com/en/stable/users/extend/additional-services/
Vite 統合：https://docs.ddev.com/en/stable/users/usage/developer-tools/#nodejs

DDEV の機能について不明な点がある場合は、該当するドキュメントページを WebFetch してください。

よくある落とし穴

ddev composer install ではなく ddev exec composer install を使う — DDEV の短縮コマンドは、パス解決と環境設定を処理します。必ず短縮コマンドを使ってください。
ddev craft up が migrate/all と project-config/apply の両方を実行することを忘れる — pull やデプロイ後に、これらを個別に実行する必要はありません。
Vite 開発サーバーの公開に web_extra_exposed_ports ではなく ports を使う — ports は複数の DDEV プロジェクトを実行する際に競合を引き起こします。web_extra_exposed_ports は Traefik 経由でルーティングされ、HTTPS でも動作します。
ddev composer global require を実行する — グローバルパッケージはコンテナ内にインストールされ、再起動すると消失します。プロジェクトレベルの依存関係のみをインストールしてください。
nodejs_version を設定しながら、ホスト上で npm install を実行する — 設定したバージョンと一致させるには、ddev npm を使ってコンテナ内で Node を実行する必要があります。
コンテナの実行中に .ddev/config.yaml を編集し、再起動しない — 設定の変更を反映するには ddev restart が必要です。
複数データベース構成で --target-db=db を指定せずに ddev import-db を実行する — デフォルトのターゲットは db ですが、追加のデータベースを設定している場合は明示してください。
カスタマイズしたカスタムコマンドに #ddev-generated を追加する — DDEV は更新時に、このコメントが付いたファイルを上書きします。アドオン管理のコマンドにのみ使用してください。自分で管理するカスタムコマンドには付けないでください。
ホスト上で composer install を実行してから ddev composer check-cs／ddev composer phpstan を実行する — ホストの PHP バージョンが DDEV と異なる場合（例：ホストは PHP 8.4、DDEV は PHP 8.3）、vendor/composer/platform_check.php で失敗します。必ず ddev composer install を実行し、vendor/ をコンテナの PHP バージョンに合わせてください。

まず Craft CLI を使い、生 SQL は最後の手段にする

生のデータベースクエリより、常に Craft CLI コマンドを優先してください。

ddev craft users/list-admins         # not: ddev mysql -e "SELECT * FROM users WHERE admin=1"
ddev craft project-config/get system # not: reading project.yaml manually
ddev craft resave/entries            # not: UPDATE queries on content tables
ddev craft elements/delete           # not: DELETE FROM elements

CLI に相当するコマンドがない場合（テーブルスキーマの確認、特定の行のデバッグ、ミューテックスロックが固まった場合の TRUNCATE cache など）に限り、ddev mysql を使用してください。Craft CLI コマンドは、生 SQL では省略されるプロジェクト設定、検索インデックスの更新、イベント発火を処理します。

短縮コマンド

ddev exec より、常に DDEV の短縮コマンドを使ってください。

ddev composer install          # not ddev exec composer install
ddev craft up                  # not ddev exec php craft up
ddev npm install               # not ddev exec npm install
ddev craft make service        # scaffolding

Craft CMS プロジェクトタイプ

# .ddev/config.yaml
name: my-craft-site
type: craftcms
docroot: web
php_version: "8.3"
database:
  type: mysql
  version: "8.0"
nodejs_version: "20"

DDEV は次の環境変数を自動的に挿入します：CRAFT_DB_SERVER、CRAFT_DB_USER、CRAFT_DB_PASSWORD、CRAFT_DB_DATABASE、PRIMARY_SITE_URL。これらは .ddev/.env.web を介してコンテナに挿入されます。.ddev/config.yaml で disable_settings_management: true を設定すると、挿入を無効にできます。

新規プロジェクトのセットアップ

新しい DDEV + Craft プロジェクトの標準的な手順は次のとおりです。

mkdir my-craft-site && cd my-craft-site
ddev config --project-type=craftcms --docroot=web   # writes .ddev/config.yaml
ddev start
ddev composer create-project craftcms/craft         # Craft's setup wizard runs automatically

ddev composer create-project は完了時に Craft の対話型インストールウィザードを起動します。起動しない場合（または再実行が必要な場合）は、ddev craft install を使ってください。コミュニティ製のスタータープロジェクトから始める場合は、craftcms/craft をそのプロジェクトに置き換えてください。

よく使うコマンド

ddev start                     # Start the project
ddev stop                      # Stop the project
ddev restart                   # Restart containers
ddev ssh                       # SSH into web container
ddev describe                  # Show project info and URLs
ddev launch                    # Open the project in a browser
ddev launch -m                 # Open Mailpit (also --mailpit)
ddev logs                      # View container logs
ddev import-db --file=dump.sql # Import database
ddev export-db --file=dump.sql # Export database
ddev xdebug on                 # Enable Xdebug
ddev craft db/backup           # Craft database backup

インストール後の自動実行

Composer スクリプトは、インストール／更新後に craft up を自動実行します。

{
    "scripts": {
        "post-craft-update": [
            "@php craft install/check && php craft up --interactive=0 || exit 0"
        ],
        "post-update-cmd": "@post-craft-update",
        "post-install-cmd": "@post-craft-update"
    }
}

ddev craft migrate/all や ddev craft project-config/apply を手動で実行する必要はありません。ddev craft up が両方を実行し、ddev composer install/update の後に自動実行されます。

アドオン

ddev add-on get ddev/ddev-redis       # Install Redis
ddev add-on list                       # List installed add-ons
ddev add-on remove ddev/ddev-redis    # Remove add-on

Mailpit は DDEV コアに組み込まれているため、アドオンをインストールする必要はありません。送信メールは自動的に捕捉されます。ddev mailpit でウェブ UI にアクセスできます。または、ddev describe を実行すると URL が表示されます（例：https://{project}.ddev.site:8026）。

ローカルサイトの共有

ddev share                     # Expose the project on a temporary public URL

ddev share のデフォルトプロバイダーは ngrok です。利用するには、無料の ngrok.com アカウントと設定済みの ngrok 認証トークンが必要です。（--provider=cloudflared で cloudflared を代替プロバイダーとして利用できます。アカウントは不要ですが、デフォルトは ngrok です。）

カスタムコマンド

スクリプトは .ddev/commands/web/（コンテナ）または .ddev/commands/host/（ホスト）に配置します。

#!/usr/bin/env bash
## Description: Run ECS code style check
## Usage: check-cs
## Example: ddev check-cs

cd /var/www/html && composer check-cs

注：自分で管理するカスタムコマンドには #ddev-generated を付けないでください。DDEV は更新時に、そのコメントが付いたファイルを上書きします。アドオンが管理するコマンドにのみ、このコメントを付けてください。

Composer のパスリポジトリとボリュームマウント

プラグインをローカルで開発する場合、Composer のパスリポジトリはプラグインを vendor/ にシンボリックリンクします。DDEV の Docker コンテナ内でこれを機能させるには、シンボリックリンクを解決できるように、ホストのパスをボリュームマウントする必要があります。

セットアップ

composer.json — ローカルのホストパスを使用します。

{
    "repositories": [
        {
            "type": "path",
            "url": "/Users/Shared/dev/craft-plugins/v5/*"
        }
    ]
}

docker-compose のオーバーライド — 同じパスをコンテナにマウントします。.ddev/docker-compose.mounts.yaml を作成します。

services:
  web:
    volumes:
      - /Users/Shared/dev/craft-plugins:/Users/Shared/dev/craft-plugins

コンテナ内のマウントパスは、ホストのパスと完全に一致している必要があります。Composer は絶対パスのシンボリックリンクを作成するため、どちらの環境でも解決できなければなりません。/Users/Shared/dev/craft-plugins を実際のプラグインディレクトリのパスに置き換えてください。

プラグインを要求する：ddev composer require vendor/plugin-handle:@dev

よくある間違い

composer.json の url に Docker 内部のパスを使用する — パスには /var/www/... ではなく、ホストのファイルシステムのパスを指定する必要があります。
ボリュームマウントを忘れる — ddev composer install は成功しますが、コンテナ内でシンボリックリンクの参照先が存在しません。
composer.json の config に "platform": {"php": "8.3"} を設定する — 設定しないでください。DDEV は .ddev/config.yaml で PHP のバージョンを管理します。プラットフォームの上書き設定は、ホストとコンテナの間で依存関係の解決に不整合を生じさせ、DDEV によるバージョンアップグレードの適切な管理を妨げます。

Chrome DevTools MCP によるブラウザーのデバッグ

Chrome DevTools MCP サーバーを使うと、Claude Code からブラウザーに直接アクセスできます。ページの検査、コンソールログの読み取り、ネットワークリクエストの確認、スクリーンショットの撮影、DOM の操作が可能です。

インストール

claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

新しい MCP サーバーを読み込むには、Claude Code を終了して再起動してください。Chrome または Chromium の起動が必要です。DevTools Protocol の接続は MCP サーバーが自動的に処理します。

利用できる機能

機能	用途
ページの検査	レンダリングされた HTML の確認、テンプレート出力の検証、メタタグの検査
コンソールログ	Twig エラー、JS の例外、Garnish の初期化失敗の検出
ネットワークリクエスト	404 になるアセット、失敗した AJAX 呼び出し、Sprig／htmx の差し替えのデバッグ
DOM クエリ	フォームのマークアップの検証、フィールドのレンダリング確認、ARIA 属性の検証
スクリーンショット	CP テンプレートの視覚的な検証、レスポンシブテスト
ナビゲーションとログイン	CP へのログイン、プラグイン設定／編集ページへの移動

使用する場面

フロントエンドテンプレートのデバッグ — 404、アセットの欠落、レイアウトの崩れ、SEOmatic のメタタグの検証
CP テンプレートの検証 — プラグイン設定ページが正しく表示されること、編集可能なテーブルが動作すること、スライドアウトエディターが読み込まれること
Garnish／JS のデバッグ — モーダル、ドラッグ並べ替え、開閉メニューがコンソールエラーなしで初期化されること
Sprig／htmx のデバッグ — htmx のスワップに対するネットワークリクエストを監視し、レスポンスの HTML フラグメントを検証すること
認証フローのテスト — ログイン、登録、パスワードリセットをエンドツーエンドで確認すること
読み取り専用モードの検証 — allowAdminChanges がオフの状態で設定ページが正しく表示されることを確認すること
ビジュアルリグレッション — テンプレート変更の前後でスクリーンショットを撮ること

CP 認証パターン

DDEV サイトには https://{project}.ddev.site からアクセスできます。CP ページを調べるには、次の手順に従います。

https://{project}.ddev.site/{cpTrigger} に移動します
管理者の認証情報でログインします
調べるプラグイン／設定ページに移動します
コンソールで JS エラーを確認し、DOM を調べてマークアップが正しいことを確認します

プロジェクトのセットアップ

craft-project-setup スキルでは、スキャフォールディング中に Chrome DevTools MCP をインストールするかどうかを選択できます。後からインストールした場合は、プロジェクトのルートで claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest を実行します。これによりプロジェクトの .claude.json に書き込まれ、プロジェクト単位の設定として保持されます。

プラグイン独自のテストスイートを実行する

プラグインをホストプロジェクトにシンボリックリンクした場合、コンテナ内のプラグイン自身のディレクトリからテストスイートを実行します。

ddev exec --dir /var/www/html/vendor/acme/my-plugin vendor/bin/pest
ddev exec --dir /var/www/html/vendor/acme/my-plugin composer test

--dir は作業ディレクトリを設定します。これが重要な点です。markhuot/craft-pest-core は環境のオーバーライドを getcwd().'/phpunit.xml(.dist)' からのみ読み込み、--configuration= フラグは解析しません。そのため、共有ルートから実行する次の形式では、

# UNSAFE — runs the tests, but against the project's live database
ddev craft pest -- --configuration=vendor/acme/my-plugin/phpunit.xml.dist

…プラグインのテストを検出して実行する一方、プラグイン独自の CRAFT_DB_DATABASE の指定は黙って無視されます。さらに、RefreshesDatabase トレイトがバインドされていないテストスイート（ロールバックはオプトインです）と組み合わせると、テストデータが開発用データベースに永続的に書き込まれます。共有ルートからの実行は、craft-pest-core を使うテストスイートでは安全でないものとして扱ってください。

仕組み全体、分離チェックリスト、CI での同等の実行方法については、craft-pest スキルの references/isolation.md を参照してください。

Composer のパスリポジトリ経由でマウントされたプラグインでは、--dir のパスはコンテナ内のシンボリックリンク先です。そのパスを解決可能にする方法については、Composer のパスリポジトリとボリュームマウントを参照してください。

トラブルシューティング

ddev poweroff                  # Stop all DDEV projects
ddev debug router              # Debug router configuration
ddev debug capabilities        # Check Docker capabilities
ddev delete --omit-snapshot    # Remove project without snapshot

general-config の編集が反映されない（DDEV が注入する環境変数が優先される）

DDEV は .ddev/.env.web を介して Craft の環境変数（PRIMARY_SITE_URL、CRAFT_DB_* など）をコンテナに自動注入し、.ddev/config.yaml で disable_settings_management: true が設定されていない限り、ddev start／再起動のたびにこのファイルを再生成します。実際のコンテナ環境変数は cms/.env の dotenv 値より優先され、CRAFT_* 環境変数は config/general.php より優先されるため（craftcms スキルの config-bootstrap.md を参照）、.env または general.php で編集した値が、DDEV によって注入された値に黙って上書きされることがあります。

よくある症状と対処法は次のとおりです。

サイト URL／スキームが間違っている。 PRIMARY_SITE_URL は DDEV のプライマリ URL に従いますが、そのスキームは多くの場合 http です。Craft が予期しないベース URL を解決する場合は、注入されたこの変数が原因である可能性があります。サイト設定で Craft のサイト URL に別の名前の環境変数（例：SITE_URL）を指定して、DDEV の PRIMARY_SITE_URL に上書きされないようにするか、PRIMARY_SITE_URL を意図的にオーバーライドしてください。
再起動後に .env の変更が元に戻る。 .ddev/.env.web を手動で編集した場合、再起動時に再生成されます。永続的なオーバーライドは .ddev/config.yaml（web_environment）に設定するか、disable_settings_management: true を設定してファイルを自分で管理してください。

設定値が「変わらない」場合は、再度 PHP を編集する前に、解決済みの環境（ddev exec printenv | grep CRAFT_ と .ddev/.env.web）を確認してください。

Markdown 対応

ログインしてコメント

基本情報

作者: michtio
リポジトリ: michtio/craftcms-claude-skills
カテゴリ: 開発
インストール数: 77
GitHub スター: 86

問題を報告

ddev

ddev について

主な機能

活用シーン

MCP 対応

インストール

詳細

Craft CMS 開発向け DDEV

関連スキル — 必ず一緒に読み込む

ドキュメント

よくある落とし穴

まず Craft CLI を使い、生 SQL は最後の手段にする

短縮コマンド

Craft CMS プロジェクトタイプ

新規プロジェクトのセットアップ

よく使うコマンド

インストール後の自動実行

アドオン

ローカルサイトの共有

カスタムコマンド

Composer のパスリポジトリとボリュームマウント

セットアップ

よくある間違い

Chrome DevTools MCP によるブラウザーのデバッグ

インストール

利用できる機能

使用する場面

CP 認証パターン

プロジェクトのセットアップ

プラグイン独自のテストスイートを実行する

トラブルシューティング

general-config の編集が反映されない（DDEV が注入する環境変数が優先される）

コメント