Web サイトは普通に表示されているのに、WP-CLI を打つと fatal error で落ちる。第2章は、その一行から始めます。原因はほぼ決まっていて、CLI 用の PHP が古いまま、というやつです。第1章で WP-CLI が動く状態になった前提で、ここからは現場でつまずく具体的なポイントと、そのまま使える対処をまとめていきます。
検証環境：WordPress 6.9.4 / PHP 8.3.2 / WP-CLI 2.12.0 / Xserver スタンダードプラン / ConoHa WING / Docker（wordpress:6.9.4-php8.3.2）/ macOS Tahoe 26.4 / GitHub Actions ubuntu-latest
この章は、コピペしてそのまま使えるテンプレートを多めにしています。サーバーごとの注意点、移行・保守の定型スクリプト、マルチサイト、CI/CD、そして search-replace を安全に使う型まで。実際の運用で手が止まりやすいところを順に潰していきます。
サーバーが違えば、つまずく場所も違う
WP-CLI が動かない、エラーになる、という相談の大半は、3つに集約されます。CLI の PHP が Web と違う、sudo が使えず置き場所に困る、WordPress のパス指定を間違えている。どれもサーバー環境ごとに事情が変わるので、代表的な4つを個別に見ていきます。
Xserver では、CLI用PHPのバージョンにまず疑いをかける
日本でいちばん利用者の多いレンタルサーバーです。WP-CLI 自体は問題なく動きますが、ハマりどころが3つあります。
| 問題 | 原因 | 対処 |
|---|---|---|
| sudoが使えない | 共用サーバーで管理者権限がない | ~/bin にWP-CLIを置いてPATHを通す（第1章参照） |
| CLIのPHPが古い | Web用とCLI用でPHPが別バイナリ | php -v で確認し、必要なら別パスのPHPを指定 |
| WordPressのパスがわからない | マルチドメインで public_html/サブディレクトリ/ に設置 | --path で正確なパスを毎回指定 |
インストールは第1章の sudo なし手順と同じで、~/bin に置いて PATH を通します。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 | # ~/bin ディレクトリを作成 mkdir -p ~/bin && cd ~/bin # WP-CLIをダウンロード・設置 curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar chmod +x wp-cli.phar && mv wp-cli.phar wp # PATHに追加（bashの場合。zshなら ~/.zshrc） echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc source ~/.bashrc # 動作確認 wp --info |
そして冒頭の症状です。php -v と wp --info の両方で、CLI が使っている PHP のバージョンを見比べておきます。
| 1 2 3 4 5 | # CLIのPHPバージョンを確認 php -v # WP-CLIが使っているPHP情報 wp --info |
ConoHa WING は、~/.ssh/config を整えると一気に楽になる
ConoHa WING でも WP-CLI は問題なく動きます。先にコントロールパネルで SSH を有効化して、公開鍵を登録しておきます。
接続そのものは、ローカルの ~/.ssh/config にホストを書いておくと毎回のタイプが減ります。
| 1 2 3 4 5 6 | # ConoHa本番サーバー Host conoha-prod HostName xxx.xxx.xxx.xxx User your-user Port 22 IdentityFile ~/.ssh/id_rsa |
| 1 2 | # 設定後はこれだけでSSH接続 ssh conoha-prod |
複数サーバーを持っているなら、それぞれに Host 名を付けておくと、切り替えがスムーズになります。地味ですが、サーバーを取り違えて別のサイトを触る事故を減らす効果もあります。
さくらは、プランによって前提が変わる
さくらのレンタルサーバは、プランや契約時期によって SSH の可否や使えるコマンドに差があります。WP-CLI が入っていないことも多いので、Phar で自前インストールになります。
| 1 2 3 4 | # wpコマンドが存在するか確認 which wp || echo "wp not found" # 存在しない場合は第1章の「sudo無し」手順でインストール |
容量やプロセスに制限のあるプランでは、大きな DB の export / import が途中で切れることがあります。大規模な作業は時間帯をずらすか、分割して流すと安全です。
Docker は、実行パターンを3つ知っておくと迷わない
ローカルの Docker 環境で WP-CLI を動かす方法は、大きく3つあります。
| パターン | 方法 | 特徴 |
|---|---|---|
| A: コンテナ内で実行 | docker compose exec wordpress wp ... | 最もシンプル。ただしWP-CLIがコンテナ内に必要 |
| B: wordpress:cli イメージ | WP-CLI専用コンテナをボリューム共有で起動 | WP-CLIの追加インストール不要 |
| C: ホスト側から –ssh | wp --ssh=docker-compose:wordpress:/var/www/html ... | CI/CDや複数環境の統一管理向け。設定はやや複雑 |
| 1 2 | # パターンA：コンテナ内でwp plugin listを実行 docker compose exec wordpress wp plugin list |
| 1 2 3 4 5 | # パターンB：WP-CLI専用コンテナでコマンド実行 docker run -it --rm \ --volumes-from some-wordpress \ --network container:some-wordpress \ wordpress:cli plugin list |
まずはパターンAかBで始めて、CI/CD 連携が必要になったらパターンCを検討する、くらいの順番でいいと思います。
移行・保守はテンプレート化しておくと事故が減る
運用の定型作業を、4つのテンプレートにまとめました。安全なアップデート、ドメイン移行、障害復旧、定期保守です。どれも「dry-run → backup → maintenance → 本実行」の流れを組み込んであり、環境変数を書き換えればそのまま動きます。
テンプレ1：安全なアップデート（基本形）
本体・プラグイン・テーマを一括更新する基本形です。メンテナンスモードのON/OFF、バックアップ、キャッシュクリアまで入れています。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | #!/usr/bin/env bash set -euo pipefail WP_PATH="${WP_PATH:-/path/to/wordpress}" WP="wp --path=${WP_PATH}" STAMP="$(date +%F-%H%M)" BACKUP_DIR="${BACKUP_DIR:-$PWD/_backup}" mkdir -p "$BACKUP_DIR" echo "== maintenance on ==" $WP maintenance-mode activate || true echo "== db backup ==" $WP db export "$BACKUP_DIR/db-$STAMP.sql" echo "== core update ==" $WP core update echo "== plugin update ==" $WP plugin update --all echo "== theme update ==" $WP theme update --all echo "== update db ==" $WP core update-db || true echo "== flush cache/rewrite ==" $WP cache flush || true $WP rewrite flush || true echo "== maintenance off ==" $WP maintenance-mode deactivate || true echo "DONE" |
set -euo pipefail は、エラーが出たらスクリプトを止める安全装置です。|| true を付けた行は「失敗しても止めない」例外で、メンテナンスモードやキャッシュクリアのように、失敗しても致命的でない処理に使っています。
テンプレ2：ドメイン移行（URL置換つき）
旧ドメインから新ドメインへ移すテンプレートです。必ず dry-run を挟んでから本実行します。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | #!/usr/bin/env bash set -euo pipefail WP_PATH="${WP_PATH:-/path/to/wordpress}" WP="wp --path=${WP_PATH}" OLD="${1:-https://old.example.com}" NEW="${2:-https://new.example.com}" STAMP="$(date +%F-%H%M)" BACKUP_DIR="${BACKUP_DIR:-$PWD/_backup}" mkdir -p "$BACKUP_DIR" echo "== db backup ==" $WP db export "$BACKUP_DIR/db-before-migrate-$STAMP.sql" echo "== dry-run search-replace ==" $WP search-replace "$OLD" "$NEW" --skip-columns=guid --dry-run echo read -p "Apply for real? type 'yes' to continue: " yn if [[ "$yn" != "yes" ]]; then echo "Canceled." exit 0 fi echo "== apply search-replace ==" $WP search-replace "$OLD" "$NEW" --skip-columns=guid echo "== flush cache/rewrite ==" $WP cache flush || true $WP rewrite flush || true echo "DONE" |
--dry-run は、実際には変更せず、何が変わるかだけを見せるリハーサルです。--skip-columns=guid は、RSS の識別子である guid カラムを除外します。read -p で「yes」の入力を求めることで、うっかり本実行してしまう事故を止めています。
テンプレ3：障害復旧（ログイン不可・真っ白画面）
管理画面に入れない、サイトが真っ白、という緊急時用です。原因調査は後回しにして、とにかく復旧を最優先にします。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | #!/usr/bin/env bash set -euo pipefail WP_PATH="${WP_PATH:-/path/to/wordpress}" WP="wp --path=${WP_PATH}" echo "== minimal boot (skip plugins/themes) ==" $WP --skip-plugins --skip-themes core version echo "== deactivate all plugins ==" $WP plugin deactivate --all echo "== switch theme to default ==" $WP theme activate twentytwentyfour || true echo "== flush cache ==" $WP cache flush || true echo "DONE (try login)" |
復旧したら、プラグインを1つずつ有効化していきます。有効化した瞬間にサイトが止まったものが、原因のプラグインです。全部止めて1つずつ戻す、というのは WordPress 障害対応の王道です。
テンプレ4：定期保守（cron向け）
cron で定期実行するテンプレートです。更新チェックと Cron ジョブの実行だけを行い、自動更新はしません。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | #!/usr/bin/env bash set -euo pipefail WP_PATH="${WP_PATH:-/path/to/wordpress}" WP="wp --path=${WP_PATH} --quiet" LOG_DIR="${LOG_DIR:-$PWD/_logs}" mkdir -p "$LOG_DIR" LOG_FILE="$LOG_DIR/maintenance-$(date +%F).log" { echo "== $(date) ==" $WP plugin list --update=available || true $WP theme list --update=available || true $WP cron event run --due-now || true $WP cache flush || true echo } >> "$LOG_FILE" 2>&1 |
マルチサイトでは、–url を体に染み込ませる
マルチサイトで WP-CLI を使うときは、--url で操作対象のサイトを毎回はっきりさせるのが鉄則です。--network はネットワーク全体への操作に使い、全サイトへの一括処理はシェルのループで回します。
まずはサイト一覧の確認です。作業前に必ずこれを見て、対象を取り違えないようにします。
| 1 2 3 4 5 | # サイト一覧（ID・ドメイン・パス） wp site list # URLだけを一覧表示 wp site list --field=url |
特定サイトへの操作は --url で指定します。ネットワーク全体への操作は --network、全サイトへの一括処理は wp site list の出力をループで回す、という使い分けです。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 | # 特定サイトのオプション値を取得 wp --url=https://sub.example.com option get blogname # 特定サイトのプラグインを有効化 wp --url=https://sub.example.com plugin activate my-plugin # プラグインをネットワーク有効化 wp plugin activate my-plugin --network # 全サイトのサイト名を取得 wp site list --field=url | while read -r u; do echo "== $u ==" wp --url="$u" option get blogname done |
一括操作は便利ですが、ミスの影響も大きいです。最初は必ず option get で現在値を見てから option update を実行してください。
スーパー管理者の管理も、コマンドで完結します。権限が強いので、付与は必要最小限のユーザーだけにとどめます。
| 1 2 3 4 5 6 7 8 | # スーパー管理者一覧を表示 wp super-admin list # ユーザーをスーパー管理者に追加 wp super-admin add adminuser # スーパー管理者から削除 wp super-admin remove adminuser |
CI/CDに載せると「毎回同じ手順」が確実になる
GitHub Actions で WordPress 環境を組んで WP-CLI を走らせる、最小のテンプレートを置いておきます。PR のたびに WordPress を自動で立ち上げてプラグインの動作確認まで通せるので、マージ前に問題に気づけるようになります。
CI に載せて得られるものは、大きく3つです。人手だと抜けやすい手順が、設定どおり毎回そのまま実行されること。PR ごとに WordPress 環境を作って基本チェックを自動で回せること。そして、まず検証の自動化から始めて、慣れたらステージングへのデプロイまで段階的に広げられること。
MySQL は service コンテナで起動し、WP-CLI は Phar を落として使います。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | name: wp-cli-smoke on: push: pull_request: jobs: wp-cli: runs-on: ubuntu-latest services: mysql: image: mysql:8 env: MYSQL_ROOT_PASSWORD: root MYSQL_DATABASE: wp ports: - 3306:3306 options: >- --health-cmd="mysqladmin ping -h 127.0.0.1 -proot" --health-interval=10s --health-timeout=5s --health-retries=10 steps: - uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: "8.2" extensions: mbstring, mysqli tools: composer - name: Download WP-CLI run: | curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar php wp-cli.phar --info - name: Setup WordPress run: | mkdir wp && cd wp php ../wp-cli.phar core download --locale=ja php ../wp-cli.phar config create \ --dbname=wp --dbuser=root --dbpass=root \ --dbhost=127.0.0.1 --skip-check php ../wp-cli.phar db create php ../wp-cli.phar core install \ --url=http://example.test \ --title="CI Test" \ --admin_user=admin \ --admin_password=admin \ --admin_email=admin@example.com - name: Smoke check run: | cd wp php ../wp-cli.phar plugin list php ../wp-cli.phar option get home |
search-replace は、雑に使うと取り返しがつかない
wp search-replace はサイト移行でいちばん活躍するコマンドですが、乱暴に使うと戻せません。守るのは5ステップです。backup → dry-run → 確認 → 本実行 → キャッシュクリア。あわせて guid カラムはスキップし、必ずステージングで先に試します。
| # | 原則 | 操作 |
|---|---|---|
| 1 | 必ずバックアップ | wp db export before.sql |
| 2 | 必ずdry-runを先に | --dry-run で変更内容を確認 |
| 3 | guidカラムをスキップ | --skip-columns=guid を付ける |
| 4 | 最初はURLだけ置換 | 正規表現や複数パターンは慣れてから |
| 5 | ステージングで先にテスト | 本番で一発勝負は避ける |
| 1 2 3 4 5 6 7 8 9 10 | # 1. バックアップを取得 wp db export before.sql # 2. dry-runで確認 wp search-replace 'http://old.example' 'https://new.example' \ --skip-columns=guid --dry-run # 3. 結果を確認してから本実行 wp search-replace 'http://old.example' 'https://new.example' \ --skip-columns=guid |
dry-run の結果には、対象テーブル名と置換される行数が出ます。行数が異常に多いときや、想定外のテーブルが混じっているときは、一度手を止めて確認してください。
置換したのにURLが変わらないときに見る場所
search-replace を流したのに URL が変わっていない、というときは、次を順に確認します。まず wp option get siteurl と wp option get home で現在値を見て、必要なら wp option update で直接直します。次に wp-config.php に WP_HOME や WP_SITEURL が定義されていないか。定義があると DB の値より優先されます。Cloudflare などの CDN を使っているなら CDN 側の設定も要ります。最後に、単にキャッシュが残っているだけのこともあるので、wp cache flush を実行し、ブラウザのキャッシュも消してから再確認します。
本番作業前に通すチェックリスト
本番で WP-CLI を使う前に確認したい項目を、事前チェックと安全装置の2つに分けました。作業記録としてコピーして残しておくと、多くの事故を未然に防げます。
事前チェックはこの5つです。
| 1 2 3 4 5 | [ ] wp --info でWP-CLIとPHPが正常動作しているか [ ] wp core version が通り、WordPressが認識されているか [ ] wp plugin list が通り、プラグイン読み込みに問題がないか [ ] 実行場所のパスが正しいか（--path or 正しいディレクトリ） [ ] ファイルの所有者・権限が適切か（ls -la で確認） |
作業の安全装置は、この5つです。
| 1 2 3 4 5 | [ ] DBバックアップを wp db export で取得した [ ] search-replaceを行う場合、--dry-run で結果を確認した [ ] メンテナンスモードのON/OFFコマンドを準備した [ ] 失敗時の戻し手順（db import）を把握している [ ] 作業内容と結果を記録するログの準備ができている |
困ったときは、まず公式ドキュメントを見る癖をつけておくと早いです。WP-CLI まわりの情報は、公式がいちばん正確で網羅的です。
WP-CLI 公式
GitHub Actions
ここから先に伸ばすなら
2章分の知識を実践に変えるには、順番があります。まず、この記事のテンプレートをベースに、環境変数やパスを自分仕様に書き換えたスクリプトを1つ作る。更新用でも移行用でもかまいません。次に、それをステージングで何度も流して、エラーが出る条件と対処を体で覚える。本番で初めてのコマンドを打つのは避けたいところです。マルチサイトを触るなら --url を付ける癖を先につける。そして CI で WordPress 環境を作って smoke test を回せるようにする。最初は簡単なチェックだけで十分です。
WP-CLI は、使えるようになると運用の景色が変わる道具です。テンプレートを持って、安全な手順を習慣にすれば、速さと安全は両立します。第1章とあわせて、日常の道具にしてください。
コメント