WP-CLI | wp rewrite flush –hard 徹底解説：意味・使いどころ・実行レシピ（単独／マルチサイト／SSH）

WordPress のパーマリンクを即時に反映させる最短コマンドが wp rewrite flush。その中でも .htaccess まで再生成するのが --hard オプションです。本記事では意味から実運用のシェルスクリプト、マルチサイト一括、SSH/パスワード認証での遠隔実行、Nginx 環境での注意点までまとめます。

要点まとめ

  • wp rewrite flush は “rewrite ルール（DB）の再生成”。
  • --hard を付けると .htaccess も再生成（Apache ＋ 書き込み可のとき）。
  • マルチサイトは サイト単位で実行（全体にはループや --url が必要）。
  • Nginx は .htaccess を使わない → --hard は無関係、サーバ設定で対応。
  • 非対話／自動化では set -euo pipefail などで堅牢化し、ログを出す。
  • .htaccess 再生成の警告が出る場合は、wp-cli.yml に apache_modules: [mod_rewrite] を書くと解消できることが多い。

そもそも「flush」とは何をしているのか

  • rewrite ルールの再構築：登録済みの CPT や add_rewrite_rule() の結果をもとに、WordPress が内部ルーティングを更新します。
  • .htaccess の更新（–hard の場合）：Apache 環境で .htaccess が書き込み可なら、# BEGIN WordPress〜# END WordPress のブロックを書き直します。

管理画面の「パーマリンク設定 → 変更を保存」との違い

  • 実質的に flush --hard と同様の処理が走ります（Apache 書き込み可なら .htaccess も更新）。
  • 違いは 自動化できるかどうか。CI/CD や定期保守では WP-CLI が便利です。

コマンド早見表（最短・よく使うオプション）

# ルール再生成（.htaccess も再生成）
wp rewrite flush --hard

# 特定サイト（マルチサイト）だけ
wp --url='https://example.com' rewrite flush --hard

# WordPress ルートが異なる場合
wp rewrite flush --hard --path=/var/www/html

# 現在のパーマリンク構造確認
wp option get permalink_structure

# 構造変更して即反映（例：/%postname%/）
wp rewrite structure '/%postname%/' --hard

主なオプション

  • --hard：.htaccess も再生成（Apache + 書き込み可）
  • --path=<path>：WP ルートを指定
  • --url=<url>：対象サイト URL を指定（マルチサイトのサブサイト等）
  • --quiet：出力を抑制

実運用スニペット（単一サイト）

堅牢性重視のテンプレートです。CI や手元の運用スクリプトの雛形にどうぞ。

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

WP="${WP:-wp}"                 # wp コマンド（PATH 非依存なら /usr/local/bin/wp など絶対パス）
WP_PATH="${WP_PATH:-/var/www/html}"  # WordPress ルート
SITE_URL="${SITE_URL:-}"       # 例: https://example.com（未指定なら省略）

echo "[INFO] flush start: $(date '+%F %T')"
if [[ -n "${SITE_URL}" ]]; then
  "$WP" --path="$WP_PATH" --url="$SITE_URL" rewrite flush --hard
else
  "$WP" --path="$WP_PATH" rewrite flush --hard
fi
echo "[INFO] flush done : $(date '+%F %T')"

マルチサイト一括（全サブサイトで flush）

1) URL 取得→順次 flush

# 例：同一サーバ上の WP-CLI を使用
wp site list --field=url \
| xargs -n1 -I % wp --url=% rewrite flush --hard

2) ルートが複数ディレクトリにある場合（順次）

for P in /data/apps/wp_{1..4}/; do
  wp rewrite flush --hard --path="$P"
done

3) 並列で高速化（注意：負荷と .htaccess の競合）

printf "%s\n" /data/apps/wp_{1..4}/ \
| xargs -I{} -P 4 bash -lc 'wp rewrite flush --hard --path="{}"'

SSH 経由（パスワード認証）での遠隔実行

sshpass を使った非対話の例です（セキュリティ上は鍵認証推奨）。

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

HOST="your-host-alias-or-user@host"
PASSWORD="${PASSWORD:?export PASSWORD first}"
REMOTE_WP="$HOME/bin/wp"  # リモートの wp（非対話シェルでも確実に見える位置）
PATHS=(/data/apps/wp_1/ /data/apps/wp_2/ /data/apps/wp_3/ /data/apps/wp_4/)

# 事前チェック
sshpass -p "$PASSWORD" ssh -o StrictHostKeyChecking=no "$HOST" \
  "test -x $REMOTE_WP && $REMOTE_WP --info >/dev/null"

for P in "${PATHS[@]}"; do
  echo "[INFO] flushing: $P"
  sshpass -p "$PASSWORD" ssh -o StrictHostKeyChecking=no "$HOST" \
    "$REMOTE_WP rewrite flush --hard --path='$P'"
done

補足：プロセス一覧にパスワードが見えるため、本番運用は SSH 鍵認証に移行することを推奨します。

.htaccess に書かれない・警告が出るときの対処

Success: Rewrite rules flushed. の直後に
Warning: Regenerating a .htaccess file requires special configuration.
などの警告が出るケースは、.htaccess 書き込みが抑止されている状況が多いです。

直し方（優先度順）

  1. wp-cli.yml で Apache モジュールを宣言
   # WordPress ルート直下（例：/data/apps/wp_X/wp-cli.yml）
   apache_modules:
     - mod_rewrite

その後、wp rewrite flush --hard を再実行。

  1. ファイル権限を確認
    WP ルート（get_home_path()）直下の .htaccess に Web/PHP 実行ユーザーで書き込めるか。
  2. Nginx なら .htaccess は使わない
    警告は無視可。Nginx の server / location 設定でパーマリンクを正しくルーティング。
  3. （応急処置）保存関数を直接呼ぶ
   wp eval 'add_filter("got_mod_rewrite","__return_true"); require_once ABSPATH."wp-admin/includes/misc.php"; save_mod_rewrite_rules(); echo "wrote .htaccess\n";'

よくあるシナリオ別レシピ

A) パーマリンク構造を変えて即反映

wp rewrite structure '/%postname%/' --hard

B) カテゴリ／タグベースも合わせて変更

wp option update category_base 'category'
wp option update tag_base 'tag'
wp rewrite flush --hard

C) CI（デプロイ後に毎回反映）

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'
wp rewrite flush --hard --path=/var/www/html

D) マルチサイトの一部サブサイトだけ

wp --url='https://sub.example.com' rewrite flush --hard --path=/var/www/html

トラブルシューティング・チェックリスト

  • CPT/Rewrite の登録順：register_post_type() や add_rewrite_rule() は init で確実に登録されているか。
  • --path の指し先：wp-config.php が見える WP ルートか。
  • .htaccess 権限：Apache 運用なら書き込み可か（所有者・グループ・SELinux 等）。
  • Nginx 運用：.htaccess を使わない。サーバ設定の try_files 等を確認。
  • マルチサイト：全サブサイトで個別に flush したか（URL ループの実装漏れなし）。
  • wp-cli.yml：apache_modules: [mod_rewrite] を与えているか（非対話・最小 PATH 環境で有効）。

まとめ

  • wp rewrite flush --hard は DB の rewrite ルール再生成＋.htaccess 再生成（環境が合えば）の強力コマンド。
  • 自動化スクリプトに落とし込むと、デプロイ後や CPT 追加・URL 設計変更時の事故を防げます。
  • .htaccess 警告が出る場合は wp-cli.yml＋権限確認で解決することが多く、Nginx なら サーバ側設定で対応しましょう。
スポンサーリンク

コメント

タイトルとURLをコピーしました