WP-CLI rewriteコマンドでパーマリンクとリライトルールを管理する方法

wp rewrite は、WordPress のパーマリンク設定とリライトルール（URL をどの投稿・ページに対応させるかの規則）をコマンドラインから操作するコマンドです。カスタム投稿タイプを追加したら 404 になった、パーマリンク構造を変えたい、どのルールが URL に当たっているか調べたい、といった場面で使います。この記事では flush・list・structure の3つのサブコマンドの使い方と、.htaccess を書き換えるときの設定、フラッシュを実行すべきタイミングを説明します。

リライトルールの仕組みを先に押さえる

WordPress は、/2026/10/hello/ や /event/autumn-fes/ のような URL を受け取ると、登録されたリライトルール（正規表現と、それに対応するクエリの組み合わせ）を上から順に照合し、最初に一致したルールで表示する内容を決めます。

このルールの一覧は、毎回計算し直すと重いため、データベースの wp_options テーブルに rewrite_rules というオプションとして保存されています。投稿タイプやタクソノミーを追加しても、この保存済みの一覧を作り直さない限り新しい URL は認識されず、404 になります。この「作り直し」がフラッシュです。

Apache の場合は、さらに .htaccess の設定によって、存在しないファイルへのリクエストを index.php に渡しています。Nginx では .htaccess は使われず、サーバー設定の try_files などで同じことを行います。

リライトルールを作り直す（wp rewrite flush）

wp rewrite flush

保存されている rewrite_rules を破棄し、現在有効なテーマ・プラグインが登録しているルールから作り直します。管理画面の「設定」→「パーマリンク」で何も変えずに「変更を保存」を押したときと同じ効果です。

実行すべき主なタイミングは次のとおりです。

• カスタム投稿タイプやタクソノミーを追加・変更したあと
• add_rewrite_rule() や add_rewrite_endpoint() を使うコードを追加・変更したあと
• サイトの移転やドメイン変更のあとに、一部の URL だけ 404 になるとき

.htaccess も書き直す（--hard）

--hard を付けると、データベースのルールに加えて .htaccess も書き直します（Apache の場合）。

wp rewrite flush --hard

ただし、WP-CLI はブラウザ経由ではないため、Apache の mod_rewrite が使えるかどうかを判定できません。そのままでは .htaccess は書き換えられず、警告が表示されます。WordPress のルートディレクトリに wp-cli.yml を置き、次のように記述しておくと書き換えられるようになります。

# wp-cli.yml
apache_modules:
  - mod_rewrite

--hard は .htaccess の WordPress 用ブロック（# BEGIN WordPress から # END WordPress まで）を書き換えます。キャッシュ系やセキュリティ系のプラグインが同じファイルに独自の設定を書いていることも多いため、実行前にコピーを取っておいてください。

cp .htaccess .htaccess.bak
wp rewrite flush --hard

Nginx のサーバーでは --hard を付けても意味がありません。通常の wp rewrite flush で十分です。

登録されているルールを確認する（wp rewrite list）

wp rewrite list

match（URL に照合する正規表現）、query（一致したときに WordPress に渡すクエリ）、source（そのルールを生んだ種類）の3列が表示されます。ルールは数百行になることもあるため、絞り込みのオプションを使うのが現実的です。WP-CLI のバージョンによってオプションが追加されていることがあるため、手元の環境の wp help rewrite list もあわせて確認してください（2026年10月現在）。

# 特定の URL に一致するルールだけを表示
wp rewrite list --match=/event/autumn-fes/

# 種類で絞り込む（例: 投稿タイプ event のルール）
wp rewrite list --source=event

# 表計算ソフトで見たいときは CSV で出力
wp rewrite list --format=csv > rewrite-rules.csv

--match は 404 の原因調査で特に役立ちます。期待した投稿タイプのルールが表示されなければ、そもそもルールが登録されていない（投稿タイプのコードが読み込まれていない、rewrite の設定が false になっているなど）か、フラッシュがまだという状態です。逆に、別のルールが先に一致している場合は、スラッグの衝突が原因です。固定ページとカスタム投稿タイプのスラッグが同じ、といったケースがよくあります。

--source に指定できる値は、post・page・category・post_tag といった種類や、カスタム投稿タイプ・タクソノミーの名前です。どんな値があるかは、絞り込まずに一覧を出したときの source 列で確認できます。

パーマリンク構造を変更する（wp rewrite structure）

wp rewrite structure '/%postname%/'

パーマリンク構造（permalink_structure オプション）を書き換え、続けてルールを作り直します。カテゴリーとタグのベース（URL 中の category や tag の部分）も同時に変えられます。

wp rewrite structure '/%category%/%postname%/' --category-base=topics --tag-base=keyword

% を含むため、bash や zsh ではシングルクォートで囲みます。Windows のコマンドプロンプトでは % が環境変数の記号として扱われる場合があるため、意図した値になっているか、実行後に確認してください。

wp option get permalink_structure

公開中のサイトで構造を変えるときの注意

パーマリンク構造を変えると、既存の投稿の URL が変わります。検索エンジンからの流入や外部サイトからのリンク、SNS で共有された URL が 404 になるおそれがあるため、公開中のサイトでの変更は慎重に判断してください。

1. 実行前に wp db export でデータベースを書き出す
2. ステージング環境で変更し、旧 URL から新 URL への転送がどうなるかを確かめる
3. 必要に応じて 301 リダイレクトの設定を用意してから本番で変更する

WordPress は投稿のスラッグが変わった場合の転送はある程度自動で行いますが、構造そのものを変えた場合の旧 URL がどこまで転送されるかは構造の組み合わせによります。主要な記事について、旧 URL を実際に開いて確認するのが手堅い方法です。

フラッシュはページ表示のたびに実行しない

プラグインやテーマのコードで init フックの中に flush_rewrite_rules() を書いてしまう例を見かけますが、これはページが表示されるたびにルールの作り直しとデータベースへの書き込みが走るため、サイトが重くなる原因になります。

フラッシュはプラグインの有効化・無効化のときに1回だけ行うのが定石です。

<?php
// プラグイン本体ファイル
function my_tools_register_post_types() {
	register_post_type(
		'event',
		array(
			'label'        => 'イベント',
			'public'       => true,
			'has_archive'  => true,
			'show_in_rest' => true,
		)
	);
}
add_action( 'init', 'my_tools_register_post_types' );

register_activation_hook( __FILE__, function () {
	my_tools_register_post_types();
	flush_rewrite_rules();
} );

register_deactivation_hook( __FILE__, 'flush_rewrite_rules' );

有効化フックの中で先に投稿タイプを登録してからフラッシュしている点がポイントです。有効化の処理が走るリクエストでは、このプラグインの init 処理はまだ一度も実行されていないため、ここで登録しておかないと新しいルールが含まれません。テーマの functions.php に投稿タイプを書いている場合は有効化フックが使えないため、コードを変えたあとに wp rewrite flush を手で実行します。

まとめ

• リライトルールは rewrite_rules オプションに保存されており、投稿タイプなどを追加したら wp rewrite flush で作り直す
• --hard で .htaccess も書き直すには、wp-cli.yml に apache_modules で mod_rewrite を指定する。実行前に .htaccess のコピーを取る
• 404 の調査は wp rewrite list --match=<URL> で、どのルールが一致しているかを見る
• wp rewrite structure は公開中のサイトの URL をまとめて変える操作。wp db export とステージングでの確認を経てから行う
• flush_rewrite_rules() は有効化・無効化のときだけ呼び、毎回のページ表示では実行しない

• WordPressのパーマリンク設定の基本
• WordPressの.htaccessエラーを直す方法