@wordpress/env
Topics
wp-env
を使用してプラグインやテーマのビルド用とテスト用の WordPress ローカル環境を簡単にセットアップできます。シンプルにインストールできて構成する必要もありません。
クイック (tl;dr) インストラクション
Docker が動作していることを確認し、以下のコマンドを実行してください。
$ cd /path/to/a/wordpress/plugin
$ npm -g i @wordpress/env
$ wp-env start
http://localhost:8888 (ユーザー名: admin
、パスワード: password
) でローカル環境が利用できます。
前提ソフトウエア
wp-env
を使用するにはまず Docker をインストールしてください。インストールの詳細については以下の OS ごとのドキュメントを参照してください。Windows、macOS、Linux
Node.js と npm も必要です。wp-env
の開発には最新の LTS バージョンの Node.js を使用しているため、これを推奨します。
インストール
グローバルパッケージとしてのインストール
前提ソフトウエアをインストールを確認できたら、グローバルに wp-env
をインストールできます。
$ npm -g i @wordpress/env
これで wp-env
を使うことができます !
ローカルパッケージとしてのインストール
プロジェクトにすでに package.json がある場合、wp-env
をローカルパッケージとして使用することもできます。まず wp-env
を開発依存としてローカルにインストールします。
$ npm i @wordpress/env --save-dev
この時点で、ローカルのプロジェクトレベルの wp-env を npx
で使用できます。これは npm
とともに自動的にインストールされるユーティリティです。npx
は node モジュールを通してインストールされた wp-env などのバイナリを見つけます。例: npx wp-env start --update
。
npx
を使いたくなければ、package.json を変更し、npm scripts
(https://docs.npmjs.com/misc/scripts) にコマンドを追加します。
"scripts":{"wp-env":"wp-env"}
この方法で wp-env
をインストールした場合、この文書で説明するすべての wp-env
コマンドの前に npm run
を追加してください。たとえば
# npm に対してではなく、スクリプト (wp-env) にフラグを渡すには、別の二重ダッシュ(--)を追加する必要があります。
$ npm run wp-env start -- --update
と実行します。以後は次のような形式のみ記述します。
$ wp-env start --update
使用方法
環境の開始
まず Docker が実行されていることを確認してください。確認するにはシステムトレイ、またはメニューバーの Docker アイコンをクリックします。
次に WordPress プラグインやテーマを含むディレクトリーに移動してください。
$ cd ~/gutenberg
ローカル環境を開始します。
$ wp-env start
Web ブラウザーで http://localhost:8888 を開きます。ローカルのプラグインやテーマがインストール、有効化された状態で WordPress が表示されます。デフォルトのログインアカウントはユーザー名 admin
、パスワード password
です。
環境の停止
ローカル環境を停止するには以下を実行します。
$ wp-env stop
一般的な問題のトラブルシューティング
以下のトラブルシューティングを順に実行することで多くの一般的な問題を解決できます。
1. wp-env
が動作していることの確認
まず wp-env
が動作していることを確認します。現在実行中の Docker コンテナ一覧を出力します。
$ docker ps
リストにはデフォルトで3つのエントリーが表示されます。ポート 8888 の wordpress
、ポート 8889 の tests-wordpress
、ポート 3306 の mariadb
です。
2. ポート番号の確認
デフォルトでは wp-env
はポート 8888 を使用し、ローカル環境が http://localhost:8888 で利用可能になります。
別のサーバーと衝突しないように wp-env
の使用するポートを構成できます。wp-env
を開始する際に WP_ENV_PORT
環境変数を指定してください。
$ WP_ENV_PORT=3333 wp-env start
docker ps
を実行し PORTS
列を参照すると、現在 wp-env
がどのポートを使用しているかを調べることができます。
.wp-env.json
ファイル内にポート番号を指定することもできますが、環境変数が指定されるとそちらが優先されます。
3. 更新と wp-env
の再起動
wp-env
を再起動すると、内部で使用される Docker コンテナが再起動され、多くの問題を解消します。
wp-env
を再起動するには、wp-env start
を再実行するだけです。自動的にコンテナを停止し、起動します。引数に --update
を渡すと、更新をダウンロードし、WordPress を再設定します。
$ wp-env start --update
4. Docker の再起動
Docker を再起動すると、内部で使用する Docker コンテナとボリュームが再起動され、多くの問題を解消します。
Docker を再起動するには
- システムトレイ、または、メニューバーの Docker アイコンをクリックする。
- Restart を選択する。
Docker の再起動後、wp-env
を起動します。
$ wp-env start
5. データベースのリセット
ローカル環境の使用するデータベースをリセットすると、多くの問題、特に WordPress のインストールに関する問題が解消します。
データベースをリセットするには
⚠️ 警告: 次のコマンドは、ローカル WordPress 環境内の投稿、ページ、メディア等を完全に削除します。
$ wp-env clean all
$ wp-env start
6. すべてを破壊して、最初からやり直す 🔥
上のすべてがうまくいかない場合、wp-env destroy
を使用してローカルの Docker コンテナ、ボリューム、ファイルを強制的に削除できます。ゼロからやり直すことができます。
すべてを破壊するには
⚠️ 警告: 次のコマンドは、ローカル WordPress 環境内の投稿、ページ、メディア等を完全に削除します。
$ wp-env destroy
# This new instance is a fresh start with no existing data:
$ wp-env start
7. デバッグモードと生成された docker ファイルの確認
wp-env
は裏側で docker を使用しています。生成された docker-compose ファイルを調べると何が起きているかを理解できます。
wp-env
をデバッグモードで開始します。
wp-env start --debug
wp-env
dockerComposeConfigPath
を含む構成情報を出力します。
ℹ Config:
...
"dockerComposeConfigPath": "/Users/$USERNAME/.wp-env/5a619d332a92377cd89feb339c67b833/docker-compose.yml",
...
同梱された WordPress PHPUnit テストファイルの使用
wp-env
にはデフォルトで、インストールされる WordPress のバージョンに対応した WordPress の PHPUnit テストファイル が含まれます。環境変数 WP_TESTS_DIR
は、各コンテナ内のこれらのファイルの場所を指定します。これらのファイルが環境に含まれるため、パッケージを使用したり、自分でインストールしてマウントしたりする必要はありません。これらのファイルを使用したくない場合は、環境変数 WP_TESTS_DIR
を無視して、好きな場所から読み込めます。
wp-tests-config.php
ファイルのカスタマイズ
環境内にはデフォルトで wp-tests-config.php
ファイルがありますが、独自のファイルを使いたい場合もあるでしょう。WordPress には WP_TESTS_CONFIG_FILE_PATH
定数があり、これを使用するとテストに使用する wp-config.php
ファイルを変更できます。これを bootstrap.php
ファイル内の任意のパスに設定すると、環境に含まれるファイルの代わりに、選択したファイルが使用されます。
Xdebug の使用
wp-env 環境には Xdebug がインストールされていますが、デフォルトではオフになっています。Xdebug を有効にするには wp-env start
コマンドの --xdebug
フラグを使用します。以下ではフラグの動作について説明します。
# Xdebug モードを "debug" に設定 (ステップデバッグ用)
wp-env start --xdebug
# Xdebug モードを "off" に設定
wp-env start
# リストしたそれぞれの Xdebug モードを有効
wp-env start --xdebug=profile,trace,debug
npm run
を使って wp-env
を実行する場合、たとえば、Gutenberg リポジトリで作業する場合や、wp-env
にプロジェクトのローカルな依存関係がある場合、--xdebug
コマンドの前に、忘れずに二重ダッシュを追加してください。
npm run wp-env start -- --xdebug
# Alternatively, use npx:
npx wp-env start --xdebug
これを忘れると、wp-env start
コマンドの代わりに --xdebug
パラメータが npm に渡され、無視されます。
Xdebgu のモードと定義については Xdebug ドキュメント を参照してください。
Xdebug 3 のみをインストールするため、Xdebug としては PHP 7.2 (デフォルト) 以上が必要です。phpVersion
に古いバージョンに設定されている場合、Xdebug はインストールできません。
Xdebug の IDE サポート
IDE から Xdebug に接続するには以下の IDE 設定を使用できます。この JSON は VS Code の launch.json
形式 (詳細についてはこちら) と PHP デバッグエクステンション でテストされました。なお、パスマッピングは特定のプラグインを指しています。これを wp-env インスタンス内の作業中のソースコードを指すよう更新してください。
port
と pathMappings
のみを IDE で使用する形式に変換する必要があります。
{"name":"Listen for XDebug","type":"php","request":"launch","port":9003,"pathMappings":{"/var/www/html/wp-content/plugins/gutenberg":"${workspaceFolder}/"}}
リポジトリに .vscode/launch.json
ファイルを作成したら、それを グローバル gitignore ファイル に追加すると良いでしょう。ファイルはプライベートになり、リポジトリにはコミットされません。
IDE Xdebug 設定が有効になればあとはデバッガを起動し、PHP コードの任意の行にブレークポイントを置き、ブラウザをリフレッシュするだけです。
まとめ:
- Xdebug を有効化して wp-env を起動する:
wp-env start --xdebug
- もしまだなら IDE 用に適切な Xdebug エクステンションをインストールする。
- IDE デバッガーがポート
9003
と wp-env 内の正しいソースファイルを使用するよう構成する。 - デバッガーを起動し、PHP コードの任意の行にブレークポイントを置く。
- wp-env の稼働する URL をリフレッシュすれば、ブレークポイントに達する。
コマンドリファレンス
wp-env
は生成したファイルを wp-env
ホームディレクトリー、デフォルトでは ~/.wp-env
に置きます。例外は Linux で Snap パッケージの互換性のため、ファイルは ~/wp-env
に置かれます。wp-env
ホームディレクトリーには各プロジェクトのサブディレクトリーが /$md5_of_project_path
として作成されます。wp-env
ホームディレクトリーを変更するには、WP_ENV_HOME
環境変数を設定してください。例えば WP_ENV_HOME="something" wp-env start
と実行すると、プロジェクトファイルは現行ディレクトリーからの相対パスでディレクトリー ./something/$md5_of_project_path
にダウンロードされます。
wp-env start
start コマンドは WordPress 環境をインストールし初期化します。これには指定された任意のリモートのソースのダウンロードも含まれます。wp-env
はデフォルトでは構成ファイルが変更されない限り、環境を更新も再考性もしません。ソースを更新し、構成オプションを再度適用するには wp-env start --update
を使用してください。既存のコンテンツは上書きされません。
wp-env start
WordPress 開発環境をポート 8888 (http://localhost:8888) で (ポートは WP_ENV_PORT で指定可)、
テスト環境を 8889 (http://localhost:8889) で (ポートは WP_ENV_TESTS_PORT で指定可) 開始します。
コマンドは WordPress インストールディレクトリー、プラグインやテーマのディレクトリー、
または .wp-env.json ファイルのあるディレクトリーで実行する必要があります。最初のインストール後、
'--update' フラグを使用して更新をマップされたソースにダウンロードし、WordPress 構成オプションに
再適用します。
引数:
--update ソースの更新をダウンロードし、WordPress 構成に適用する
[boolean] [デフォルト: false]
wp-env stop
wp-env stop
実行中の WordPress 開発環境、テスト環境を停止し、ポートを解放します。
wp-env clean
wp-env clean [environment]
WordPress データベースをクリアします。
引数:
environment どの環境のデータベースをクリアするか。
[string] [選択: "all", "development", "tests"] [デフォルト: "tests"]
wp-env run [container] [command]
run コマンドは、シェルセッションを開いたり、WP-CLI コマンドの呼び出しに使用できます。
いくつかのケースでは、コンテナに渡したいオプションを wp-env
が奪ってしまう場合があります。これは、wp-env
が同じオプションを宣言する場合、例えば、--debug
、--help
、--version
などで発生します。これを防ぐには引用符 ("
) を使用してください。wp-env
は、引用符内のすべてをコマンド引数とみなします。
たとえば、WP-CLI
のヘルプメッセージを表示するには、
wp-env run cli "wp --help"
引用符がない場合、wp-env
は、コンテナにオプションを渡す代わりに、自身のヘルプメッセージを表示します。コマンドが正しく渡らない問題が発生した場合は、引用符を使用してください。
wp-env run <container> [command..]
動作している Docker コンテナ内で任意のコマンドを実行します。
"container" パラメータは Docker サービス "development"、"tests"、"cli"の1つを指定する必要が
あります。wp-cli コマンドを実行するには "cli" または "tests-cli" サービスを使用してください。
また bash のようなシェルセッションや、WordPress インスタンス内の WordPress シェルを開くためにも
使用できます。たとえば `wp-env run cli bash` は開発 WordPress インスタンス内で bash を開きます。
引数:
container コマンドを実行するコンテナ [string] [必須]
command 実行するコマンド [array] [デフォルト: []]
オプション:
--help ヘルプの表示 [boolean]
--version バージョン番号の表示 [boolean]
--debug デバッグ出力の有効化 [boolean] [でファルト: false]
例:
development インスタンス上のユーザーの表示
wp-env run cli wp user list
⠏ Running `wp user list` in'cli'.
ID user_login display_name user_email user_registered roles
1 admin admin wordpress@example.com 2020-03-05 10:45:14 administrator
✔ Ran `wp user list` in'cli'. (in 2s 374ms)
tests インスタンスで投稿を作成
wp-env run tests-cli "wp post create --post_type=page --post_title='Ready'"
ℹ Starting 'wp post create --post_type=page --post_title='Ready'' on the tests-cli container.
Success: Created post 5.
✔ Ran `wp post create --post_type=page --post_title='Ready'` in'tests-cli'. (in 3s 293ms)
tests インスタンスで WordPress シェルを開き、PHP コマンドを実行
wp-env run tests-cli wp shell
ℹ Starting 'wp shell' on the tests-cli container. Exit the WordPress shell with ctrl-c.
Starting 31911d623e75f345e9ed328b9f48cff6_mysql_1 ... done
Starting 31911d623e75f345e9ed328b9f48cff6_tests-wordpress_1 ... done
wp> echo( 'hello world!' );
hello world!
wp> ^C
✔ Ran `wp shell` in'tests-cli'. (in 16s 400ms)
development インスタンスでのプラグインやテーマのインストール
wp-env run cli wp plugin install custom-post-type-ui
Creating 500cd328b649d63e882d5c4695871d04_cli_run ... done
Installing Custom Post Type UI (1.9.2)
Downloading installation package from https://downloads.wordpress.org/plugin/custom-post-type-ui.zip...
The authenticity of custom-post-type-ui.zip could not be verified as no signature was found.
Unpacking the package...
Installing the plugin...
Plugin installed successfully.
Success: Installed 1 of 1 plugins.
✔ Ran `plugin install custom-post-type-ui` in'cli'. (in 6s 483ms)
注意: ホスト OS によっては、プラグインやテーマをインストールしようとすると、エラーが発生する場合があります (例: Warning: Could not create directory.
)。これは通常、コンテナ内で使用されているユーザー ID が、wp-env
で作成、マウントしたディレクトリへの書き込み権限を持っていないことが原因です。この問題を解決するには、wp-env
で作成したディレクトリから直接 docker-compose
コマンドを使用します。run
コマンドに、-u $(id -u)
と -e HOME=/tmp
オプションを追加してください。
$ cd ~/wp-env/500cd328b649d63e882d5c4695871d04
$ docker-compose run --rm -u $(id -u) -e HOME=/tmp cli [plugin|theme] install <plugin|theme>
wp-env destroy
wp-env destroy
WordPress 環境を破壊します。WordPress 環境と関連する Docker コンテナ、ボリューム、
ネットワークを削除し、ローカルファイルを削除します。
wp-env logs
wp-env logs [environment]
指定した WordPress 環境の PHP と Docker のログを表示します。
引数:
environment どの環境のログを出力するか
[string] [選択: "development", "tests", "all"] [デフォルト: "development"]
オプション:
--help ヘルプの表示 [boolean]
--version バージョン番号の表示 [boolean]
--debug デバッグ出力の有効化 [boolean] [デフォルト: false]
--watch ログをウオッチする [boolean] [デフォルト: true]
wp-env install-path
WordPress 環境ファイルへの絶対パスを出力します。
例:
$ wp-env install-path
/home/user/.wp-env/63263e6506becb7b8613b02d42280a49
.wp-env.json
WordPress のインストールや開発環境で使用するプラグインやテーマをカスタマイズできます。.wp-env.json
ファイルに指定し、同じディレクトリーで wp-env
を実行してください。
.wp-env.json
はテストと開発の両方のインスタンスに適用可能なオプションとして、6つのフィールドをサポートします。
フィールド | タイプ | デフォルト | 説明 |
---|---|---|---|
"core" | string|null | null | 使用する WordPress のバージョンまたはビルド。null の場合、最新リリース版 |
"phpVersion" | string|null | null | 使用する PHP のバージョン。null が指定されると wp-env は WordPress の製品版リリースで使用されるデフォルトバージョンを使用する。 |
"plugins" | string[] | [] | 環境にインストール、有効化するプラグインのリスト |
"themes" | string[] | [] | 環境にインストールするテーマのリスト |
"port" | integer | 8888 (テストインスタンスでは 8889 ) | インストールに使用するポート番号。インスタンスには ‘http://localhost:8888‘ でアクセスできる |
"config" | Object | 以下を参照 | wp-config.php の定数とその値のマッピング |
"mappings" | Object | "{}" | WordPress インスタンス内にマウントされるローカルディレクトリと WordPress ディレクトリのマッピング |
注意: ポート番号に関する環境変数 (WP_ENV_PORT
と WP_ENV_TESTS_PORT
) は .wp-env.json の値に優先します。
core
、plugins
、themes
、mappings
フィールドに指定できる文字列のタイプを以下に示します。
タイプ | 形式 | 例 |
---|---|---|
相対パス | .<path>|~<path> | "./a/directory" , "../a/directory" , "~/a/directory" |
絶対パス | /<path>|<letter>:\<path> | "/a/directory" , "C:\\a\\directory" |
GitHub リポジトリ | <owner>/<repo>[#<ref>] | "WordPress/WordPress" , "WordPress/gutenberg#trunk" , ブランチが指定されない場合、wp-env はリポジトリのデフォルトブランチを使用する |
SSH リポジトリ | ssh://user@host/<owner>/<repo>.git[#<ref>] | "ssh://git@github.com/WordPress/WordPress.git" |
ZIP ファイル | http[s]://<host>/<path>.zip | "https://wordpress.org/wordpress-5.4-beta2.zip" |
リモートのソースは ~/.wp-env
内の一時ディレクトリーにダウンロードされます。
さらにキー env
は上の任意のオプションを個々の環境ごとに上書きできます。たとえば次の .wp-env.json
ファイルでは
{"plugins":["."],"config":{"KEY_1":true,"KEY_2":false},"env":{"development":{"themes":["./one-theme"]},"tests":{"config":{"KEY_1":false},"port":3000}}}
development インスタンスでは、cwd
がプラグインに、one-theme
がテーマにマップされ、KEY_1 が true に、KEY_2 が false に設定されます。デフォルトのポートは引き続き 8888 が使用されます。
tests インスタンスでは、cwd
がプラグインマップされますがテーマのマップはありません。また KEY_2 は false のままですが、KEY_1 は false で、デフォルトのポートは 3000 で上書きされます。
この強力な機能により環境ごとにオプションを変更できます。
.wp-env.override.json
このファイルのフィールド値は、.wp-env.json の値よりも優先されます。このファイルをバージョンコントロールの対象外とすると、常に希望のローカル環境で上書きできて便利です。注意: plugins
や themes
などのオプションはマージされません。結果として .wp-env.override.json ファイル内で plugins
を設定すると、ベースレベルの構成でリストされたすべてのプラグインを上書きします。マージされるキーは config
と mappings
のみです。すなわちデフォルト値を失うこと無く自身の wp-config 値を設定できます。
デフォルト wp-config 値
development インスタンスでは次の wp-config 値がデフォルトとして定義されます。
WP_DEBUG: true,
SCRIPT_DEBUG: true,
WP_PHP_BINARY: 'php',
WP_TESTS_EMAIL: 'admin@example.org',
WP_TESTS_TITLE: 'Test Blog',
WP_TESTS_DOMAIN: 'localhost',
WP_SITEURL: 'http://localhost',
WP_HOME: 'http://localhost',
tests インスタンスでは同じすべての値が定義されますが、WP_DEBUG
と SCRIPT_DEBUG
は false に設定されます。
これらは config
設定内に値を設定することで上書きできます。この値を null
に設定すると、定数を完全に定義できなくなります。
また URL を参照する値には環境で指定されたポート番号が含まれます。たとえば testsPort: 3000, port: 2000
を設定すると、WP_HOME
は tests インスタンスでは http://localhost:3000
、development インスタンスでは http://localhost:2000
になります。
例
最新の安定版 WordPress + 現行ディレクトリーのプラグインをインストールし有効化
この設定はプラグイン開発時に便利です。
{"core":null,"plugins":["."]}
最新の開発版 WordPress + 現行ディレクトリーのプラグインをインストール
この設定はプラグイン開発時に、最新のコアの変更の影響を見る上で便利です。これは、環境変数 WP_ENV_CORE
からも設定できます。
{"core":"WordPress/WordPress#master","plugins":["."]}
ローカルの wordpress-develop
+ 現行ディレクトリーのプラグインをインストール
プラグインと WordPress コアで同時に作業する場合に便利です。
wordpress-develop
の build を実行している場合は、core
を build
ディレクトリに指定します。
{"core":"../wordpress-develop/build","plugins":["."]}
もし、wordpress-develop
を dev モード(例: watch コマンド dev
や dev ビルド build:dev
)で実行している場合は、core
を src
ディレクトリに指定します。
{"core":"../wordpress-develop/src","plugins":["."]}
完全なテスト環境
インテグレショーンテストで便利です。古いバージョンの WordPress と異なるプラグインの組み合わせで互いに与える影響をテストできます。
{"core":"WordPress/WordPress#5.2.0","plugins":["WordPress/wp-lazy-loading","WordPress/classic-editor"],"themes":["WordPress/theme-experiments"]}
mu-plugins とマッピングディレクトリの追加
マッピング構成を使用して mu-plugins を追加できます。マッピング構成を使用すると、WordPress インストール内の任意の場所にディレクトリをマウントできます。サブディレクトリにマウントすることも可能です。ただし theme-1 は有効化されないことに注意してください。
{"plugins":["."],"mappings":{"wp-content/mu-plugins":"./path/to/local/mu-plugins","wp-content/themes":"./path/to/local/themes","wp-content/themes/specific-theme":"./path/to/local/theme-1"}}
インスタンスのプラグインやテーマを有効化しない
デフォルトでは plugins
キーのすべてのプラグインは有効化されます。この動きを避けるには mappings
キーを使用してください。この方法は常には有効化すべきでない、テスト用のプラグインがある場合に便利です。
{"plugins":["."],"mappings":{"wp-content/plugins/my-test-plugin":"./path/to/test/plugin"}}
テスト環境にのみプラグインをマップする
1つの環境でのみプラグインを有効化し、他の環境では有効化しない場合、env.<envName>
を使用して1つの環境でのみオプションを設定できます。ここではテストインスタンスでのみ現行ディレクトリとテストプラグインを有効化しています。他のインスタンスではプラグインは有効化されません。
{"plugins":["."],"env":{"tests":{"plugins":[".","path/to/test/plugin"]}}}
カスタムポート番号
wp-env
にカスタムポート番号を指定することで、他の wp-env
インスタンスとの衝突を避けられます。
{"plugins":["."],"port":4013,"env":{"tests":{"port":4012}}}
PHP バージョンの指定
互換性やテストのため、wp-env
では特定の PHP バージョンを使用できます。これは環境変数 WP_ENV_PHP_VERSION
からでも設定できます。
{"phpVersion":"7.2","plugins":["."]}
このパッケージへのコントリビュート
これは、Gutenberg プロジェクトの一部である、個別パッケージです。このプロジェクトは、monorepo として構成されています。複数の自己完結型ソフトウェアパッケージで構成されており、それぞれが特定の目的を持ちます。この monorepo のパッケージは npm で公開され、WordPress や他のソフトウェアプロジェクトで利用されています。
このパッケージや Gutenberg 全体へのコントリビュートの詳細については、プロジェクトのメインのコントリビューターガイドを参照ください。

最終更新日: