Back to Details

wp-wpcli-and-ops

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

WP-CLI and Ops

WP-CLI 与运维操作

When to use

适用场景

Use this skill when the task involves WordPress operational work via WP-CLI, including:
  • wp search-replace
    (URL changes, domain migrations, protocol switch)
  • DB export/import, resets, and inspections (
    wp db *
    )
  • plugin/theme install/activate/update, language packs
  • cron event listing/running
  • cache/rewrite flushing
  • multisite operations (
    wp site *
    , 
    --url
    , 
    --network
    )
  • building repeatable scripts (
    wp-cli.yml
    , shell scripts, CI jobs)
当任务涉及通过WP-CLI执行WordPress运维工作时使用本技能，包括：
  • wp search-replace
    （URL变更、域名迁移、协议切换）
  • 数据库导出/导入、重置与检查（
    wp db *
    ）
  • 插件/主题的安装/激活/更新、语言包管理
  • 定时任务事件的列出/执行
  • 缓存/重写规则刷新
  • 多站点操作（
    wp site *
    、
    --url
    、
    --network
    ）
  • 构建可重复执行的脚本（
    wp-cli.yml
    、Shell脚本、CI任务）

Inputs required

所需输入信息

  • Where WP-CLI will run (local dev, staging, production) and whether it’s safe to run.
  • How to target the correct site root: 
    • --path=<wordpress-root>
      and (multisite) 
      --url=<site-url>
  • Whether this is multisite and whether commands should run network-wide.
  • Any constraints (no downtime, no DB writes, maintenance window).
  • WP-CLI的运行环境（本地开发、预发布、生产环境）以及是否可安全执行命令。
  • 如何定位正确的站点根目录： 
    • --path=<wordpress-root>
      以及（多站点场景下）
      --url=<site-url>
  • 是否为多站点环境，以及命令是否需要在全网范围执行。
  • 任何约束条件（无停机、禁止数据库写入、维护窗口）。

Procedure

操作流程

0) Guardrails: confirm environment and blast radius

0) 防护措施：确认环境与影响范围

WP-CLI commands can be destructive. Before running anything that writes:
  1. Confirm environment (dev/staging/prod).
  2. Confirm targeting (path/url) so you don’t hit the wrong site.
  3. Make a backup when performing risky operations.
Read:
  • references/safety.md
WP-CLI命令可能具有破坏性。在执行任何写入操作前：
  1. 确认环境（开发/预发布/生产）。
  2. 确认目标路径/URL，避免操作错误站点。
  3. 执行高风险操作前创建备份。
参考：
  • references/safety.md

1) Inspect WP-CLI and site targeting (deterministic)

1) 检查WP-CLI与站点目标（确定性验证）

Run the inspector:
  • node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]
If WP-CLI isn’t available, fall back to installing it via the project’s documented tooling (Composer, container, or system package), or ask for the expected execution environment.
运行检查脚本：
  • node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]
如果WP-CLI不可用，可通过项目文档中记录的工具（Composer、容器或系统包）安装，或询问预期的执行环境。

2) Choose the right workflow

2) 选择合适的工作流

A) Safe URL/domain migration (
search-replace
)

A) 安全的URL/域名迁移（
search-replace
）

Follow a safe sequence:
  1. wp db export
    (backup)
  2. wp search-replace --dry-run
    (review impact)
  3. Run the real replace with appropriate flags
  4. Flush caches/rewrite if needed
Read:
  • references/search-replace.md
遵循安全操作序列：
  1. wp db export
    （创建备份）
  2. wp search-replace --dry-run
    （查看影响范围）
  3. 使用适当的标志执行实际替换
  4. 必要时刷新缓存/重写规则
参考：
  • references/search-replace.md

B) Plugin/theme operations

B) 插件/主题操作

Use 
wp plugin *
/ 
wp theme *
and confirm you’re acting on the intended site (and network) first.
Read:
  • references/packages-and-updates.md
使用
wp plugin *
/ 
wp theme *
命令，先确认操作的目标站点（及网络）是否正确。
参考：
  • references/packages-and-updates.md

C) Cron and queues

C) 定时任务与队列

Inspect cron state and run individual events for debugging rather than “run everything blindly”.
Read:
  • references/cron-and-cache.md
检查定时任务状态，调试时仅执行单个事件，而非盲目运行所有任务。
参考：
  • references/cron-and-cache.md

D) Multisite operations

D) 多站点操作

Multisite changes can affect many sites. Always decide whether you’re operating:
  • on a single site (
    --url=
    ), or
  • network-wide (
    --network
    / iterating sites)
Read:
  • references/multisite.md
多站点变更可能影响多个站点。需明确操作范围：
  • 单个站点（
    --url=
    ），或
  • 全网范围（
    --network
    / 遍历所有站点）
参考：
  • references/multisite.md

3) Automation patterns (scripts + wp-cli.yml)

3) 自动化模式（脚本 + wp-cli.yml）

For repeatable ops, prefer:
  • wp-cli.yml
    for defaults (path/url, PHP memory limits)
  • shell scripts that log commands and stop on error
  • CI jobs that run read-only checks by default
Read:
  • references/automation.md
对于可重复执行的操作，优先选择：
  • wp-cli.yml
    配置默认值（路径/URL、PHP内存限制）
  • 记录命令并在出错时停止的Shell脚本
  • 默认执行只读检查的CI任务
参考：
  • references/automation.md

Verification

验证步骤

  • Re-run 
    wpcli_inspect
    after changes that could affect targeting or config.
  • Confirm intended side effects:
    • correct URLs updated
    • plugins/themes in expected state
    • cron/caches flushed where needed
  • If there’s a health check endpoint or smoke test suite, run it after ops changes.
  • 变更可能影响目标或配置后，重新运行
    wpcli_inspect
    。
  • 确认预期的结果：
    • URL已正确更新
    • 插件/主题处于预期状态
    • 定时任务/缓存已按需刷新
  • 如果存在健康检查端点或冒烟测试套件，操作后运行测试。

Failure modes / debugging

故障模式与调试

  • “Error: This does not seem to be a WordPress installation.”
    • wrong 
      --path
      , wrong container, or missing 
      wp-config.php
  • Multisite commands affecting the wrong site
    • missing 
      --url
      or wrong URL
  • Search-replace causes unexpected serialization issues
    • wrong flags or changing serialized data unsafely
See:
  • references/debugging.md
  • “Error: This does not seem to be a WordPress installation.” 
    • --path
      错误、容器错误，或缺少
      wp-config.php
  • 多站点命令操作了错误站点
    • 缺少
      --url
      或URL错误
  • 搜索替换导致意外的序列化问题
    • 标志错误或不安全地修改序列化数据
参考：
  • references/debugging.md

Escalation

升级处理

  • If you cannot confirm environment safety, do not run write operations.
  • If the repo uses containerized tooling (Docker/wp-env) but you can’t access it, ask for the intended command runner or CI job.
  • 若无法确认环境安全性，请勿执行写入操作。
  • 如果仓库使用容器化工具（Docker/wp-env）但无法访问，询问预期的命令运行器或CI任务。