wp-env startでタイムアウトエラー (ETIMEDOUT) が発生し起動できない場合の解決策

会社と自宅で異なるPCを利用して開発しており、dockerを利用してwp-envでいつものようにローカル環境を立ち上げようとしたのですが、タイムアウトエラーが連続してしまい、2時間くらいハマってしまいました。

同じように困っている方がいたら参考にして見てください。

解決策
具体的な症状
1. エラーログの例
2. 特徴的な挙動
具体的な原因
1. iCloud プライベートリレーによる通信の干渉
2. なぜ wp-env が影響を受けるのか
解決策の紹介

解決策

結論から。

macOS の「iCloud プライベートリレー」をオフにする。

これだけで、wp-env が外部（WordPress.org や GitHub）のリソースを正常に取得できるようになり、タイムアウトが解消されます。

具体的な症状

npm run wp-start や npx wp-env start を実行した際、以下のようなエラーが発生して停止してしまいました。

エラーログの例

250msという極めて短時間でタイムアウトしてしまっていました。

✖ Reading configuration.
RequestError
    at ClientRequest.<anonymous> (.../node_modules/got/dist/source/core/index.js:970:111)
...
AggregateError [ETIMEDOUT]: 
    at internalConnectMultiple (node:net:1122:18)
    at internalConnectMultiple (node:net:1190:5)
    at Timeout.internalConnectMultipleTimeout (node:net:1716:5)
 {
  code: 'ETIMEDOUT',
  timings: {
    ...
    phases: {
      wait: 1,
      dns: 3,
      tcp: undefined,
      tls: undefined,
      request: undefined,
      total: 250
    }
  }
}

特徴的な挙動

実行からエラーまでが非常に早い: 通常のネットワークタイムアウト（30秒など）ではなく、250ms〜300ms 程度で即座にエラーになります。
curl などは通る: ターミナルから curl -I https://ja.wordpress.org などは成功するのに、node プロセス（wp-env）の通信だけが遮断されます。
Node.js v18 / v20 / v22 以降で顕著: 新しい Node.js のネットワークスタック（Happy Eyeballs アルゴリズム）を利用している場合に発生しやすい傾向があります。

具体的な原因

iCloud プライベートリレーによる通信の干渉

macOS の「iCloud プライベートリレー」は、DNS リクエストや HTTP 通信を Apple のプロキシサーバー経由で暗号化して送信する機能です。

なぜ wp-env が影響を受けるのか

wp-env は内部で got という通信ライブラリを使用しており、起動時に WordPress 本体（zip）やプラグインの存在確認・ダウンロードを行います。

プライベートリレーが有効な環境では、Node.js が名前解決（DNS）やソケット接続を行おうとする際、Apple のプロキシ層と競合が発生し、OS 側が「不正な接続試行」または「到達不能」と判断して 即座に TCP 接続を破棄 (Drop) してしまいます。その結果、プログラム側には ETIMEDOUT として通知されます。

解決策の紹介

以下のいずれかの方法で通信制限を解除できます。

方法1：プライベートリレーを完全にオフにする（推奨）

開発環境を安定させるために、システム全体でオフにする方法です。

Mac の 「システム設定」 を開く。
一番上の 「ユーザー名（Apple Intelligence / iCloud）」 をクリック。
「iCloud」 ＞ 「プライベートリレー」 を選択。
スイッチをオフにする。

方法2：特定のネットワークのみ制限を解除する

自宅の Wi-Fi など、特定の環境でのみ機能を無効にしたい場合に有効です。

「システム設定」 ＞ 「ネットワーク」 ＞ 「Wi-Fi」 を開く。
接続中のネットワークの 「詳細…」 ボタンをクリック。
「IPアドレスのトラッキングを制限」 をオフにする。
- 注: これにより、その Wi-Fi ネットワーク上でのみプライベートリレーが実質的に無効化されます。