native-to-weapp-vite-wevu-migration
用途
把原生小程序迁移到 weapp-vite + wevu + Vue SFC,遵循“行为等价优先、语义逐步升级、每步可回滚”。
何时使用
- 用户要把原生
Page/Component迁到.vue。 - 用户要把
setData重构为响应式状态。 - 用户要迁移
properties/observers/triggerEvent。 - 用户要引入
definePageMeta/ layout / autoRoutes / 受管 TS。 - 用户要在迁移后让 AI 能稳定使用项目。
不适用场景
本 skill 聚焦迁移路径和风险治理。
- 普通 weapp-vite 配置问题:使用
weapp-vite-best-practices。 .vue宏或模板兼容:使用weapp-vite-vue-sfc-best-practices。wevu运行时写法优化:使用wevu-best-practices。
核心流程
- 先按页面族或组件族划分迁移波次,不要把迁移和大规模业务重构绑在一起。
- 固化迁移前基线:页面入口、关键交互、关键接口、已知异常、至少一条冒烟路径。
- 先做机械迁移,再做语义迁移:
- js/wxml/wxss/json -> .vue - properties -> defineProps - triggerEvent -> defineEmits - observers -> watch/watchEffect
- 再做运行时升级:
- this.data/setData -> ref/reactive/computed - 页面元信息走 definePageMeta - 平台分支收敛到 import.meta.env.PLATFORM
- 迁移后统一 AI/工具链约束:
- 先读根 AGENTS.md 与 node_modules/weapp-vite/dist/docs/*.md - 先跑 wv prepare - 明确 wv screenshot / wv compare / wv ide logs --open
- 每波次独立验证并保留回滚点;布局或视觉变化再补截图对比。
约束
- 不要在同一波次同时做迁移和架构重写。
- 不要把原生实例对象暴露到模板状态。
- 不要跳过
prepare和.weapp-vite支持文件验证。 - 不要只看 dev 环境,不看构建产物和真实运行时。
输出
应用本 skill 时,输出必须包含:
- 迁移波次。
- 每波次任务清单。
- 风险点与回滚点。
- 最小验证命令。
完成标记
- 页面/组件已完成
.vue化或明确记录留在原生的原因。 - 状态更新不依赖大对象
setData。 - props / events 契约类型化。
.weapp-vite支持文件和 AI 指引已对齐。- 至少有一轮可复现验证覆盖关键链路。
参考资料
references/migration-checklist.mdreferences/api-mapping-and-pitfalls.md