Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【ITニュース解説】Why your custom post type URLs 404 (and how to never re-save permalinks again)

2026年10月15日に「Dev.to」が公開したITニュース「Why your custom post type URLs 404 (and how to never re-save permalinks again)」について初心者にもわかりやすく解説しています。

作成日: 更新日:

ITニュース概要

WordPressでカスタム投稿タイプを登録してもURLが404になるのは、URLルールがキャッシュされ、コード変更時に自動更新されないため。手動でパーマリンク設定を保存し直す手間を、ルール変更時のみキャッシュを更新することで自動化し、パフォーマンス問題も回避する。

ITニュース解説

WordPressでWebサイトを構築する際、通常の「投稿」や「固定ページ」とは異なる、独自の種類のコンテンツを追加したい場合がある。例えば、「レシピ」や「商品」など、それぞれに固有の情報を持ちたいコンテンツだ。これをWordPressでは「カスタム投稿タイプ」と呼ぶ。このカスタム投稿タイプを新しく定義し、その種類の記事を投稿して公開したとする。しかし、その記事のURLにアクセスしてみると、「ページが見つかりません」という「404エラー」が表示されることが頻繁にある。

この問題に直面した多くのWordPressユーザーや開発者は、ある独特の解決策を知っている。それは、WordPressの管理画面にある「設定」→「パーマリンク」に移動し、何も変更せずに「変更を保存」ボタンをクリックするというものだ。すると不思議なことに、それまで404エラーだったURLが正しく表示されるようになる。これは一種の「おまじない」のように感じられ、多くの人がその理由を知らずにこの手順を踏んでいるのが現状だ。

この現象の根本的な原因は、WordPressがWebサイトのURL構造、つまりパーマリンクをどのように管理しているかにある。開発者がregister_post_type()のような関数をコードで呼び出し、新しいカスタム投稿タイプを定義する際、WordPressはすぐにそのカスタム投稿タイプに対応するURLルールを Webサイトに適用するわけではない。これらの関数は、あくまで「このようなURL構造にしたい」という「記述」をWordPressの内部情報、具体的には$wp_rewriteというグローバル変数に記録するだけなのだ。

WordPressが実際に、ユーザーがアクセスしたURLをどのページに結びつけるかを判断するために使うのは、正規表現とそれに対応するデータベースクエリのペアが大量に並んだ配列である。例えば、「レシピ」というカスタム投稿タイプに「私のアップルパイ」という記事があれば、「/recipes/my-apple-pie/」というURLが「index.php?recipe=my-apple-pie」というデータベースクエリに対応するといった具体的なルールだ。この複雑なルール配列をWebサイトへのリクエストがあるたびにゼロから構築するのは非常に処理コストがかかるため、WordPressはこのルール配列を一度構築すると、それをデータベースに「rewrite_rules」というオプションとしてキャッシュ(一時保存)しておく。Webサイトへのリクエストがあるたびに、WordPressはこのキャッシュされたルールを読み込んでURLの解決に利用するのだ。

問題は、コード内で新しいカスタム投稿タイプを登録したり、既存のスラッグ(URLの一部)を変更したりしても、このデータベースにキャッシュされたrewrite_rulesが自動的に更新されない点にある。キャッシュが更新されないままでは、WordPressはまだ「recipes」という新しい投稿タイプの存在を知らない古いルールに基づいてURLの解決を試みるため、結果として「/recipes/my-apple-pie/」のような新しいURLにアクセスしても、対応するルールが見つからずに404エラーとなってしまうのだ。このキャッシュを更新し、新しいルールをデータベースに書き換えるには、flush_rewrite_rules()という関数を呼び出す必要がある。「パーマリンク設定の保存」ボタンをクリックすることは、このflush_rewrite_rules()関数を呼び出す数少ないトリガーの一つなのである。

この原因を知ると、「それなら毎回initアクション(WordPressが初期化される最初の段階)でflush_rewrite_rules()を呼び出せばいい」と考える人もいるかもしれない。実際にそのようなコードを記述すると、一時的に問題は解決する。しかし、これは非常に望ましくない解決策だ。flush_rewrite_rules()は、WebサイトのすべてのURLルールをゼロから再構築し、それをデータベースに書き込むという非常に重い処理を実行する。これをWebサイトへのすべてのリクエストごとに実行してしまうと、サーバーに過剰な負荷がかかり、Webサイト全体のパフォーマンスが著しく低下してしまう。この関数の公式ドキュメントでも、この関数は「プラグインのアクティベーションフック」(プラグインが有効化された時)のような、ごくまれにしか実行されない場所で使うべきだと明確に警告している。

しかし、プラグインのアクティベーションフックで一度だけflush_rewrite_rules()を実行する方法も、すべてのケースをカバーできるわけではない。この方法では、そのプラグインが有効化された時にしかルールが更新されないため、テーマの切り替え、新しいコードがサーバーにデプロイされた時(スラッグの変更などを含む)、あるいは別のプラグインが新しいルートを追加した場合などには対応できない。これらの状況では、やはり「パーマリンク設定を再保存する」という手動のおまじないが必要となってしまうのが実情だ。

