WordPressをサブディレクトリ運用でHeartbeatが404になる時の修正方法
なぜサブディレクトリ運用でHeartbeatが404になるのか
WordPressにはホームURLとサイトURLの2つの設定がある。ルートで運用していればどちらもexample.comになるが、サブディレクトリ運用ではホームURLがexample.com、サイトURLがexample.com/wpのように分かれる。
この場合、AJAXのエンドポイントはexample.com/wp/wp-admin/admin-ajax.phpが正しい。ところが、Media Library Assistantにはjs/mla-define-ajaxurl-scripts.jsというファイルがあり、グローバル変数ajaxurlに /wp-admin/admin-ajax.phpというハードコードされたパスを代入するフォールバック処理が含まれている。
Heartbeatは本来heartbeatSettings.ajaxurlに正しいURLを持っているが、グローバル変数window.ajaxurlを優先して参照してしまう。このため、サブディレクトリの /wp部分が欠けたURLへリクエストが飛び、404を返す。
パスが1つ違うだけでHeartbeatが404になる流れを示している。
window.ajaxurlの値を確認して原因を特定する手順
Ajax周りの404は別の原因でも発生するため、まずはwindow.ajaxurlを確認して切り分ける。ログイン中のフロントエンドで調査するのがポイントだ。
DevToolsのConsoleでwindow.ajaxurlを確認する
ChromeやFirefoxの開発者ツールを開き、Consoleタブにwindow.ajaxurlと入力して実行する。返ってきた値が /wp-admin/admin-ajax.phpのようになっていれば、サイトURL側の /wp部分が欠けている。管理画面ではajaxurlが最初から正しい値になるため、この症状はフロントエンドでしか現れない。
Networkタブで404になっているリクエストを探す
Networkタブを開き、admin-ajax.phpという文字列で絞り込む。404と表示されているリクエストが複数回発生していれば、Heartbeatが誤ったパスへ送信している。リクエストのURLを確認すると、/wpの部分が抜けていることが分かる。
プラグインを1つずつ無効化して切り分ける
Media Library Assistantを無効化してから再度window.ajaxurlを確認すると、値がundefinedになるか正しいURLに変わる。無効化で症状が消え、再有効化で再発するならそのプラグインが原因だ。ほかのプラグインでも同様のハードコードがある可能性があるため、1つずつ確認する。
ハードコードされたajaxurlを修正する実践手順
根本的にはプラグイン側の修正を待つのが望ましい。ただし実務ではすぐに解消したいため、子テーマのfunctions.phpに一時的な修正を入れる手順を示す。
子テーマへ修正を追加してから確認するまでの流れを3手順に整理した。
子テーマのfunctions.phpにwp_add_inline_scriptを追加する
以下のコードを子テーマのfunctions.phpに追記する。admin_urlを使い、WordPressの設定から正しいパスを動的に生成してwindow.ajaxurlに代入する。wp_footerで出力するため、プラグインのスクリプトが読み込まれた後に確実に上書きできる。
function fix_heartbeat_ajaxurl_for_subdirectory() {
// 管理画面では不要なので除外する
if ( is_admin() ) {
return;
}
$ajax_url = admin_url( 'admin-ajax.php' );
echo '' . "\n";
}
add_action( 'wp_footer', 'fix_heartbeat_ajaxurl_for_subdirectory', 999 );wp_add_inline_scriptを使う手もある。ただし対象プラグインのスクリプトがHeartbeatより後に読み込まれる場合は上書きされるため、wp_footerで最後に定義するのが確実だ。子テーマを使っていない場合は、まず子テーマを作成してからfunctions.phpを編集する。
修正後にキャッシュをクリアして確認する
コードを追加したら、ブラウザキャッシュとキャッシュプラグインのキャッシュを削除する。その後、ログインしたままフロントエンドのページを開き、DevToolsのConsoleでwindow.ajaxurlを確認する。正しいパスになっていれば、NetworkタブでHeartbeatが200を返すようになる。
プラグイン本体の更新で根本解決する
Media Library Assistantでは、このajaxurlのハードコードについて開発元に報告されており、後続バージョンでの修正が見込まれる。まずは対象プラグインの最新版が出ていないかを確認する。ほかのプラグインで同じ症状を発見した場合は、開発元のサポートフォーラムやバグトラッカーに再現手順を添えて報告すると、根本修正につながりやすい。
再発を防ぐためにプラグイン側で確認したいポイント
同じ問題を避けるには、プラグイン開発者がajaxurlをハードコードしないことが最も重要だ。WP AJAX用のURLはadmin_urlかwp_localize_scriptで動的に渡すのがWordPressの標準的な作法である。サイト運営者側では、リニューアルやサブディレクトリ移設の際にHeartbeatの404が増えていないかを監視する。
アクセスログでadmin-ajax.phpに対する404が頻発していないか、定期的に確認すると早期発見できる。プラグインを新しく導入した直後に軽くフロントエンドを動かして、Networkタブを確認する習慣を付けるとよい。
よくある質問
Heartbeatが404を返すとサイトにどんな影響があるか
主にログイン中のユーザーに影響する。ページの自動保存、セッション期限の通知、投稿のロック処理などが不安定になる。編集作業中にサーバーと通信できないため、下書きの保存が失敗することがある。
Media Library Assistant以外のプラグインでも起きるか
起きる可能性がある。window.ajaxurlをハードコードで定義するプラグインはどれも同じ挙動になる。特に管理画面以外で独自のAjax処理を実装したプラグインで注意が必要だ。
wp_add_inline_scriptを追加するのは本番環境で安全か
管理画面以外のフロントエンドだけに適用するコードなので、比較的安全だ。ただしfunctions.phpの編集は必ず子テーマで行い、編集前にバックアップを取る。ステージング環境で1日程度様子を見るのが望ましい。
プラグインのJavaScriptファイルを直接編集して直せないか
直すことはできるが、プラグインの更新で上書きされるため推奨しない。子テーマのfunctions.phpに一時しのぎを置き、開発元の修正版を待つのが安全だ。
サブディレクトリからルートへ移設すれば解決するか
解決はするが、移設はサーバー設定やパーマリンク、検索エンジンへの影響が大きい。この不具合だけのために移設するのは過剰だ。まずはajaxurlの修正で対応するのが現実的だ。
この記事のポイント
- サブディレクトリ運用ではadmin-ajax.phpの正しいパスが /wp/wp-admin/ になる
- プラグインがwindow.ajaxurlをハードコードするとHeartbeatが404を繰り返す
- DevToolsのConsoleでwindow.ajaxurlを確認して原因を切り分ける
- wp_add_inline_scriptで正しいURLを渡すと即座に解消できる
- 一時しのぎは子テーマのfunctions.phpに置き、根本修正はプラグイン更新を待つ
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
WordPressサブディレクトリ環境でプラグイン管理画面が404になる原因と対処
WordPress をサブディレクトリに置いている環境で、一部プラグインの管理画面にアクセスすると「ページが見つかりません（404）」になる。これはプラグイン内部で作られた管理画面の URL が、実際のディレクトリ構造と合っていないのが主な原因だ。プラグインの更新で修正されることが多く、一時的に URL へ正しいパスを手動で加えればすぐに操作を再開できる。
なぜ管理画面のプラグインページが404になるのか
WordPress の管理画面は通常 /wp-admin/ で始まるが、Bedrock（roots.io スタック）のようなカスタム構成では、コアファイルを /wp/ の下に配置する。管理画面の URL は /wp/wp-admin/ のようにサブディレクトリが一段深くなる。ここで、プラグインが管理画面へのリンクを作る際に「/wp-admin/ はルート直下にある」という前提でコードを書いていると、リンク先が https://example.com/wp-admin/... のようにサブディレクトリを反映しない形になり、フロントエンドで処理されて結果的に404になる。
これはコアファイルの場所を変更していない標準的なインストールでは表面化しない。Bedrock や独自に /cms/ などへ配置を変えているサイトで、かつプラグインが管理画面のパスをハードコード（直書き）している場合に限って起こる。エラーログには何も残らず、ただ「ページが見つかりません」と表示されるため、原因の特定に手間取ることが多い。
上記デモのとおり、プラグインが出力したパスに /wp/ が1つ欠けているために「そんなページはフロントエンドに存在しない」と判断され、404 が返っている。見た目はありふれた存在しないページへのアクセスと変わらず、管理画面の一部だけが突然消えたように感じる。
サブディレクトリ環境で発生する404の一時的な回避策
プラグインのアップデートを待たずに、今すぐ該当画面を操作したい場合は、ブラウザのアドレスバーで404になった URL を直接編集する。たとえば /wp-admin/ の直前に、自分の環境で実際に使っているサブディレクトリ名（Bedrock なら /wp/）を挿入して再度アクセスすれば、多くの場合そのまま画面が開く。修正後の正しいパスは /wp/wp-admin/admin.php?page=... の形になる。
この操作はあくまで一時しのぎで、管理画面内の他のリンクも同じ問題を抱えている可能性がある。ページを移動するたびに手動で URL を直すのは現実的ではないため、根本的な解決にはプラグインの修正が必要になる。
プラグインのアップデートで完全に解決する
この種の不具合は、プラグインが WordPress 標準の関数（admin_url() など）を使わずにパスを決め打ちで書いてしまったために起こる。開発者がこの問題に気づけば、次のバージョンで修正されるのが一般的だ。実際、今回の事例の Milo Subscriptions でも、内部の管理画面リンクを WordPress が返す正しい URL から組み立て直す修正がバージョン 1.8.7 で適用された。まずは管理画面の「プラグイン」から当該プラグインの更新がないか確認し、最新版が提供されていれば即座に適用する。
更新がすぐに提供されていない場合でも、問題が発見された後のバージョンでは修正されていることが多い。プラグインの公式ページの「Changelog（変更履歴）」に “Fix admin URLs on subdirectory installs” のような記載があれば、それを当てるだけで解決する。
恒久的な修正のためにプラグイン開発者へ報告する
まだ修正されていないプラグインで同じ症状が出るなら、サポートフォーラムや公式リポジトリの Issues で「サブディレクトリ構成だと管理画面のリンクが404になる」と具体的に伝えるのが最も建設的だ。報告の際は、自分の WordPress が /wp/ や /cms/ などのサブディレクトリにインストールされていること、問題が起こる画面の URL、使っているテーマや主要プラグインのバージョンを添えると、開発者が原因を特定しやすい。サブディレクトリ環境に限ったバグはテストで見落とされやすいため、利用者からの報告がなければ長期間放置される可能性がある。
よくある質問
サブディレクトリへ WordPress をインストールするのは特別なのか
標準的な構成であっても、WordPress 本体を /wp/ や /cms/ といったサブディレクトリに置くことは公式にも認められた設定だ。Bedrock や一部のセキュリティ寄りのスタックは、コアファイルをルートから分離する目的でこの構造を採用している。ただし、プラグインやテーマの開発者が標準構成だけを想定してテストしていると、今回のようなパス解決のミスが残りやすい。
サブディレクトリ環境だと他にどんな不具合が起きるのか
管理画面のリンク切れ以外にも、REST API や Ajax のエンドポイントが見つからずに動作が止まるケースがある。たとえば画像の一括処理やリアルタイム検索が動かなくなることがある。いずれも WordPress が提供する URL 取得関数（rest_url() や admin_url()）を使わずにパスを直書きしていることが原因だ。
自分でプラグインのコードを修正してもよいのか
管理画面のリンクをすぐに直す必要があるなら、プラグインの該当ファイルを子テーマやカスタムプラグインで上書きできれば対処できる。ただし、元のプラグインが更新されると上書きが無効になるため、恒久的な対応としては推奨しない。一時しのぎと割り切ったうえで、開発者へのフィードバックとセットで行うのが現実的だ。
Bedrock 以外の構成でも同じ問題は起こるのか
WordPress を /wp/ 以外の任意のディレクトリ（/cms/ /admin/ など）に配置している場合、まったく同じ仕組みで発生する。また、マルチサイトのサブディレクトリ構成でも、特定の管理画面リンクが正しく生成されないことがある。原因の構造は共通しているため、対処の考え方は変わらない。
この記事のポイント
- サブディレクトリ環境ではプラグインの管理画面リンクが404になることがある
- 原因はプラグインがパスをルート相対でハードコードしていること
- 一時的には URL へ正しいサブディレクトリを手動で挿入すればアクセスできる
- プラグインの最新版を確認し、修正があればすぐに更新する
- 修正がまだなら開発者へ具体的な環境情報を添えて報告する
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている