wp-env

@wordpress/env (wp-env)

プラグイン、テーマ、コア向けの、設定不要で Docker ベースのローカル WordPress 開発環境です。

使用するタイミング

• ユーザーがローカル WordPress 開発環境のセットアップを依頼している
• プロジェクトに .wp-env.json ファイルが含まれている
• ユーザーが wp-env、@wordpress/env、または Docker ベースの WordPress 開発に言及している
• ユーザーが WP-CLI コマンドや PHPUnit テストを実行したい、またはローカルで Xdebug を使ってデバッグしたい
• トリアージで、ローカル WordPress インスタンスが必要なプラグインまたはテーマのプロジェクトが検出された

wp-env と wp-playground のどちらを使うべきですか？ 手早くローカル WordPress を使う場合は、デフォルトで wp-playground スキルを優先してください。より高速で、使い捨て可能で、Docker も不要です。タスクで実際に必要な場合は wp-env を使用してください。

• リポジトリにすでに .wp-env.json が含まれている
• 実際の MySQL データベースが必要（データベースに対する PHPUnit、wp db コマンド、再起動後も保持されるデータ）
• 環境内で任意のコマンドを実行する必要がある（シェルアクセス、Composer、wp-env run による完全な WP-CLI）
• WordPress コアまたは Gutenberg のチェックアウトである
• ユーザーが明示的に wp-env または Docker を求めている

wp-env は、Playground をランタイムとして使うことで Docker なしでも実行できます（実験的機能）。npx @wordpress/env start --runtime=playground を使用します。これは同じ .wp-env.json で制御される、あくまで wp-env です。そのため、すでに wp-env 設定があるプロジェクト向けの Docker 不要の代替手段として扱い、第三の選択肢とは見なさないでください。MySQL が SQLite に置き換わり、wp-env run と個別のテスト環境も利用できなくなりますが、これらはそもそも wp-env を選ぶ主な理由の一部です。wp-env の設定なしで手早く Docker 不要の WordPress を使う場合は、wp-playground スキルを直接使用してください。

必要な入力

1. Docker の状態 -- Docker がインストールされ、実行中であることを確認します：docker info
2. Node.js のバージョン -- 18.12.0 以上である必要があります：node -v
3. プロジェクトの種類 -- プラグイン、テーマ、またはサイト全体（.wp-env.json、プラグインヘッダー、style.css のテーマヘッダーを確認）
4. 既存の設定 -- .wp-env.json と、存在する場合は .wp-env.override.json を読み取ります

手順

1. wp-env をインストールする

# Global (recommended)
npm -g install @wordpress/env

# Or project-local
npm i @wordpress/env --save-dev
# Then use: npx wp-env start

2. 環境を起動する

wp-env start

デフォルトの認証情報：

• URL： http://localhost:8888/wp-admin/
• ユーザー名： admin
• パスワード： password

よく使う起動オプション：

• wp-env start --update -- 最新のソースを取得して再設定します
• wp-env start --xdebug -- Xdebug を有効にします（デバッグモード）
• wp-env start --xdebug=profile,trace -- 複数の Xdebug モードを有効にします
• wp-env start --auto-port -- デフォルトのポートが使用中の場合、利用可能なポートを探します

3. 自動検出（設定ファイルがない場合）

.wp-env.json がない場合、wp-env は現在のディレクトリをスキャンします。

検出された種類	検出方法	自動設定
プラグイン	ルートにある .php ファイル内の Plugin Name: ヘッダー	{ "plugins": ["."] }
テーマ	style.css 内の Theme Name: ヘッダー	{ "themes": ["."] }
コア	wp-includes/version.php が存在する	{ "core": "." }

4. .wp-env.json で設定する

プロジェクトのルートに配置します。すべてのフィールドは省略可能です。

{
  "core": null,
  "phpVersion": "8.1",
  "plugins": [
    ".",
    "https://downloads.wordpress.org/plugin/akismet.zip",
    "WordPress/classic-editor"
  ],
  "themes": [],
  "port": 8888,
  "multisite": false,
  "phpmyadmin": false,
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  },
  "mappings": {
    "wp-content/mu-plugins": "./mu-plugins"
  },
  "lifecycleScripts": {
    "afterStart": "wp-env run cli wp rewrite structure /%postname%/"
  }
}

ソース文字列の形式（core、plugins、themes、mappings 用）

形式	例
ローカルパス	"."、"./path"、"../path"
GitHub の簡略表記	"WordPress/classic-editor"、"owner/repo#branch"
ZIP URL	"https://downloads.wordpress.org/plugin/akismet.zip"
Git SSH	"ssh://user@host/repo.git#ref"

