【WordPress】@wordpress/env（wp-env）の使い方｜ブロック開発用のローカルWordPress環境をDockerで作る方法

カスタムブロックを作るには、当然ながら動かすための WordPress が必要です。とはいえ MAMP を入れて PHP のバージョンを合わせて…という準備を、プラグインひとつのために毎回やるのは面倒です。@wordpress/env（コマンド名は wp-env）は、プラグインやテーマのディレクトリで npx wp-env start と打つだけで、WordPress 本体・データベース・PHP がまとめて立ち上がる公式ツールです。この記事では導入から .wp-env.json での設定、WP-CLI の実行方法、起動しないときの対処までを解説します。

wp-env はブロック開発のための使い捨て WordPress

@wordpress/env は WordPress 公式が配布している Node 製のツールで、Docker を使って WordPress の実行環境を組み立ててくれます。特徴は設定ファイルを一切書かなくても動くことです。開発中のプラグインのディレクトリでコマンドを叩けば、そのディレクトリが wp-content/plugins/ の中にマウントされた状態の WordPress が起動し、ブラウザーですぐ動作確認ができます。

環境そのものは Docker コンテナなので、壊れても wp-env destroy で消してやり直せます。ローカルマシンに PHP や MySQL をインストールする必要はなく、プラグインごとに独立した WordPress を持てるのも利点です。@wordpress/scripts でビルドしながら wp-env で確認する、というのがカスタムブロック開発の標準的な組み合わせになっています。

Docker Desktop を用意する

wp-env は自分で PHP を動かすわけではなく、Docker のコンテナを操作しているだけです。そのため Docker が動いていることが前提になります。macOS や Windows なら Docker Desktop をインストールし、起動しておいてください。Node.js も必要ですが、こちらはブロック開発ですでに入っているはずです。

準備ができているかは、ターミナルで次のコマンドが正常に応答するかで確認できます。エラーが出る場合は Docker Desktop が起動していません。

docker -v
node -v

プロジェクトに導入して起動する

開発しているプラグイン（またはテーマ）のディレクトリで、開発用の依存としてインストールします。グローバルに入れる方法もありますが、プロジェクトごとにバージョンを固定できるローカルインストールのほうが安全です。

npm install --save-dev @wordpress/env

毎回 npx wp-env ... と打つのが煩わしければ、package.json の scripts に登録しておきます。チームで開発するときも、コマンド名を揃えられるので分かりやすくなります。

{
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "env": "wp-env",
    "env:start": "wp-env start",
    "env:stop": "wp-env stop"
  },
  "devDependencies": {
    "@wordpress/env": "^10.0.0",
    "@wordpress/scripts": "^30.0.0"
  }
}

あとは起動するだけです。初回はイメージのダウンロードと WordPress のインストールが走るため数分かかりますが、2回目以降はすぐ立ち上がります。

npx wp-env start

# package.json に登録した場合
npm run env:start

初期状態のログイン情報

起動が終わると、ターミナルに WordPress の URL が表示されます。既定では http://localhost:8888 が開発用サイトで、管理画面には http://localhost:8888/wp-admin からアクセスします。ユーザー名は admin、パスワードは password です。ローカル専用の環境なので、この固定の情報のままで構いません。

あわせて、もうひとつの WordPress が http://localhost:8889 に立ち上がっています。こちらは自動テスト用のインスタンスで、データベースが開発用とは別に用意されています。テストで投稿を作ったり消したりしても、開発用サイトの内容が壊れないようになっているわけです。普段の動作確認では 8888 のほうだけを使います。

よく使うコマンド

覚えるコマンドは多くありません。日常的に使うのは start と stop で、あとは困ったときの手段として残りを知っていれば十分です。

stop と destroy の違いは押さえておいてください。stop は電源を切るようなもので、投稿やプラグインの有効化状態はそのまま残ります。一方 destroy は環境ごと捨てるコマンドなので、次に start したときはまっさらな WordPress になります。

run コマンドで WP-CLI を実行する

wp-env run は、どのコンテナで実行するかを第1引数で指定します。WP-CLI を使うときは cli コンテナを指定し、そのあとに wp から始まるコマンドを続けて書きます。

# インストール済みプラグインの一覧を見る
npx wp-env run cli wp plugin list

# 動作確認用の投稿をまとめて作る
npx wp-env run cli wp post generate --count=10

# パーマリンク構造を変更する
npx wp-env run cli wp rewrite structure '/%postname%/'

テスト用インスタンス（8889）に対して実行したいときは、コンテナ名を tests-cli に変えます。また --env-cwd オプションを付けると、コンテナ内の作業ディレクトリを指定できます。プラグインのディレクトリで composer install を走らせたい、といった場面で役に立ちます。

npx wp-env run cli --env-cwd=wp-content/plugins/my-block composer install

.wp-env.json で環境をカスタマイズする

設定ファイルなしでも動きますが、WordPress のバージョンを指定したり、一緒に使うプラグインを入れたりしたくなったら、プロジェクトのルートに .wp-env.json を置きます。書き換えたあとは wp-env start を実行し直すと反映されます。

{
  "core": "WordPress/WordPress#6.6",
  "phpVersion": "8.2",
  "plugins": [ ".", "https://downloads.wordpress.org/plugin/query-monitor.zip" ],
  "themes": [ "./test-theme" ],
  "port": 8888,
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  },
  "mappings": {
    "wp-content/mu-plugins": "./mu-plugins"
  }
}

それぞれの項目の意味は次のとおりです。

