wp-env 入門

@wordpress/env パッケージ (wp-env) を使用すると、追加の構成なしでプラグインやテーマのビルド用、テスト用のローカル WordPress 環境をセットアップできます。

このガイドに従って実行する前に、Node.js 開発ツール をインストールしてください。

クイックスタート

1. オペレーティングシステムごとの説明に従って、Docker Desktop をダウンロードし、インストール、起動する。
2. ターミナルで npm -g install @wordpress/env を実行し、wp-env をグローバルにインストールする。
3. ターミナルで、既存のプラグインディレクトリ、テーマディレクトリ、または新しい作業ディレクトリに移動する。
4. ターミナルで wp-env start を実行して、ローカルの WordPress 環境を起動する。
5. スクリプトの実行後、http://localhost:8888/wp-admin にアクセスし、ユーザー名 admin とパスワード password を使用して WordPress ダッシュボードにログインする。

Docker Desktop のセットアップ

wp-env ツールは Docker を使用して WordPress サイト実行用の仮想マシンを作成します。Docker Desktop アプリケーションは、中小企業、個人利用、教育、非商用のオープンソースプロジェクト向けに無料で提供されています。詳しくは FAQ をご覧ください。

以下のリンクから、使用中のオペレーティングシステム用の Docker Desktop をダウンロードして、インストールしてください。

• Docker Desktop for Mac
• Docker Desktop for Windows
• Docker Desktop for Linux

20.04.1より前のバージョンの Ubuntu を使用している場合は、後述する追加のトラブルシューティングノートを参照してください。

インストールに成功したら、Docker Desktop アプリケーションを起動し、プロンプトに従ってセットアップしてください。ほとんど推奨 (デフォルト) 設定を使うべきですが、Dockerアカウントの作成は任意です。

wp-env のインストールと実行

wp-env を使用すると、Docker で WordPress のローカル環境を構築できます。Docker Desktop のセットアップが完了したら、ターミナルを開いて wp-envをインストールしてください。以下のコマンドを実行します。

npm -g install @wordpress/env

このコマンドは wp-env をグローバルにインストールするため、任意のディレクトリからコマンドを実行できます。インストールが完了し、利用できることを確認するには wp-env --version を実行し、バージョン番号が表示されることを確認してください。

次に、ターミナルで既存のプラグインディレクトリ、テーマディレクトリ、または新しい作業ディレクトリに移動し、以下を実行します。

wp-env start

スクリプトの実行が完了したら、ローカル環境に http://localhost:8888 でアクセスします。ユーザー名 admin、パスワード password で WordPress ダッシュボードにログインできます。

Gutenberg を含むいくつかのプロジェクトには、独自の wp-env 設定が含まれています。ドキュメントを参照すると、代わりに npm run start wp-env を実行するよう指示しているかもしれません。

Docker 環境の制御に関する詳細については、@wordpress/env パッケージ を参照してください。

wp-env を実行する場所

wp-env ツールは実質的にどこからでも実行できます。1つのプラグインを開発する場合、開発中のプラグインのディレクトリから wp-env start を実行してください。自動的にプラグインディレクトリがマウントされ、プラグインが有効化されます。同じ方法はテーマでも動作します。開発中のテーマのディレクトリでコマンドを実行してください。

プラグインでもテーマでもないディレクトリから wp-env start を実行すると、汎用の WordPress 環境が作成されます。スクリプトは以下の警告を表示しますが、意図したものであれば無視してください。

!! Warning: could not find a .wp-env.json configuration file and could not determine if 'DIR' is a WordPress installation, a plugin, or a theme.

!! 警告: .wp-env.json 構成ファイルが見つかりません。’DIR’ が WordPress インストールか、プラグインか、テーマか判別できません。

また .wp-env.json 構成ファイルを使用すると、複数のプラグインやテーマと動作する環境を作成できます。構成の詳細については @wordpress/env パッケージを参照してください。

wp-env のアンインストールやリセット

最初からやり直したい場合や、アンインストールする場合の手順です。

• WordPress のデータベースをリセットして、クリーンにしたいだけであれば、wp-env clean all を実行する。
• 特定のプロジェクトのローカル環境を完全に削除するには、wp-env destroy を実行する。
• wp-env ツールをグローバルにアンインストールするには、 npm -g uninstall @wordpress/env を実行する。

トラブルシューティング

一般的なエラー

wp-envを使用すると、エラー Error while running docker-compose command (docker-compose コマンドの実行中にエラー) がよく発生します。

• Docker Desktop が開始され、実行されていることを確認する。
• Docker Desktop ダッシュボードでログを確認し、再起動するか、既存の仮想マシンを削除する。
• そして wp-env start を再実行する。

エラー Host is already in use by another container (ホストはすでに他のコンテナで使用中) が表示される場合は、

• 開始したいコンテナが既に実行されている、または別のコンテナがすでに起動しています。コンテナを開始したディレクトリから wp-env stop を実行して、既存の実行中のコンテナを停止する。
• wp-env を起動したディレクトリが分からなければ、docker stop $(docker ps -q) ですべてのコンテナを停止する。ただし、これはすべての Docker コンテナを停止するため、注意して使用してください。
• そして wp-env start を再実行する。

Ubuntu での Docker セットアップ

20.04.1より前のバージョンの Ubuntu を使用していると、wp-env を使用してローカルの WordPress 環境をセットアップする際に、エラーが発生する可能性があります。

これを解決するには、まず Docker のインストールガイドに従ってください。docker-compose も必要なため、別途インストールする必要があるかもしれません。Docker compose ドキュメントを参照してください。

Docker と wp-env をインストールできたら、wp-env がグローバルに設定されていると仮定して、ディレクトリで wp-env start を実行してみてください。以下のエラーが発生したら

ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?

If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable.

エラー: http+docker://localhost で Docker デーモンに接続できませんでした。実行していますか ?
通常と異なる場所にある場合は、DOCKER_HOST 環境変数に URL を指定してください。

まず、Docker が起動していることを確認してください。ps -ef | grep docker を実行して確認すると、次のように出力されるはずです。

/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

Docker が起動していなければ、sudo systemctl start docker.service を実行して、サービスを起動してみてください。

Docker が起動している場合は、WordPress 環境の通信の試みに対してリッスンしていません。以下のサービスの override ファイルを追加して、tcp でリッスンするようにします。Docker デーモンのリモートアクセスを設定する方法については、この Docker ドキュメントを参照してください。

# /etc/systemd/system/docker.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376

コマンドラインからサービスを再起動します。

sudo systemctl daemon-reload
sudo systemctl restart docker.service

サービスを再起動した後、環境変数 DOCKER_HOST を設定し、wp-env を起動します。

export DOCKER_HOST=tcp://127.0.0.1:2376
wp-env start

これで環境が http://localhost:8888 にセットアップされたはずです。

追加のリソース

• @wordpress/env (公式ドキュメント)
• Docker Desktop (公式ドキュメント)
• wp-env を使用した素早く、お手軽なローカル WordPress 開発 (WordPress Developer Blog)
• wp-env: WordPress のシンプルなローカル環境 (Make WordPress Core Blog)
• wp-env 基本ダイアグラム (Excalidraw)

原文