native-to-weapp-vite-wevu-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

native-to-weapp-vite-wevu-migration

Overview

将原生小程序项目迁移到

weapp-vite + wevu + Vue SFC

，目标是“行为等价优先、逐步语义升级、可回滚”。

适用任务：

原生
```
Page/Component
```
向 SFC 迁移。
```
this.data
```
/
```
setData
```
重构为
```
ref/reactive
```
。

properties/observers/triggerEvent

迁移为

defineProps/watch/defineEmits

。

增加
```
import.meta.env.PLATFORM
```
分支与多平台验证。
建立迁移过程中的 e2e 运行时错误拦截与回滚策略。

Migrate native mini-program projects to

weapp-vite + wevu + Vue SFC

, with the goals of "behavior equivalence first, gradual semantic upgrade, rollback capability".

Applicable tasks:

Migrate native
```
Page/Component
```
to SFC.
Refactor
```
this.data
```
/
```
setData
```
to
```
ref/reactive
```
.

Migrate

properties/observers/triggerEvent

defineProps/watch/defineEmits

Add
```
import.meta.env.PLATFORM
```
branches and cross-platform validation.
Establish e2e runtime error interception and rollback strategies during migration.

Workflow

锁定迁移波次

先明确本轮只迁移哪些页面族（例如订单、优惠券）。
禁止把业务重构和技术迁移放在同一批提交。

建立迁移前基线

列出页面入口、关键交互、关键接口返回结构。
记录现有异常行为（如空数组崩溃、参数类型漂移）。

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

机械迁移：把
```
js/wxml/wxss/json
```
合并为
```
.vue
```
，流程保持等价。
语义迁移：替换为
```
ref/reactive/computed/watch
```
，并清理大对象
```
setData
```
。

优先迁移组件契约

输入契约：
```
properties
```
->
```
defineProps
```
+
```
withDefaults
```
。
输出契约：
```
triggerEvent
```
->
```
defineEmits
```
+ 类型化事件签名。
副作用契约：
```
observers
```
->
```
watch/watchEffect
```
。

处理原生能力访问

优先使用
```
emit
```
和响应式变量。
需要原生实例方法时，在
```
setup(_, { instance })
```
中使用
```
instance
```
。
不把
```
instance
```
泄露到可序列化状态里。

加入多平台条件分支

统一使用
```
import.meta.env.PLATFORM
```
做平台守卫。
避免在业务页面散落
```
wx/my/tt
```
分支，收敛到 platform helper。

迁移验证与回滚

先单页冒烟，再定向 e2e，再关键链路真机回归。
e2e 必须收集运行时错误日志，避免“页面可见但持续报错”。
每个页面族独立提交，保证可单独回滚。

Lock migration batches

First, clarify which page groups (e.g., orders, coupons) to migrate in this round.
Do not combine business refactoring and technical migration in the same batch of commits.

Establish pre-migration baseline

List page entries, key interactions, and response structures of critical APIs.
Document existing abnormal behaviors (e.g., crashes caused by empty arrays, parameter type drift).

Perform mechanical migration first, then semantic migration

Mechanical migration: Merge
```
js/wxml/wxss/json
```
into
```
.vue
```
files while maintaining equivalent workflows.
Semantic migration: Replace with
```
ref/reactive/computed/watch
```
and clean up large-object
```
setData
```
usage.

Prioritize component contract migration

Input contract:
```
properties
```
->
```
defineProps
```
+
```
withDefaults
```
.
Output contract:
```
triggerEvent
```
->
```
defineEmits
```
+ typed event signatures.
Side effect contract:
```
observers
```
->
```
watch/watchEffect
```
.

Handle native capability access

Prioritize using
```
emit
```
and reactive variables.
When native instance methods are required, use
```
instance
```
in
```
setup(_, { instance })
```
.
Do not leak
```
instance
```
into serializable state.

Add cross-platform conditional branches

Uniformly use
```
import.meta.env.PLATFORM
```
as platform guards.
Avoid scattering
```
wx/my/tt
```
branches in business pages; converge them to platform helpers.

Migration validation and rollback

First perform single-page smoke testing, then targeted e2e testing, followed by real-device regression for critical links.
e2e testing must collect runtime error logs to avoid "pages are visible but continuously report errors".
Submit each page group independently to ensure individual rollback capability.

Guardrails

不要在同一波次同时进行“迁移 + 架构重写”。
不要把原生实例对象返回到模板状态。
不要跳过构建产物验证，只看 dev 环境。
不要先跑全量回归；迁移阶段优先高价值链路。

Do not perform "migration + architecture rewrite" in the same batch.
Do not return native instance objects to template state.
Do not skip build artifact validation and only rely on the dev environment.
Do not run full regression first; prioritize high-value links during the migration phase.

Completion Checklist

迁移页面已改为
```
.vue
```
，不再使用
```
Page/Component
```
构造器。
页面状态更新不依赖
```
setData
```
大对象写法。
组件事件/props 契约完成类型化（
```
defineProps/defineEmits
```
）。
多平台分支使用
```
import.meta.env.PLATFORM
```
，并有至少 1 个次平台验证。
e2e 能捕获运行时报错，并对关键链路有断言。
回滚点与迁移记录已写入变更说明。

Migrated pages have been converted to
```
.vue
```
files and no longer use the
```
Page/Component
```
constructor.
Page state updates do not rely on large-object
```
setData
```
syntax.
Component event/prop contracts are typed (using
```
defineProps/defineEmits
```
).
Cross-platform branches use
```
import.meta.env.PLATFORM
```
, with validation on at least one secondary platform.
e2e testing can capture runtime errors and has assertions for critical links.
Rollback points and migration records are documented in the change description.

References

```
references/migration-checklist.md
```
```
references/api-mapping-and-pitfalls.md
```

```
references/migration-checklist.md
```
```
references/api-mapping-and-pitfalls.md
```