MIGRATION-VUE3.md 3.4 KB

Vue2 → Vue3 迁移说明

已完成的改动

1. 依赖与配置

  • package.json:新增 vue@^3.2.47vuex@^4.1.0uview-plus@^3.0.0,将 vuex-persistedstate 升级为 ^4.1.0
  • manifest.jsonvueVersion"2" 改为 "3"

2. 入口与状态

  • main.js:改为 uni-app Vue3 标准写法,使用 createSSRAppexport function createApp(),通过 app.use() 注册 store、uview-plus 及各插件,使用 app.config.globalProperties.$getDictsapp.mixin(globalMinxins)
  • store/index.js:使用 Vuex4 的 createStore,移除 Vue.use(Vuex),持久化配置(paths、reducer、storage)保持不变。

3. 插件适配 Vue3

  • utils/request.jsinstall(Vue, vm) 改为 install(app)
  • utils/api.js:改为 install(app),在 install 内获取 uni.$u.http,并挂载到 app.config.globalProperties.$u.api
  • utils/hideNav.js:指令从 inserted 改为 mountedinstall(Vue) 改为 install(app)
  • utils/doubleTap.js:指令从 bind/unbind 改为 mounted/unmountedinstall(Vue) 改为 install(app)
  • utils/common.js:所有 Vue.prototype.xxx 改为 app.config.globalProperties.xxx

4. UI 与样式

  • uview-ui → uview-plus:通过 npm 使用 uview-plus(Vue3 版本),不再使用本地 uni_modules/uview-ui
  • pages.json:easycom 指向 uview-plus/components/u-$1/u-$1.vueup- 前缀。
  • App.vue:样式改为 @import "uview-plus/theme.scss"uview-plus/index.scss
  • uni.scss:改为 @import 'uview-plus/theme.scss'

5. 组件兼容性

  • 所有使用 beforeDestroy 的页面改为 beforeUnmount(订单详情、跟进记录、回单列表、佣金列表、通话记录、接单卡片等)。
  • components/mk-upload/mk-upload.vue$listeners.onDeleteTake / onPreviewTake 改为使用 $attrs.onDeleteTake / onPreviewTake(Vue3 中已合并到 $attrs)。

你需要做的测试

  1. 安装依赖(若尚未执行):在项目根目录执行 npm install
  2. HBuilderX:用 HBuilderX 打开项目,在 manifest 中确认「Vue 版本」为 3,运行到浏览器(H5)或运行到手机或模拟器(App),重点验证:
    • 登录、首页、个人中心、TabBar 切换;
    • 线索、仓库、询价/核价、接单中心等主流程;
    • 订单详情、跟进、回单、佣金等子页与事件(如 uni.$on/uni.$off)是否正常。
  3. 真机打包:对 Android(及目标鸿蒙设备)打正式包,验证启动、后台保活、电话监听、上传录音等依赖原生能力的功能。
  4. 回滚:若出现问题,可将 manifest.jsonvueVersion 改回 "2",并恢复 Git 中 main.jsstore/index.js、各 utils 插件及上述页面/组件的修改,或从 vue2-legacy 分支恢复。

注意事项

  • uni.$on / uni.$off:仍为 uni-app 提供的 API,未做修改,Vue3 下可继续使用。
  • uni_modules:除 uview 已切换为 npm 的 uview-plus 外,其余 uni_modules(如 uni-table、bt-cropper、yui-tabs 等)未改,若某插件在 Vue3 下报错,再按需升级或替换。
  • vuex-persistedstate:npm 会提示已弃用,当前 4.x 在 Vuex4 下可正常使用;若后续需要可考虑迁移到 vuex-persister 等替代方案。