plugins と themes はパスの書き方が柔軟で、"./my-other-plugin" のような相対パス、"https://downloads.wordpress.org/plugin/xxx.zip" のような zip の URL、"WordPress/gutenberg#trunk" のような GitHub 上のリポジトリを混ぜて書けます。Gutenberg プラグインの開発版と一緒に動作確認したい、といった使い方ができます。

カレントディレクトリは自動でマウントされる

wp-env が手軽な最大の理由がこれです。コマンドを実行したディレクトリがプラグインとして認識できる構造（プラグインヘッダーを持つ PHP ファイルがある）なら、そのまま wp-content/plugins/ にマウントされて有効化されます。テーマとして認識できる構造なら wp-content/themes/ 側にマウントされます。だから設定ファイルなしで wp-env start するだけで、自分のブロックが入った WordPress が手に入るわけです。

マウントは実体をコピーするのではなく、ローカルのディレクトリを参照しています。エディターでファイルを保存すればコンテナ内にも即座に反映されるので、wp-scripts start でビルドを走らせたまま画面をリロードするだけで変更を確認できます。

注意したいのは、plugins を自分で書いたときにカレントディレクトリの指定が必要になる点です。他のプラグインを追加したくて plugins を書いたのに自作プラグインが消えた、というときは、配列の先頭にカレントディレクトリを表す "." を入れ忘れていないか確認してください。

ローカル固有の設定は .wp-env.override.json に書く

.wp-env.json はチームで共有するファイルなので、Git にコミットします。しかし「自分のマシンだけポートが空いていない」「自分だけ PHP 8.3 で試したい」といった事情を書き込むと、他のメンバーに迷惑がかかります。

そのために用意されているのが .wp-env.override.json です。同じ階層に置くと、.wp-env.json の同名の項目を上書きします。書き方は同じで、変更したい項目だけを書けば十分です。

{
  "port": 9000,
  "phpVersion": "8.3"
}

このファイルは個人設定なので、.gitignore に追加してコミットしないようにしておきます。

node_modules/
build/
.wp-env.override.json

開発用とテスト用で設定を分ける

設定は env キーを使って、開発用（development）とテスト用（tests）で分けることもできます。外側に共通の設定を書き、env の中に差分だけを書く形です。

{
  "plugins": [ "." ],
  "config": {
    "WP_DEBUG": true
  },
  "env": {
    "tests": {
      "config": {
        "WP_DEBUG": false
      }
    }
  }
}

wp-env が起動しないとき

Docker が起動していない

いちばん多いのがこれです。wp-env start が Docker に接続できずエラーで止まる場合、まず Docker Desktop が起動しているかを確認してください。アプリを開いた直後はまだ内部のサービスが立ち上がりきっていないことがあるので、「Engine running」といった表示になるまで待ってから実行し直します。

ターミナルで docker ps を実行して、エラーにならずコンテナの一覧（空でも構いません）が表示されれば準備完了です。

ポート 8888 が他のアプリに使われている

ポートが埋まっていると起動に失敗します。別のプロジェクトの wp-env を立ち上げっぱなしにしている、あるいは Jupyter など 8888 番を使うツールが動いている、というのがよくある原因です。

他のプロジェクトが原因なら、そちらのディレクトリで npx wp-env stop を実行すれば解放されます。両方を同時に動かしたいときは、.wp-env.json の port（とテスト用の testsPort）をずらしてください。設定ファイルを触りたくなければ、環境変数 WP_ENV_PORT でも指定できます。

WP_ENV_PORT=9999 npx wp-env start

設定を変えても反映されない・状態が壊れた

.wp-env.json を編集したら wp-env start を実行し直す必要があります。それでも古い状態のままだったり、データベース周りのエラーで起動しなくなったりしたときは、wp-env destroy で環境を作り直すのがいちばん早い解決策です。

npx wp-env destroy
npx wp-env start

destroy はコンテナとボリュームを削除するため、その環境で作った投稿や設定はすべて消えます。消えて困るデータがないのがローカル開発環境の良いところですが、動作確認用に作り込んだ投稿がある場合は、事前に wp-env run cli wp db export などで書き出しておくと安心です。なお、ソースコードはローカルのディレクトリにあるものをマウントしているだけなので、destroy しても失われません。

エラーの内容が分からないとき

画面が真っ白になる、管理画面で 500 エラーが出る、といった場合は wp-env logs を使います。PHP のエラーメッセージがそのまま流れてくるので、自作プラグインの構文ミスやフック内のエラーはここで特定できます。

まとめ

@wordpress/env は、Docker さえ動いていれば npx wp-env start の一行でブロック開発用の WordPress が手に入るツールです。プラグインやテーマのディレクトリがそのままマウントされるので、設定ファイルを書かなくても自作ブロックの動作確認を始められます。

もう少し踏み込みたくなったら .wp-env.json を置いて、core で WordPress のバージョン、phpVersion で PHP のバージョン、plugins で一緒に入れるプラグインを指定します。このファイルを Git で共有すれば、チーム全員が同じ条件で動作確認できます。自分のマシンだけの都合は .wp-env.override.json に逃がしておきましょう。

そして覚えておきたいのが、環境が壊れても wp-env destroy でいつでも作り直せるという点です。設定を試すハードルが下がるので、対応する WordPress のバージョンを変えて確認する、PHP のバージョンを上げて警告を洗い出す、といった検証も気軽に行えます。

参考ページ

• @wordpress/env – Block Editor Handbook | WordPress Developer Resources
• Development Environment – Block Editor Handbook | WordPress Developer Resources
• Get started with wp-env – Block Editor Handbook | WordPress Developer Resources
• Commands | WP-CLI Command