3步实操：从微信小程序到uni-app的完整迁移流程
很多人一听“迁移”就觉得技术门槛高，其实 uni-app 对微信小程序的兼容性做得特别好，官方文档里明确说“大部分微信小程序代码可直接迁移”（参考uni-app官方迁移指南）。我去年帮朋友迁移时，他的小程序有30多个页面、2000多行代码，核心功能迁移只用了半天，剩下的时间都在处理细节优化。下面这3步是我 的高效流程，你可以直接照着做。
第一步：环境搭建与项目初始化（30分钟搞定）
迁移前得先把“工作台”搭起来。你可能用过微信开发者工具写小程序，uni-app 推荐用 HBuilderX，这是官方开发工具，集成了项目创建、编译、调试一条龙功能，我自己用下来比其他工具快至少20%。具体操作很简单：
先去 HBuilderX官网 下载最新版，选“App开发版”（别选标准版，少了很多 uni-app 专属功能）。安装完成后打开，点左上角“文件→新建→项目”，选择“uni-app”，输入项目名称（ 和你的微信小程序同名，方便后续文件对照），模板选“默认模板”，然后点“创建”。这时候一个基础的 uni-app 项目就建好了，目录结构和微信小程序很像，比如 pages 放页面、components 放组件，你上手会很熟悉。
接下来要把微信小程序的代码“搬”过来。先在电脑里建个临时文件夹，把微信小程序的 pages、components、images 这三个文件夹复制进去（这是核心内容，其他配置文件后面会重新弄）。然后打开 HBuilderX 里的新项目，把临时文件夹里的 pages 和 components 直接拖到项目对应的目录下，图片资源拖到 static 文件夹（uni-app 推荐把静态资源放这里，打包时会自动处理）。
这里有个小细节我第一次做时踩过坑：微信小程序的 app.json 里的页面路径、窗口配置，需要手动转到 uni-app 的 pages.json 里。比如微信小程序 app.json 里的 "pages": ["pages/index/index"]，在 pages.json 里要写成 "pages": [{"path": "pages/index/index"}]；窗口配置里的 "navigationBarTitleText": "首页" 可以直接复制。你可以把两个配置文件并排打开，一条条对照着改，10分钟就能弄完。
第二步：代码适配与核心功能转换（最关键的一步）
环境搭好后，就到了最核心的代码适配环节。uni-app 虽然兼容大部分微信小程序语法，但毕竟是跨平台框架，有些 API 和组件需要调整。我 了三个“高频转换点”，你按这个顺序处理，效率会很高。
第一个是 API 替换。微信小程序里以 wx. 开头的 API（比如 wx.request、wx.navigateTo），在 uni-app 里要统一换成 uni. 开头。比如发送网络请求，微信里写 wx.request({url: 'xxx', success: res => {}})，uni-app 里要改成 uni.request({url: 'xxx', success: res => {}})。别担心记不住，我整理了一个常用 API 对照表，你可以直接对着改：
| 微信小程序API | uni-app对应API | 注意事项 |
|---|---|---|
| wx.request | uni.request | 参数完全兼容，无需改其他 |
| wx.navigateTo | uni.navigateTo | 路径前不用加 ‘/’，如 ‘pages/index/index’ |
| wx.getStorageSync | uni.getStorageSync | 完全兼容，直接替换前缀 |
| wx.showToast | uni.showToast | icon值”success”改”success”，”loading”改”loading” |
第二个是组件转换。微信小程序的内置组件（比如 、、）在 uni-app 里基本可以直接用，但有些属性需要调整。比如微信的 ，在 uni-app 里要写成 （因为图片放在了 static 文件夹）；还有 的 scroll-x 属性，在 uni-app 里要写成 scroll-x="true"（微信里可以直接写 scroll-x，但 uni-app 要求显式赋值）。我去年迁移时遇到过一个组件不显示的问题，查了半天才发现是 的 indicator-dots 属性没写 ="true"，所以这里一定要仔细检查。
第三个是样式适配。微信小程序用的是 wxss，uni-app 用的是 scss 或普通 css，大部分样式可以直接复制，但有两个地方要注意：一是单位，微信小程序常用 rpx，uni-app 也支持 rpx，但 把 rpx 统一换成 upx（uni-app 的跨平台单位，在不同设备上适配更准）；二是全局样式，微信小程序的 app.wxss 里的样式，要放到 uni-app 的 App.vue 的 标签里，并且去掉 @import 语句（uni-app 支持直接在 style 里写全局样式）。比如你原来在 app.wxss 里写 .red { color: red; }，直接复制到 App.vue 的 里就行。
第三步：测试与多端发布（确保每个平台都能用）
代码改完后，千万别急着发布，一定要测试！uni-app 最强的地方就是“一次开发，多端发布”，但不同平台的兼容性还是有差异。我 按“微信小程序→H5→其他平台”的顺序测试，因为微信小程序是你原来的主战场，先确保它能正常运行，再拓展其他平台。
测试微信小程序很简单：在 HBuilderX 顶部工具栏点“运行→运行到小程序模拟器→微信开发者工具”，第一次运行时会提示你输入微信开发者工具的安装路径，选对后就能自动打开模拟器了。这时候你可以像平时测试微信小程序一样，点点每个按钮、看看页面跳转、检查数据加载是否正常。我去年测试时发现一个问题：原来微信小程序里用 wx.getSystemInfoSync().statusBarHeight 获取状态栏高度，在 uni-app 里虽然能用，但在 iOS 和 Android 上数值不一样，后来改用 uni-app 提供的 uni.getSystemInfoSync().safeArea.top，兼容性更好（参考uni-app官方设备信息文档）。
如果需要发布到 H5，就在 HBuilderX 里点“发行→网站-H5手机版”，填写网站标题和域名，打包后会生成一个 unpackage 文件夹，把里面的 dist 目录上传到你的服务器就行。这里要注意：H5 不支持本地存储的 wx.setStorageSync，需要用 localStorage 代替，不过 uni-app 的 uni.setStorageSync 会自动适配，你不用改代码，它在 H5 环境下会自动调用 localStorage，这点特别方便。
至于其他平台（比如支付宝小程序、抖音小程序），流程和微信类似，在“HBuilderX→运行→运行到小程序模拟器”里选对应的平台就行。发布时注意每个平台都需要提前在对应开放平台注册账号、创建应用，比如支付宝小程序要在支付宝开放平台注册，抖音小程序要在抖音开放平台注册，这些账号信息在打包时需要填进去。
避坑指南：10+迁移常见问题及解决方案
虽然 uni-app 迁移难度不大，但细节没处理好很容易踩坑。我把去年迁移和后来帮其他开发者解决问题时遇到的高频坑点整理出来了，你遇到类似情况可以直接参考。
坑点1：自定义组件路径错误导致组件不显示
有个做工具类小程序的朋友，迁移时把自定义组件放在了 components 文件夹里，引用时写成 ，结果页面一直空白。后来我帮他检查发现，uni-app 引用自定义组件需要在页面的 json 文件里声明，比如在 pages/index/index.json 里加 "usingComponents": {"component-name": "../../components/component-name/component-name"}，和微信小程序的用法一样，但他忘了这一步。所以你迁移组件后，一定要检查每个页面的 json 文件，确保组件路径声明正确。
坑点2：原生插件不兼容导致功能失效
如果你的微信小程序用了原生插件（比如地图、支付相关的插件），迁移到 uni-app 时要注意：uni-app 支持的是“uni-app 插件市场”的插件，微信小程序的原生插件不能直接用。比如微信的“腾讯位置服务地图组件”，在 uni-app 里需要改用插件市场的“腾讯地图SDK”（插件市场地址）。我之前帮一个外卖小程序迁移时，就遇到过地图插件不兼容的问题，后来在插件市场找了替代插件，配置方法参考插件文档，半小时就解决了。
坑点3：路由跳转路径错误导致页面打不开
微信小程序的路由跳转路径可以写相对路径（比如 ../detail/detail），也可以写绝对路径（比如 /pages/detail/detail），但 uni-app 推荐用相对路径，而且不能以 / 开头。有个开发者跟我说他的页面跳转一直报“页面不存在”，我一看他写的是 uni.navigateTo({url: '/pages/detail/detail'})，把前面的 / 去掉改成 url: 'pages/detail/detail' 就好了。所以你迁移时，所有路由跳转的 url 都要检查一下，去掉开头的 /。
坑点4：样式隔离导致全局样式不生效
uni-app 的页面样式默认是隔离的（和 Vue 的 scoped 类似），如果你在 App.vue 里写了全局样式，但在页面里没生效，可能是因为页面的 style 标签加了 scoped。比如你在 App.vue 里写 .title { font-size: 16px; }，但页面的 style 有 scoped，这时候 .title 就不会生效。解决办法很简单：要么把全局样式写在 uni.scss 里（uni-app 会自动引入），要么在页面样式里用 /deep/ 穿透（比如 /deep/ .title { font-size: 16px; }）。我个人推荐用 uni.scss，管理起来更方便。
其实迁移到 uni-app 后，你会发现开发效率提升特别明显。我那个电商朋友现在更新功能，改一处代码就能同步到6个平台，之前改6个平台的代码要花一天，现在两小时就搞定。如果你按上面的步骤操作，遇到问题可以对照避坑指南，基本都能解决。对了，迁移前一定要备份微信小程序的代码，万一操作失误还能恢复。你迁移过程中遇到什么具体问题，或者有其他平台的适配需求，都可以留言告诉我，我看到会回复你~
你完全不用担心用户数据会丢，真的。迁移这事儿说白了就是“换个开发框架写前端代码”，原来小程序里用户的账号信息、订单记录、收藏内容这些数据，根本不在前端代码里存着——它们要么在你后台的服务器数据库里，要么在微信云开发、阿里云这种云数据库里，就像你手机里的照片存在内存卡里，换个手机壳（前端框架）照片肯定还在啊。我去年帮那个电商朋友迁移时，他小程序里5万用户的购买记录、购物车数据，迁移前后一点没少，用户打开新编译的小程序，感觉和原来一模一样，就是加载速度快了点。
不过话说回来，虽然数据本身不会丢，但本地开发环境的文件还是得备份。比如你电脑里微信小程序项目的本地调试日志、没提交到云端的临时代码、自己写的工具函数这些，万一迁移时误删了就麻烦了。我之前遇到个开发者，迁移时觉得“反正数据在云端”，直接把原项目文件夹删了，结果后来想对比原来的某个交互逻辑，只能去线上扒代码，折腾了好久。所以 你迁移前，先把微信小程序的整个项目文件夹复制一份存到移动硬盘或者网盘里，数据库数据也导出一份备份，花10分钟做这个事，能省后面好几天的麻烦。
微信小程序迁移到uni-app需要具备什么技术基础？
零基础也能操作，只要你熟悉基础的微信小程序开发（比如会用微信开发者工具、了解小程序目录结构和基础语法），跟着文中的3步流程和避坑指南一步步做就行。重点是耐心对照API和组件转换表，遇到问题可以参考uni-app官方文档或留言提问，大部分开发者1-2天就能完成基础迁移。
迁移完成后，原来的微信小程序还能继续维护吗？
可以。迁移到uni-app后，你仍然可以通过HBuilderX将项目编译为微信小程序格式并发布，操作和原来在微信开发者工具里发布类似。后续功能更新只需修改uni-app项目代码，重新编译发布即可，不会影响原微信小程序的线上版本，相当于多了一个“多端开发副本”。
迁移过程中，微信小程序的用户数据会丢失吗？
不会。迁移的是前端代码（页面、组件、逻辑等），用户数据通常存储在后端服务器或云开发数据库（如微信云开发、阿里云等），这部分数据不会受迁移影响。不过 迁移前备份微信小程序的代码和数据库数据，避免因操作失误导致本地文件丢失。
迁移到uni-app后，发布到其他平台（如支付宝、H5）需要额外开发吗？
大部分功能无需额外开发。uni-app的核心优势就是“一次开发，多端发布”，基础功能（如页面跳转、数据请求、组件渲染）会自动适配不同平台。但部分平台特有功能（如微信的开放能力、支付宝的芝麻信用接口）可能需要用条件编译（#ifdef语法）单独编写，具体可参考uni-app官方的多端适配文档。
有没有工具可以自动将微信小程序代码转换为uni-app代码？
有。HBuilderX提供了“微信小程序转换uni-app”插件（在HBuilderX的“插件市场”搜索即可安装），能自动转换部分代码（如页面结构、样式、基础API），但复杂项目（如使用了大量原生组件、自定义编译配置的）仍需手动调整。 先用插件自动转换，再对照文中的避坑指南检查适配细节，能节省50%以上的手动工作量。
