wp-wpcli-and-ops

WP-CLI 與運維操作

使用時機

當任務涉及透過 WP-CLI 進行 WordPress 運維操作時使用此技能，包括：

• wp search-replace（網址變更、網域遷移、通訊協定切換）
• 資料庫匯出/匯入、重置與檢查（wp db *）
• 外掛/主題安裝、啟用、更新、語言包
• 排程事件列表與執行
• 快取/重寫規則清除
• 多站點操作（wp site *、--url、--network）
• 建立可重複使用的腳本（wp-cli.yml、Shell 腳本、CI 任務）

所需輸入

• WP-CLI 將在何處執行（本機開發、測試站、正式站）以及是否安全執行。
• 如何指定正確的網站根目錄：
  • --path=<wordpress-root> 以及（多站點）--url=<site-url>
• 是否為多站點，以及指令是否應在整個網路中執行。
• 任何限制條件（無停機時間、不寫入資料庫、維護時段）。

操作流程

0) 安全護欄：確認環境與影響範圍

WP-CLI 指令可能具有破壞性。在執行任何寫入操作前：

1. 確認環境（開發/測試/正式）。
2. 確認目標（路徑/網址），避免影響錯誤的網站。
3. 執行風險操作前先備份。

請閱讀：

• references/safety.md

1) 檢查 WP-CLI 與網站目標（確定性）

執行檢查工具：

• node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]

如果 WP-CLI 不可用，則透過專案文件中的工具（Composer、容器或系統套件）安裝，或詢問預期的執行環境。

2) 選擇正確的工作流程

A) 安全的網址/網域遷移（search-replace）

遵循安全順序：

1. wp db export（備份）
2. wp search-replace --dry-run（檢視影響）
3. 使用適當的旗標執行實際取代
4. 必要時清除快取/重寫規則

請閱讀：

• references/search-replace.md

B) 外掛/主題操作

使用 wp plugin * / wp theme *，並先確認操作對象是正確的網站（以及網路）。

請閱讀：

• references/packages-and-updates.md

C) 排程與佇列

檢查排程狀態，並針對除錯執行個別事件，而非「盲目執行所有事件」。

請閱讀：

• references/cron-and-cache.md

D) 多站點操作

多站點變更可能影響許多網站。務必決定操作範圍：

• 單一網站（--url=），或
• 整個網路（--network / 遍歷網站）

請閱讀：

• references/multisite.md

3) 自動化模式（腳本 + wp-cli.yml）

對於可重複的運維操作，建議使用：

• wp-cli.yml 設定預設值（路徑/網址、PHP 記憶體限制）
• Shell 腳本，記錄指令並在錯誤時停止
• CI 任務，預設執行唯讀檢查

請閱讀：

• references/automation.md

驗證

• 在可能影響目標或設定的變更後，重新執行 wpcli_inspect。
• 確認預期的副作用：
  • 正確的網址已更新
  • 外掛/主題處於預期狀態
  • 排程/快取已視需要清除
• 如果有健康檢查端點或冒煙測試套件，請在運維變更後執行。

失敗模式 / 除錯

• 「錯誤：這似乎不是 WordPress 安裝。」
  • --path 錯誤、容器錯誤或缺少 wp-config.php
• 多站點指令影響錯誤的網站
  • 缺少 --url 或網址錯誤
• Search-replace 導致意外的序列化問題
  • 錯誤的旗標或不安全地變更序列化資料

請參閱：

• references/debugging.md

升級處理

• 如果無法確認環境安全性，請勿執行寫入操作。
• 如果儲存庫使用容器化工具（Docker/wp-env）但您無法存取，請詢問預期的指令執行器或 CI 任務。