wp-wpcli-and-ops

WP-CLI 与运维

何时使用

当任务涉及通过 WP-CLI 执行 WordPress 运维操作时使用此技能，包括：

• wp search-replace（URL 更改、域名迁移、协议切换）
• 数据库导出/导入、重置和检查（wp db *）
• 插件/主题安装/激活/更新、语言包
• cron 事件列表/运行
• 缓存/重写刷新
• 多站点操作（wp site *、--url、--network）
• 构建可重复脚本（wp-cli.yml、shell 脚本、CI 任务）

所需输入

• WP-CLI 将在哪里运行（本地开发、预发布、生产环境）以及运行是否安全。
• 如何定位正确的站点根目录：
  • --path=<wordpress-root> 和（多站点）--url=<site-url>
• 是否为多站点以及命令是否应在全网范围内运行。
• 任何约束条件（无停机、无数据库写入、维护窗口）。

操作步骤

0) 安全护栏：确认环境和影响范围

WP-CLI 命令可能具有破坏性。在执行任何写入操作之前：

1. 确认环境（开发/预发布/生产）。
2. 确认目标（路径/URL），以免影响错误的站点。
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) 安全的 URL/域名迁移（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) Cron 和队列

检查 cron 状态并运行单个事件以进行调试，而不是“盲目运行所有事件”。

阅读：

• references/cron-and-cache.md

D) 多站点操作

多站点的更改可能影响许多站点。始终确定您是在：

• 单个站点上操作（--url=），还是
• 全网范围操作（--network / 遍历站点）

阅读：

• references/multisite.md

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

对于可重复的运维操作，推荐使用：

• wp-cli.yml 设置默认值（路径/URL、PHP 内存限制）
• 记录命令并在出错时停止的 shell 脚本
• 默认只运行只读检查的 CI 任务

阅读：

• references/automation.md

验证

• 在可能影响定位或配置的更改后，重新运行 wpcli_inspect。
• 确认预期的副作用：
  • 正确的 URL 已更新
  • 插件/主题处于预期状态
  • cron/缓存已按需刷新
• 如果有健康检查端点或冒烟测试套件，在运维更改后运行它。

失败模式 / 调试

• “错误：这似乎不是一个 WordPress 安装。”
  • --path 错误、容器错误或缺少 wp-config.php
• 多站点命令影响错误的站点
  • 缺少 --url 或 URL 错误
• Search-replace 导致意外的序列化问题
  • 标志错误或不安全地更改序列化数据

参见：

• references/debugging.md

升级处理

• 如果您无法确认环境安全，请不要执行写入操作。
• 如果仓库使用容器化工具（Docker/wp-env）但您无法访问，请询问预期的命令运行器或 CI 任务。