wp-playground

WordPress Playground

使用する場面

• フルスタック環境を構築せずに、使い捨ての WordPress を立ち上げてプラグインやテーマをテストします。
• Playground Blueprints（JSON）をローカルで実行または反復します。
• 共有や CI に使える、再現可能なサイトのスナップショットを作成します。
• 問題を再現するため、WP/PHP のバージョンをすばやく切り替えます。
• 隔離された Playground で Xdebug を使ってプラグインやテーマのコードをデバッグします。

必要な入力

• ホストマシンの準備：Node.js ≥ 20.18、npm/npx が使用可能であること。
• マウントするプロジェクトのパス（--auto-mount または明示的なマウントマッピング）。
• 希望する WP/PHP のバージョン（任意。デフォルトは最新の WP、PHP 8.3）。
• Blueprint を実行する場合は、その場所または URL。
• 9400 番ポートが競合する場合に使用するポート。
• Xdebug が必要かどうか。

手順

0) ガードレール

• Playground インスタンスは一時的で、SQLite を使用します。本番データは絶対に指定しないでください。
• CLI を実行する前に、Node ≥ 20.18（node -v）を確認してください。
• ローカルコードをマウントする場合は、シークレットが含まれていないことを確認してください。Playground はファイルをインメモリ FS にコピーします。

1) ローカルで手早く起動（自動マウント）

cd <plugin-or-theme-root>
npx @wp-playground/cli@latest server --auto-mount

• デフォルトでは http://localhost:9400 で開きます。プラグインやテーマを自動検出してインストールします。
• 必要に応じて --wp=<version> / --php=<version> を追加します。
• 従来型のフルインストールがすでに存在する場合は、--skip-wordpress-setup を追加してツリー全体をマウントします。

2) 手動マウントまたは複数のマウント

• 自動マウントでは不十分な場合（複数のプラグイン、mu-plugins、カスタムコンテンツなど）は、--mount=/host/path:/vfs/path を使用します（繰り返し指定できます）。
• インストーラーのブートストラップフローを実行するには、インストール前に --mount-before-install でマウントします。
• リファレンス：references/cli-commands.md

3) Blueprint を実行（サーバー不要）

npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>

• スクリプトによるセットアップや CI の検証に使用します。リモート URL とローカルファイルに対応しています。
• 必要に応じて --blueprint-may-read-adjacent-files を指定し、ローカル Blueprint 内の同梱アセットを使用できるようにします。
• 構造と一般的なフラグについては、references/blueprints.md を参照してください。

4) 共有用のスナップショットを作成

npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip

• Playground に読み込んだり、バグ報告に添付したりできる ZIP を作成します。

5) Xdebug によるデバッグ

• --xdebug（または CLI のリリースに応じて --enable-xdebug）を指定して起動し、IDE キーを公開します。その後、CLI 出力に表示されたホストとポートに VS Code/PhpStorm から接続します。
• プラグインやテーマのデバッグには、--auto-mount と組み合わせます。
• チェックリスト：references/debugging.md

6) バージョンの切り替え

• WP のバージョンを固定するには --wp= を使用し（例：6.9.0）、互換性のテストには --php= を使用します。
• 機能が Gutenberg trunk に依存する場合は、利用可能であれば最新の WP リリースとプラグインの組み合わせを優先してください。Playground のイメージでは、安定版 WP と同梱の Gutenberg が使用されます。

7) ブラウザーのみでのワークフロー（CLI 不要）

• URL フラグメントまたはクエリパラメーターを使って、手早くプレビューを起動します。
  • フラグメント：https://playground.wordpress.net/#<base64-or-json-blueprint>
  • クエリ：https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>
• ライブ Blueprint Editor（playground.wordpress.net）でスキーマのヘルプを参照しながら Blueprint を作成します。JSON を貼り付けて、共有可能なリンクをコピーします。

検証

• マウントしたコードが有効であることを確認します（プラグインが一覧に表示され有効になっていること、テーマが選択されていること）。
• Blueprint やスナップショットの場合は、--verbosity=debug を指定して再実行し、手順が実行されたことを確認します。
• 対象を絞ったスモークテスト（例：ブラウザーのターミナルが公開されている場合は、Playground シェル内で wp plugin list を実行）または UI のクリック操作による確認を行います。

失敗時の対処／デバッグ

• CLI が Node に関するエラーを出して終了する：≥ 20.18 にアップグレードします。
• マウントが適用されない：パスを確認し、絶対パスを使用して、--verbosity=debug を追加します。
• Blueprint がローカルアセットを読み込めない：--blueprint-may-read-adjacent-files を追加します。
• ポートがすでに使用されている：--port=<free-port> を指定します。
• UI の動作が遅い／ロックされる：--experimental-multi-worker が有効な場合は無効にします。または、CPU に負荷のかかる実行のスループットを向上させるために有効にします。

エスカレーション

• PHP 拡張機能やネイティブ DB アクセスが必要な場合、Playground は適さない可能性があります。フル WP スタックまたは wp-env/Docker に切り替えてください。
• ブラウザーのみでの埋め込みや VS Code 拡張機能の詳細については、上流ドキュメントを参照してください：https://wordpress.github.io/wordpress-playground/