3周迁完80个页面：一次基于 miniprogram-to-vue3 的真实迁移实录

【免费下载链接】miniprogram-to-vue3将微信小程序源码转换为 vue3/uniapp3（Vue3/Vite版） 源码项目地址: https://gitcode.com/gh_mirrors/mi/miniprogram-to-vue3

miniprogram-to-vue3 是一款把微信小程序源码自动转换为 Vue3/Uniapp3（Vue3/Vite 版）的开源工具，支持单页面转换与整包迁移。这篇文章记录我们团队用它把一套 80 个页面、13 万行的小程序迁到 uniapp 3.0 的全过程：怎么选型、怎么试跑、踩了哪些坑，以及最终到底省了多少人力。

第一幕 · 困局：三份代码，一个促销活动改两天

我们团队维护一个商超小程序。刚开始只有微信端，20 来个页面，日子过得挺滋润。直到业务线扩张——要上 H5，要上支付宝端，公司没有跨端框架的预算，于是最朴素的做法出现了：复制一份，改。

于是同一套"满减逻辑"有了三份实现，同一个按钮在三个端里长得还不一样。改一个促销规则，前端要在三个仓库里各改一遍；联调时三个端一起报 bug，光对"哪个端漏了改"就能消耗半天。到去年初，仓库里已经堆了80 个页面、约 13 万行小程序代码，以及300 多处三端行为不一致的"历史遗产"。

我们做过一次手动迁移的评估：按 2 小时/页的保守速度，加上组件抽离和回归测试，最快也要 3-6 个月，且这段时间业务必须冻结，新需求全部押后。这显然不是老板能接受的时间表。

"不改是等死，手动改是找死"——团队就在这个档口开始找工具，找到了miniprogram-to-vue3。它干的事一句话就能说清：把微信小程序的 .wxml/.wxss/.js 读进来，吐给你一套能直接跑在 uniapp 3.0 上的 .vue 文件。

但先别急着跑，选型这关得过。

第二幕 · 抉择：凭什么不自己改，要用一个开源工具？

我们其实列了四条路，摆在一起看：

我们选它，理由很朴素：开源、本地跑、不传代码。商业服务要我们把源码打包发过去，安全评审直接卡死；全量重写风险太大；手动迁移时间不达标。剩下就它了。

道理要先讲明白再动手。它为什么能做到"秒级转换"？打个比方：就像给代码做一次"体检 + 翻译"。人不逐行读文章，而是先把文章拆成"主谓宾"的语法树（AST），翻译器只改树上的节点，最后再把树拼回通顺的句子。机器改树比人逐行改文本快得多，也不会看漏。

具体到这个项目，它有三条"翻译流水线"：

• 模板：wxml → posthtml 解析成 AST → 逐节点替换标签/属性 → 渲染成 Vue 模板，核心逻辑在 packages/posthtml-wxml2unitemplate/index.js；
• 脚本：js → Babel 解析成 AST → 把Page({})选项式 API 改写成script setup组合式 API，核心在 packages/babel-plugin-options2composition-page/index.js；
• 样式：wxss 走 postcss 通道，目前多数场景是"原样搬运"。

它敢这么干，还因为微信小程序和 uniapp 的语法太像了：wx:if换成v-if、bindtap换成@click、wx.换成uni.，本质就是一张映射表的事。

选型定了，接下来才是重头戏：真跑一次。

第三幕 · 实操：从"单页试跑"到"整包迁移"的 72 小时

第一步：环境准备（半天）

先把仓库拉下来，装上依赖：

git clone https://gitcode.com/gh_mirrors/mi/miniprogram-to-vue3 cd miniprogram-to-vue3 npm install

第二步：先跑通一个页面再说（半天）

别上来就整包跑，先挑一个最不起眼的列表页试水。注意路径不带后缀名：

npm run build pages/index/index

它会基于 src/generateVue3.js 去读同名的.wxml/.js/.wxss/.json四个文件，然后吐出一个pages/index/index-日期.vue。打开看一眼，你立刻能感受到它干了多少活：

// 转换前的小程序 JS Page({ data: { count: 0 }, increment() { this.setData({ count: this.data.count + 1 }); }, onShow() { this.increment(); } }); // 转换后的 Vue 组合式代码 const state = reactive({ count: 0 }); function increment() { state.count = state.count + 1; } onShow(function () { increment(); });

注意三件事：data变成了reactive、this.setData变成了直接改state、onShow从对象方法变成了从@dcloudio/uni-app导入的生命周期钩子。

第三步：整包迁移（一天）

单页没问题，就上npm run build:project：

npm run build:project ./miniprogram-src

入口在 src/project.js，它做的事像一个搬家队长：

1. 读app.json，复制 packages/template/uni-preset-vue-vite/ 作为新项目骨架；
2. 把app.js + app.wxss合成App.vue（见 src/generateAppvue.js）；
3. 把app.json的页面路由翻译成pages.json；
4. 通过依赖图工具 packages/babel-getDependencyGraph/ 收集所有页面/组件/工具 JS，逐个转换；
5. 根据usingComponents在 src/generateMainjs.js 里自动生成全局组件注册代码。

终端会实时打印"完成率：xx/xx"，哪页失败一目了然。

第四步：结果验证（剩下的时间全在这）

转换完不是终点，npm run dev跑起来才是真考试。我们第一轮编译报错 40 多个，绝大多数是三类：组件路径没对上、wxss里rpx单位要核对、个别事件参数拿不到dataset。

踩坑提醒：工具的 README 自己都写了"js 代码灵活性太大，转换后务必人工复核"。别把它当"一键完成"，要当"一键完成 80%，剩 20% 是你在干"。

第四幕 · 蜕变：三周之后我们拿到了什么

迁移加修整，全团队实际投入3 人周，比最初估的 8 人周砍了一半还多。前后对比如下（单页转换速度与错误率为团队实测，性能项为基于低端安卓机的示意数据，仅供参考）：

最大的隐性收益是**"三端不一致"这个历史包袱彻底清零**了——以后改逻辑只改一处，发版靠 uniapp 的多端编译，// #ifdef MP-WEIXIN这种条件编译想分端就分端。😌 运维心智从"三套代码"降为"一套代码 + 一个编译开关"。

第五幕 · 收尾：新手最容易踩的 Top 5 坑

最后把我们的血泪教训压缩成一张清单，给后来者当探雷器：

如果要用一句话总结落地节奏：先转工具函数和公共 JS（零风险）→ 再转简单展示页（验证流程）→ 然后转业务组件（处理 props 和事件）→ 最后啃核心页面（涉及复杂交互和分包）。每批转换后都跑一遍编译和冒烟测试，把错误控制在"小步快跑"的粒度内。

回到开头那个问题：三份代码的时代真的能结束吗？我们这次用工具 + 人工复核的组合拳，把 3-6 个月的迁移压到了 3 周。它的上限不在工具，而在你敢不敢拿一个真实页面先试一次。

仓库地址放这里，周末拉下来，找个页面跑一条命令，你就知道我在说什么了：https://gitcode.com/gh_mirrors/mi/miniprogram-to-vue3🚀

【免费下载链接】miniprogram-to-vue3将微信小程序源码转换为 vue3/uniapp3（Vue3/Vite版） 源码项目地址: https://gitcode.com/gh_mirrors/mi/miniprogram-to-vue3