注意： WordPress.org のプラグイン／テーマのスラッグ（"akismet" のような名前だけのもの）は機能しません。完全な ZIP URL を使用してください。

.wp-env.override.json によるローカルオーバーライド

個人用の設定（Git で無視されます）を記述するには、.wp-env.json と同じ場所に .wp-env.override.json を作成します。config と mappings のみがマージされ、plugins や themes の配列を含むその他すべてのフィールドは、ベース設定を完全に置き換えます。

5. コンテナ内でコマンドを実行する

# WP-CLI commands
wp-env run cli wp user list
wp-env run cli wp plugin list
wp-env run cli wp option update blogname "My Site"
wp-env run cli "wp rewrite structure /%postname%/"

# Run commands in a specific directory
wp-env run cli --env-cwd=wp-content/plugins/my-plugin composer install

# PHPUnit tests
wp-env run cli --env-cwd=wp-content/plugins/my-plugin vendor/bin/phpunit

# Pass flags with -- separator
wp-env run cli php -- --version

# MySQL access
wp-env run mysql mysql -- --user=root --password=password wordpress

使用可能なコンテナ：mysql、wordpress、cli、composer、phpmyadmin。

6. 環境を管理する

wp-env stop                    # Stop and free ports
wp-env reset development       # Reset dev database (keeps test)
wp-env reset all               # Reset all databases
wp-env logs                    # Stream PHP/Docker logs
wp-env logs --no-watch         # Print logs and exit
wp-env status                  # Show URLs, ports, config
wp-env status --json           # Machine-readable status
wp-env cleanup                 # Remove containers/volumes (keep images)
wp-env destroy                 # Remove everything including images

7. Xdebug のセットアップ

wp-env start --xdebug          # Enable debug mode
wp-env start --xdebug=coverage # For code coverage
wp-env start                   # Disable Xdebug (restart without flag)

モード：debug、profile、trace、develop、coverage。

IDE はポート 9003 で待ち受けます。VS Code の launch.json には次の設定が必要です。

{
  "type": "php",
  "request": "launch",
  "name": "Listen for Xdebug",
  "port": 9003,
  "pathMappings": {
    "/var/www/html/wp-content/plugins/your-plugin": "${workspaceFolder}"
  }
}

8. マルチサイト

{ "multisite": true, "plugins": ["."] }

検証

• wp-env status で、正しいポートを使用する実行中のコンテナーが表示される
• http://localhost:8888/wp-admin/ で WordPress の管理画面が読み込まれる
• wp-env run cli wp plugin list で、想定されるプラグインが表示される
• 開発中のプラグイン／テーマが WordPress の管理画面に表示される
• データベースのリセットが機能する：wp-env reset development

障害モード／デバッグ

症状	原因	対処方法
「Cannot connect to Docker daemon」	Docker が起動していない	Docker Desktop を起動する
「Port 8888 already in use」	ポートが競合している	--auto-port を使用するか、.wp-env.json でカスタム port を設定する
プラグインが表示されない	メインの PHP ファイルに Plugin Name: ヘッダーがない	標準的なプラグインヘッダーコメントを追加する
「Could not find a valid source」	設定内のソース文字列が無効	wp.org のプラグインには、単独のスラッグではなく完全な ZIP URL を使用する
ソースの変更後も環境が古いまま	Docker ボリュームがキャッシュされている	wp-env start --update または wp-env destroy && wp-env start を実行する
画面が真っ白／PHP エラー	データベースが破損している	wp-env reset all && wp-env start を実行する
オーバーライドが反映されない	マージ方法が正しくない	オーバーライドの plugins／themes はベース配列を置き換えます。マージされるのは config／mappings のみです
テスト環境にアクセスできない	ポートが正しくない	テスト環境はデフォルトでポート 8889 で実行されます
Xdebug が接続しない	IDE が待ち受けていないか、ポートが正しくない	IDE が正しい pathMappings を使用してポート 9003 で待ち受けていることを確認する
npm のグローバルインストールで権限エラーが発生する	Node がシステムパスにインストールされている	nvm を使用するか、ローカルにインストールする：npm i -D @wordpress/env を実行し、npx wp-env で起動する

エスカレーション

• wp-env の範囲外にある Docker の問題（ネットワーク、ディスク容量、WSL2 バックエンド）
• wp-env と競合するカスタム Docker Compose 設定
• 標準的ではない Docker セットアップを必要とする CI/CD パイプラインとの統合
• WordPress Playground のランタイム（--runtime=playground）は実験的であり、機能の互換性が限られています

参考資料

• 公式ドキュメント
• スタートガイド
• ソースコード