EP11. "wp-migration-upgrade-review 数据迁移与升级审查"

• 插件的升级脚本如果没做版本判断，每次页面加载都会重新跑一遍数据迁移——这种坑往往要等到线上库变大了才炸出来
• wp-migration-upgrade-review 是 jorgerosal/wordpress-skills 这套 18 个 skill 里专门审查 WordPress 插件/主题升级流程的一个，覆盖 schema 变更、dbDelta() 用法、数据回填、批处理、回滚风险
• 核心原则一句话：升级流程必须可重复执行（idempotent）、有版本意识、分批增量、对线上真实数据安全
• 前置知识：先看过 EP01「wp-security-review 安全审查」，理解「不可逆操作要先确认」这个大原则——这个 skill 处理的正是升级里最容易不可逆的那部分（删表、删字段、数据覆盖）

重点内容

这个 Skill 是做什么的

wp-migration-upgrade-review 审查插件/主题的升级流程：激活钩子里的迁移逻辑、版本比对、后台回填任务、手动修复工具，检查版本守卫是否存在、流程是否幂等（跑两次结果一样）、破坏性操作是否有正当理由、大批量数据处理是否分批。

适合用在：

• 审查 schema 或 option 迁移逻辑
• 审计 dbDelta() 用法
• 检查带版本号的升级流程
• 审查后台回填任务或一次性修复脚本
• 为高风险的版本发布做上线前检查

不适合用在：

• 跟迁移逻辑无关的纯性能审查
• 缺乏升级情境的通用插件架构审查
• 跟产品升级无关的一次性内容导入

触发方式

审查流程

四步走：

1. 识别迁移面：定位激活钩子、版本比对逻辑、后台回填任务、手动修复工具
2. 先检查安全性：版本守卫存不存在、流程是不是幂等、破坏性操作有没有正当理由、大批量数据处理有没有分批
3. 审查 schema 与数据流：dbDelta() 用法、option 改名/复制/删除的先后顺序、回填任务的持久性、升级完成标记
4. 按严重度分类：CRITICAL 是没有版本守卫、破坏性写入没有检查、长时间运行的升级挂在页面加载上；WARNING 是缺批处理、没考虑回滚、部分执行状态没有记录；INFO 是可以建立更清楚的迁移注册表或改进日志

版本升级要守住的原则

快速扫描指令（rg）

# CRITICAL：版本比对/升级标记、schema 变更、激活与升级钩子
rg -n "version_compare|get_option\s*\(.*version|update_option\s*\(.*version" . -g '*.php'
rg -n "dbDelta|CREATE TABLE|ALTER TABLE|DROP TABLE" . -g '*.php'
rg -n "register_activation_hook|upgrader_process_complete|admin_init|init" . -g '*.php'

# WARNING：批量候选、后台调度、删除/改名操作
rg -n "foreach|while" . -g '*.php'
rg -n "wp_schedule_event|as_schedule_single_action|WP_CLI" . -g '*.php'
rg -n "delete_option|rename|migrate|backfill" . -g '*.php'

# INFO：升级 class 或迁移管理器
rg -n "Migration|Upgrade|Installer|Schema" . -g '*.php'

实操示例

// ❌ CRITICAL：每次页面加载都重新跑一遍升级逻辑，没有版本守卫
add_action( 'init', function () {
    dbDelta( myplugin_get_schema_sql() );
    myplugin_backfill_all_orders();
} );

// ✅ GOOD：先比对版本，跑完才更新版本标记，保证幂等、不重复跑
add_action( 'init', function () {
    $installed_version = get_option( 'myplugin_db_version', '0' );

    if ( version_compare( $installed_version, MYPLUGIN_DB_VERSION, '>=' ) ) {
        return;
    }

    dbDelta( myplugin_get_schema_sql() );
    update_option( 'myplugin_db_version', MYPLUGIN_DB_VERSION );
} );

// ❌ CRITICAL：大批量回填一次性跑完，容易超时、也没法从中断处恢复
function myplugin_backfill_all_orders() {
    $orders = wc_get_orders( array( 'limit' => -1 ) );
    foreach ( $orders as $order ) {
        myplugin_migrate_order_meta( $order );
    }
}

// ✅ GOOD：用 Action Scheduler 分批处理，每批处理完再排下一批
function myplugin_backfill_batch( $offset = 0, $batch_size = 50 ) {
    $orders = wc_get_orders( array( 'limit' => $batch_size, 'offset' => $offset ) );

    foreach ( $orders as $order ) {
        myplugin_migrate_order_meta( $order );
    }

    if ( count( $orders ) === $batch_size ) {
        as_schedule_single_action( time() + 30, 'myplugin_backfill_batch', array( $offset + $batch_size ) );
    } else {
        update_option( 'myplugin_backfill_done', true );
    }
}

怎么安装

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

Claude Code：

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

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

常见错误

• ❌ 把「代码里出现 foreach/while」一律当成批处理问题标出来——官方检测规则只是把循环列为「需要人工判断是不是批量候选」的 WARNING 信号，不是循环本身就有问题，要看循环处理的数据量和场景
• ❌ WP-CLI 触发的迁移脚本也要求跟页面加载时的升级逻辑一样做超时防护——WP-CLI 是命令行直接跑，没有 HTTP 请求超时的限制，判断标准不一样
• ❌ 把「一次性内容导入」（跟产品版本升级无关）也套用这个 skill 的迁移安全标准——skill 明确说明这类场景不在适用范围内
• ❌ 只要看到 delete_option/DROP TABLE 就判 CRITICAL，不看有没有先做版本确认和数据验证——真正的判断标准是「破坏性操作前有没有确认数据已经迁移完成并验证过」，不是看到删除关键字就报警
• 💡 版本守卫（version_compare + 存好的 _version option）是这个 skill 里最基础也最常被漏掉的一条，审查时第一步永远是先确认这个守卫存不存在

Sources

官方文档：

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