そこで考えられたのが、「実際にルート(URLルールを記述する情報)に変更があった場合にのみ、ルールを再構築する」という解決策である。この方法では、まずwp_loadedアクションという、WordPressのすべてのプラグインやテーマがURLルールを登録し終えた後に実行されるタイミングを利用する。このタイミングで、WordPressのグローバル変数$wp_rewriteに格納されている現在のURLルールに関する情報(カスタム投稿タイプやタクソノミーの構造、追加されたリライトルール、エンドポイントなど)をすべて集め、その情報から「指紋」と呼べるハッシュ値(データのユニークな識別子)を生成する。

次に、この新しく生成された指紋を、前回ルールを再構築した時にデータベースに保存しておいた指紋と比較する。もし両方の指紋が同じであれば、URLルールに関する情報には何も変更がないと判断し、何もせずに処理を終える。指紋が異なる場合のみ、ルールが変更されたと判断し、flush_rewrite_rules( false )という形でflush_rewrite_rules()関数を呼び出す。ここで引数にfalseを渡すのは、「ソフトフラッシュ」と呼ばれる方法で、データベース内のルールのみを再構築し、Webサーバーの設定ファイルである.htaccessは変更しない。WordPressの標準的な.htaccessはほとんどの場合、汎用的なURLキャッチオールとして機能するため、ほとんどの環境で.htaccessの再生成は不要なのである。

この仕組みにより、URLルールに変更がない通常のWebサイトアクセスでは、データベースオプションの読み込みとハッシュ値の比較という非常に軽い処理だけで済み、パフォーマンスへの影響はほとんどない。そして、コードの変更によってURLルールに実際に変更があった場合にのみ、必要な再構築処理が実行されるため、無駄な負荷を避けることができる。

ただし、この「変更があった時だけ再構築」の仕組みにも、一つ注意すべきエッジケースが存在した。一部のプラグインは、管理画面でのみカスタム投稿タイプを登録するように設計されている場合がある。このようなWebサイトでは、フロントエンド(一般ユーザーが見る画面)からのアクセスと、管理画面からのアクセスとで、$wp_rewriteオブジェクトの内容が異なってしまう。これにより、アクセスするたびに指紋が頻繁に変化し、あたかもルールが変更されたかのように誤って判断され、結局は毎回ルールが再構築されてしまうという、「initフックで毎回フラッシュ」と同じパフォーマンス問題が発生する可能性があったのだ。

この問題への対策として、ルール再構築の回数に上限を設ける方法が採用された。具体的には、過去10分間の間にルールが再構築された回数をデータベースに記録し、その回数が5回を超えた場合は、それ以上ルールを再構築しないように制限する。これにより、たとえ指紋が頻繁にフリップフロップするようなサイトであっても、1時間あたり最大30回までしかルール再構築が行われず、サーバーへの過剰な負荷を防ぐことができる。もちろん、実際にルート情報が変更された場合は、次回のアクセスでルールが正しく適用されるため、Webサイトの機能が損なわれることはない。

新しいURLへの対応と同時に、古いURLの扱いも重要な問題となる。例えば、カスタム投稿タイプ「recipes」のスラッグを「recipe」に変更した場合、以前の「/recipes/pie/」のようなリンクはどうなるだろうか。WordPressは、デフォルトで404エラーハンドラの一部としてredirect_guess_404_permalink()という機能を持っている。これは、404になったURLから投稿のスラッグを推測し、新しいスラッグに301リダイレクト(恒久的な転送)を試みる機能だ。そのため、多くの場合は古い投稿URLも機能し続けることが多い。しかし、この機能は投稿にしか適用されず、タクソノミー(カテゴリやタグのような分類)のスラッグを変更した場合には機能しない。例えば、タクソノミー「genre」を「genres」に変更すると、以前の「/genre/jazz/」のようなリンクは永遠に404エラーとなってしまう。また、投稿のリダイレクトも推測に基づくため、あいまいなマッチングとなり、例えば「/recipe/pi/」のようなタイプミスでも「pie」にリダイレクトされることがある。このような、より高度で正確な古いURLのリダイレクトを管理したい場合には、Permapilot Proのような専門の有料アドオンが提供されており、タクソノミーの変更にも対応し、正確な301リダイレクトを提供している。

このような複雑なURLルールやキャッシュに関するバグは、実際のWebサイト環境で様々なプラグインやキャッシュ機構が絡み合った場合に発生しやすいため、シミュレーションだけでは発見が難しい。そのため、このソリューションはDockerコンテナで構築された実際のWordPress環境で、コード変更を模擬しながらHTTPリクエストを送信し、テストを行うことでその堅牢性が検証されている。

この「おまじない」問題を解決するPermapilotというプラグインは、WordPress.orgで無料で公開されている。特別な設定は不要で、有効化するだけで上記の仕組みが導入され、パーマリンクの設定を再保存する手間なく、カスタム投稿タイプやタクソノミーのURLが正しく機能するようになる。

関連コンテンツ

関連IT用語