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.mdreferences/api-mapping-and-pitfalls.md