native-to-weapp-vite-wevu-migration

目的

将原生小程序迁移到 weapp-vite + wevu + Vue SFC ，遵循“行为等价优先、语义逐步升级、全程可回滚”。

触发信号

• 用户要把原生 Page/Component 迁移到 .vue 。

• 用户要把 this.data/setData 重构为响应式状态。

• 用户要迁移 properties/observers/triggerEvent 契约到 Vue/wevu 写法。

• 用户要做多平台守卫（import.meta.env.PLATFORM ）并验证一致性。

• 用户要迁移阶段的 e2e 校验、日志拦截和回滚机制。

适用边界

使用本 skill 的前提是“迁移安全和落地路径”是核心问题。

以下情况不应作为主 skill：

• 只是在 weapp-vite 项目内做常规配置优化。使用 weapp-vite-best-practices 。

• 只是在 .vue 里处理宏或模板兼容。使用 weapp-vite-vue-sfc-best-practices 。

• 只是在 wevu 运行时做生命周期/store 优化。使用 wevu-best-practices 。

快速开始

• 划分迁移波次并定义回滚边界。

• 建立迁移前基线（关键页面、关键交互、关键接口）。

• 按“机械迁移 -> 语义迁移 -> 定向验证”推进。

• 每个页面族独立提交，保证可单独回滚。

执行流程

• 锁定迁移波次

• 本轮明确页面族和边界（例如订单链路、活动链路）。

• 禁止混入大规模业务重构或架构重写。

• 建立迁移前基线

• 列出页面入口、关键交互、关键接口返回结构。

• 记录现有已知异常（例如空数组崩溃、参数漂移、边界态闪烁）。

• 固化至少一组可重复的冒烟路径。

• 先机械迁移，再语义迁移

• 机械迁移：js/wxml/wxss/json -> .vue ，保持行为等价。

• 语义迁移：this.data/setData -> ref/reactive/computed/watch ，逐步降低大对象写入。

• 保证每步都有可验证输出，不跨越多个风险层级。

• 优先迁移组件契约

• 输入契约：properties -> defineProps

• withDefaults 。

• 输出契约：triggerEvent -> defineEmits

• 类型化事件签名。

• 副作用契约：observers -> watch/watchEffect 。

• 处理原生能力访问

• 默认优先 emit 与响应式状态流。

• 必须调用原生实例时，在 setup(_, { instance }) 局部使用。

• 不把原生实例对象暴露到可序列化状态或跨层共享结构。

• 引入平台守卫

• 统一使用 import.meta.env.PLATFORM 。

• 将平台分支集中在 helper 层，避免散落在业务页面。

• 建立迁移验证与回滚闭环

• 验证顺序：单页冒烟 -> 定向 e2e -> 关键链路回归。

• e2e 必须收集运行时错误日志，防止“页面可见但持续报错”。

• 每个页面族独立提交，具备单独回滚能力。

约束

• 不要在同一波次同时进行“迁移 + 架构重写”。

• 不要把原生实例对象返回到模板状态。

• 不要跳过构建产物验证，只看 dev 环境。

• 不要先跑全量回归；迁移阶段优先高价值链路。

• 不要跳过迁移前基线采集，否则难以证明行为等价。

输出要求

应用本 skill 时，输出必须包含：

• 迁移波次划分与边界说明。

• 每波次的“机械迁移 / 语义迁移 / 验证”任务清单。

• 风险点与回滚点。

• 最小验证命令与通过标准。

完成检查

• 迁移页面已改为 .vue ，不再使用 Page/Component 构造器。

• 页面状态更新不依赖 setData 大对象写法。

• 组件事件/props 契约完成类型化（defineProps/defineEmits ）。

• 多平台分支使用 import.meta.env.PLATFORM ，并有至少 1 个次平台验证。

• e2e 能捕获运行时报错，并对关键链路有断言。

• 回滚点与迁移记录已写入变更说明。

参考资料

• references/migration-checklist.md

• references/api-mapping-and-pitfalls.md