EP16. "wp-wpcli-and-ops WP-CLI 与运维操作审查"

• 一条 wp search-replace 忘了加 --dry-run，网域名跑错環境直接全库替换——这种运维事故往往不是代码写错，是「跑指令的人没想清楚范围」，wp-wpcli-and-ops 就是专门抓这种坑
• 这是 jorgerosal/wordpress-skills 开源 skill 包里的其中一个，专门审查以 WP-CLI 为核心的 WordPress 运维流程
• 核心原则：运维指令在真正碰数据、真正跑到生产环境之前，范围、环境、副作用都要讲清楚——审查涵盖自定义 CLI 指令、search-replace 方案、multisite 定位、cron/cache 操作、维护脚本、部署时的自动化
• 📌 这个 skill 在上游仓库的 README 里标注为 🚧 in progress（截至 2026-09 撰写本篇笔记时），代表作者认为它还在持续打磨中；不代表内容不能用，下面的内容是照实际抓到的 SKILL.md 整理的
• 前置知识：先看过 Overview 系列的「Claude Code 是什么与新手上手」「进阶功能：Skills、Plugins 与 Routines」两篇，知道 Skill 是什么、怎么装

重点内容

这个 Skill 是做什么的

wp-wpcli-and-ops 审查的是「跑在服务器上、直接碰数据/环境」的操作，不是审查网页端的输入输出。重点抓：指令有没有讲清楚作用范围（单站点/整个 network/哪个环境）、有没有 dry-run 或备份这类安全网、破坏性操作有没有留日志或确认步骤、自定义 WP-CLI 指令有没有做参数校验。

适合用在：

• 审查自定义的 WP-CLI 指令或指令类
• 审计文档/脚本里出现的 wp 指令
• 规划安全的 search-replace 或迁移操作
• 检查 multisite / network 级别的运维步骤
• 审查 cron、cache、export、import、维护类工作流程

不适合用在：

• 没有运维操作面的一般插件架构（交给 wp-plugin-development）
• 不涉及运维流程的性能调优
• 纯 Playground 环境的设置流程（交给 wp-playground-development）
• 静态分析配置（交给 wp-phpstan-review）

触发方式

审查流程

1. 找出运维相关的面 — 自定义 WP_CLI::add_command() 注册、项目文档里出现的 wp 指令范例、部署脚本/CI job、multisite 操作手册或迁移计划
2. 先看范围和定位 — 这条指令是针对单个站点、整个 network，还是依赖当前环境？有没有明确用 --url、--path 或指定表？有没有隐含假设「反正就是当前这个安装」
3. 审查安全性和可逆性 — 能不能先 dry-run；破坏性步骤有没有确认或日志；高风险变更前有没有备份/导出步骤；纯查询指令跟真正会写入的指令有没有分清楚
4. 审查指令实现本身 — 参数校验、合理的默认值、有用的成功/错误输出、只读指令有没有偷偷夹带写入
5. 给严重度分级

严重度分级

按面向抓的坑

实操示例：search-replace 与自定义指令的错法/对法

# ❌ CRITICAL：直接在生产库上跑，没有 dry-run，也没限定范围
wp search-replace 'https://staging.example.com' 'https://example.com'

# ✅ GOOD：先 dry-run 确认影响范围，跑替换网址时排除 guid 字段，明确限定 network 范围
wp search-replace 'https://staging.example.com' 'https://example.com' --dry-run --skip-columns=guid
wp search-replace 'https://staging.example.com' 'https://example.com' --skip-columns=guid --network

// ❌ CRITICAL：自定义 CLI 指令直接吃参数就写库，没有任何校验
class Sync_Command extends WP_CLI_Command {
    public function run( $args, $assoc_args ) {
        update_option( 'sync_target', $args[0] );
        // 直接开始写入操作……
    }
}

// ✅ GOOD：校验参数、支持 dry-run、清楚区分只读检查跟真正写入
class Sync_Command extends WP_CLI_Command {
    /**
     * ## OPTIONS
     * <target>
     * : 同步目标环境
     * [--dry-run]
     * : 只显示会做什么，不真的执行
     */
    public function run( $args, $assoc_args ) {
        $target = sanitize_key( $args[0] ?? '' );
        if ( ! in_array( $target, [ 'staging', 'production' ], true ) ) {
            WP_CLI::error( "无效的同步目标：$target" );
        }
        if ( WP_CLI\Utils\get_flag_value( $assoc_args, 'dry-run' ) ) {
            WP_CLI::log( "（dry-run）会同步到：$target" );
            return;
        }
        update_option( 'sync_target', $target );
        WP_CLI::success( "已同步到：$target" );
    }
}

怎么安装

这个 skill 是 wordpress-skills 这个开源仓库（jorgerosal/wordpress-skills）打包的 18 个技能之一，安装一次，18 个技能一起到位，不用逐个装：

Claude Code：

装完重启 Claude Code，进到一个 WordPress 项目里跑 /wordpress-skills:wp-ops-review 验证有没有装成功（用 marketplace/submodule 方式装的话，指令前面会带插件命名空间 wordpress-skills:；用「只装这一个 skill」的方式则不带命名空间，直接 /wp-ops-review）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传技能文件夹（把 claude-skills/wp-wpcli-and-ops 这个文件夹打包上传，里面要包含 SKILL.md）——跟 Claude Code 的 git submodule/marketplace 安装方式不同，Desktop 端是手动上传 UI，装好之后同样能用自然语言或 slash 指令触发。

常见错误

• ❌ 把 WP-CLI 环境里的 wp eval/wp eval-file 一律当成错误——真正该报的是「该写成自定义指令的场合偷懒用了 eval」，不是所有 eval 都是坑
• ❌ 单站点安装（非 multisite）里没带 --url 也被报成风险——--url 主要是 multisite 场景下用来定位具体站点，单站点安装不适用这条
• ❌ 把纯查询/只读的指令（比如 wp option get）也要求要有 dry-run——dry-run 是给会写入/有副作用的操作用的
• 💡 判断 search-replace 风不风险，先看有没有 --dry-run 和明确的范围限定，而不是看用没用正则——正则本身只是「用起来要留意性能」，不是天生就危险

Sources

官方文档：

1. wordpress-skills（GitHub 仓库）— https://github.com/jorgerosal/wordpress-skills
2. wp-wpcli-and-ops SKILL.md — https://github.com/jorgerosal/wordpress-skills/blob/main/claude-skills/wp-wpcli-and-ops/SKILL.md