フリーランスでWeb制作をしている矢野です。
前回の記事で、ポートフォリオサイトのWordPressオリジナルテーマを自作した話を書きました。
今回はその開発環境の話で、Local by FlywheelのようなGUIツールではなく、Docker製のwp-env（@wo
rdpress/env）でローカル環境を構築した経緯とハマったポイントをまとめます。
なぜLocalではなくwp-env（Docker）を選んだか
WordPressのローカル開発環境というと、Local by Flywheelのような専用GUIツールを使う人が多いと思います。
私も最初はそちらも検討しました。
ただ、今回はあえてDockerベースのwp-envを選びました。
理由はシンプルで、Dockerに慣れておくことが今後の現場での仕事やエンジニアとしてのスキルに直結する と考えたからです。
WordPress専用のGUIツールに慣れても、その知識は他の環境に転用しにくいですが、Dockerの経験はどんな 案件でも活きてきます。
もう1つの理由は、@wordpress/envがWordPress公式が提供するツールだという安心感です。
サードパーティのツールに依存するよりも、公式ツールに乗っておいた方が長く付き合えると判断しました 。
セットアップ手順
セットアップ自体はシンプルです。
まずDocker Desktopをインストールし、起動しておきます。
続いて、テーマのディレクトリで@wordpress/envをインストールします。
npm install --save-dev
@wordpress/envテーマ開発用の設定は、.wp-env.jsonに記述します。
私の場合は以下のようなシンプルな設定にしました。
{
"core": null,
"phpVersion": "8.2",
"themes": ["."],
"config": {
"WP_DEBUG": true
},
"testsEnvironment": false
}themesに"."を指定することで、今作業しているディレクトリそのものをテーマ
としてWordPressにマウントしてくれます。
あとは起動コマンドを叩くだけです。
npx @wordpress/env startこれでhttp://localhost:8888にWordPressの環境が立ち上がります。
ハマったポイント①：「wp-env」という名前の罠
ここが一番最初につまずいたポイントです。
セットアップ後、何気なく次のコマンドを実行しました。
BEFORE（うまくいかなかったコマンド）
npx wp-env start一見動いているように見えるのですが、これは@wordpress/envとは無関係の、たまたま同じ「
wp-env」という名前を持つ別のnpmパッケージが実行されていました。
しばらく気づかずに操作していて、意図した挙動にならず首をかしげる時間を過ごしてしまいました。
AFTER（正しいコマンド）
npx @wordpress/env startパッケージのスコープ（@wordpress/）まで含めてフルネームで実行しないといけない、とい
う当たり前のことに気づくまで、少し時間がかかりました。
以降は必ず@wordpress/envとスコープ付きで実行するように徹底しています。
ハマったポイント②：Docker Desktopが重くなる・起動しない
開発を進めている途中、突然Docker Desktopが重くなり、Macのファンが唸るほどCPUを使い切ってしまったことがありました。
調べてみると、com.docker.backendというプロセスが暴走していたことが原因でした。
このプロセスを一度終了させ、Docker Desktopを再起動することで復旧しました。
また別の日には、Docker Desktop自体が起動しない状態にも遭遇しています。
このときは、画面の裏に隠れていたサブスクリプション案内のモーダルが、起動処理をブロックしていたこ とが原因でした。
利用規約への同意とセットアップウィザードを完了させることで、無事に起動できるようになりました。
ハマったポイント①：「wp-env」という名前の罠ここが一番最初につまずいたポイントです。
セットアップ後、何気なく次のコマンドを実行しました。
BEFORE（うまくいかなかったコマンド）
npx wp-env start一見動いているように見えるのですが、これは@wordpress/envとは無関係の、たまたま同じ「
wp-env」という名前を持つ別のnpmパッケージが実行されていました。
しばらく気づかずに操作していて、意図した挙動にならず首をかしげる時間を過ごしてしまいました。
AFTER（正しいコマンド）
npx @wordpress/env startパッケージのスコープ（@wordpress/）まで含めてフルネームで実行しないといけない、とい
う当たり前のことに気づくまで、少し時間がかかりました。
以降は必ず@wordpress/envとスコープ付きで実行するように徹底しています。
ハマったポイント②：Docker Desktopが重くなる・起動しない
開発を進めている途中、突然Docker Desktopが重くなり、Macのファンが唸るほどCPUを使い切ってしまったことがありました。
調べてみると、com.docker.backendというプロセスが暴走していたことが原因でした。
このプロセスを一度終了させ、Docker Desktopを再起動することで復旧しました。
また別の日には、Docker Desktop自体が起動しない状態にも遭遇しています。
このときは、画面の裏に隠れていたサブスクリプション案内のモーダルが、起動処理をブロックしていたこ とが原因でした。
利用規約への同意とセットアップウィザードを完了させることで、無事に起動できるようになりました。
Dockerを使った開発では、こうしたアプリ自体の不調にも向き合う必要がある、という点は覚えておいて損 はないと思います。
ハマったポイント③：カスタム投稿タイプのURLが404になる
テーマ側でカスタム投稿タイプ（work）を新しく登録したときのことです。
投稿の一覧・詳細ページのURLにアクセスすると、404エラーが表示されてしまいました。
原因は、カスタム投稿タイプを追加した際にパーマリンクのリライトルールが更新されていなかったことで した。
wp-adminの「設定」→「パーマリンク設定」を開いて保存し直すか、wp-cliで直接反映させることで解決でき ます。
npx @wordpress/env run cli wp rewrite
flushこのコマンド1つで直りますが、原因を知らないと地味に時間を溶かしてしまうポイントだと思います。
まとめ
Docker経験がゼロの状態から始めましたが、今回まとめた3つのハマりポイントさえ押さえておけば、大きく つまずかずに環境構築できるはずです。
- コマンドは必ず
npx @wordpress/envとスコープ付きで実行する - Docker Desktopが重い・起動しないときは、プロセスの暴走やモーダルのブロックを疑う
- カスタム投稿タイプ追加後は
wp rewrite flushでリライトルールを更新する
次回は、本番環境（XServer）へのデプロイでハマった話を書く予定です。