HarmonyOS鸿蒙Next中Unaipp开发白屏，如何排查？

HarmonyOS鸿蒙Next中Unaipp开发白屏，如何排查？ 我的app是用unaipp开发的，现在要打包成鸿蒙的app，首先要从vue2升级vue3，我前期做了些升级处理，也可以在鸿蒙模拟器上跑起来，但是跑起来出现logo后就白屏，昨天有修改了一些未转化成vue3的代码，能简单显示调试的界面。但是涉及业务流程的界面还是白屏，不知道怎么排查和修改。

Vue.use(Vuex);从这个代码开始白屏的。

8 回复

【解决方案】

  1. 当前仅支持将Vue3项目编译至HarmonyOS平台，Vue2项目需先全部升级至Vue3版本。具体操作请参阅官方迁移指南：uni-app 官方 Vue2 迁移 Vue3 指南，Vue 官方 Vue2 迁移 Vue3 指南。可能因为未全部升级为Vue3导致无法实现需要的功能。

    特别说明：uni-app对Vue版本的要求仅体现为需依赖Vue3版本运行，在代码写法上无特殊限制，只需确保项目升级至Vue3后能够正常运行即可。

  2. 另外，一些尚未适配HarmonyOS的uni接口（适配情况见uni-app官网API文档）和plus接口需要调用HarmonyOS API来适配。如果uni组件和三方库组件均不满足需求，可考虑嵌入HarmonyOS组件。
  3. 部分接口需要声明权限和向用户申请授权。 关于uni-app的版本更新、能力支持矩阵及技术交流等最新动态，请持续关注uni-app官方变更动态及uni-app-harmony。

【背景知识】

uni-app是基于Vue.js的跨平台前端开发框架。自HBuilderX 4.27版本起，uni-app已支持HarmonyOS平台的APP开发。完整适配流程请参见uni-app官网HarmonyOS APP专题文档。

正常不存在性能问题，如果部分页面或功能有性能建议使用uts调用HarmonyOS侧API。更多关于uni-app性能优化可以参考uni-app官网性能优化专题。

【问题分析】

升级部分代码后需要打包的app在模拟器上无法正常测试，业务界面出现白屏。需要排查代码是否完全升级、配置和接口是否正确以及项目升级至Vue3后能否正常运行。

更多关于HarmonyOS鸿蒙Next中Unaipp开发白屏，如何排查？的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


之前已经按文档调整过了，运行起来还是白屏。

uni-app适配：

1. vue2项目需要升vue3

2. 检查HTML和代码条件编译是否命中鸿蒙平台

3. plus等不支持的方法需要使用uni方法或UTS插件替换

4. 部分接口需要声明权限和向用户申请授权

5. 调试手段：

  • 通过DevTools查看子页/元素是否加载
  • 通过JSVM调试查看是否有报错

6. 最终手段：

二分法排查业务代码

Devtools调试：

uni-app使用Devtools调试HarmonyOS应用。

  1. 将设备连接至电脑，运行uni-app到HarmonyOS;
  2. 在HbuilderX中打开终端，执行 hdc shell ，再执行 hdc shell cat /proc/net/unix | grep devtools ，再输入exit退出。hdc fport 执转发端口。
  3. 在电脑端Chrome浏览器地址栏中输入调试工具地址 chrome://inspect/#devices 并打开该页面，点击 “Configure” 按钮，添加配置：localhost:9222然后保存。
  4. 如果前面的步骤执行成功，Chrome的调试页面将显示待调试的网页。
  5. 点击inspect进入调试页面，还可在Element中审查元素，检查元素遮挡和样式异常问题。

参考链接：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-debugging-with-devtools

JSVM调试：

  1. 转发端口。hdc fport tcp:9229 tcp:9225。转发开发者个人计算机侧端口9229到端侧端口9225。结果为"Forwardport result:OK"即可。
  2. 在chrome浏览器地址栏输入"localhost:9229/json"，回车。获取端口连接信息。
  3. 拷贝"devtoolsFrontendUrl"字段url内容到地址栏，回车，进入DevTools源码页，将看到在应用中通过OH_JSVM_RunScript执行的JS源码，此时暂停在第一行JS源码处。(注："devtoolsFrontendUrl"字段url只支持使用Chrome、Edge浏览器打开，不支持使用Firefox、Safari等浏览器打开。)
  4. 用户可在源码页打断点，通过按钮发出各种调试命令控制JS代码执行，并查看变量。

参考链接：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/jsvm-debugger-cpuprofiler-heapsnapshot

白屏问题定位请看：https://developer.huawei.com/consumer/cn/forum/topic/0201192388832518497

有要学HarmonyOS AI的同学吗，联系我：https://www.itying.com/goods-1206.html

核心问题定位：Vuex初始化兼容性

根据白屏触发点 Vue.use(Vuex)，此代码在Vue3中已废弃。Vue3要求通过 createStore 和 app.use(store) 方式初始化Vuex。

鸿蒙Next中UniApp开发白屏，可按以下步骤排查：

  1. 检查编译配置：确认IDE中已正确安装并配置HarmonyOS SDK与工具链，项目编译目标是否为HarmonyOS。

  2. 查看运行日志：在DevEco Studio的Log窗口中，筛选应用进程日志，重点查看应用启动阶段的错误或异常信息。

  3. 核对资源文件：检查entry/src/main/resources目录下的资源文件（如图片、布局文件）是否存在或引用路径错误。

  4. 验证页面路由：检查应用启动的首个页面（在config.json中配置）路径是否正确，页面文件是否已正常编译到HAP包中。

  5. 检查权限声明：在module.json5中确认应用所需的网络等基本权限已声明。

若日志中有具体错误码，可结合鸿蒙官方文档进一步定位。

从你描述的情况来看，问题很可能集中在Vue 3的兼容性以及UniApp在HarmonyOS Next环境下的特定适配上。你提到从Vue.use(Vuex);开始出现白屏，这是非常关键的线索。

核心问题分析：

  1. Vuex的Vue 3兼容性问题：在Vue 2中，使用Vue.use(Vuex)来安装Vuex。但在Vue 3中，创建和安装Store的方式发生了根本变化。Vue 3使用createStore方法创建store，并通过app.use(store)挂载，而不是全局的Vue.use。直接使用Vue 2的Vuex语法在Vue 3项目中会导致错误，从而引发白屏。
  2. UniApp对HarmonyOS Next的适配度：UniApp对HarmonyOS Next（纯HarmonyOS内核）的支持仍处于完善阶段。一些在Vue 2或Web环境中正常的API、生命周期或组件行为，在HarmonyOS Next的ArkTS运行时环境下可能无法正常工作，导致渲染失败。

具体排查步骤：

  1. 彻底升级Vuex到Vue 3版本：

    • 确保安装的是支持Vue 3的Vuex版本（通常是vuex@4.x）。
    • 修改Store创建方式：
      // Vue 3 + Vuex 4 的正确方式
import { createApp } from 'vue'
import { createStore } from 'vuex'
import App from './App.vue'

const store = createStore({
  // ... state, mutations, actions, getters
})

const app = createApp(App)
app.use(store)
app.mount('#app')
    • 检查所有用到Vuex的组件，将mapState, mapGetters, mapActions, mapMutations等辅助函数从vuex导入改为从'vuex'导入，或使用新的Composition API写法（useStore）。

  2. 检查HarmonyOS Next的调试信息：

    • 在DevEco Studio中运行应用，并打开Log窗口（View > Tool Windows > Log）。
    • 过滤标签为App或JS的日志，白屏时通常会有JavaScript异常或错误信息被抛出。这些错误信息是定位问题的直接依据（例如，未定义的变量、不支持的API调用、模块加载失败等）。

  3. 审查业务界面代码的Vue 3兼容性：

    • 生命周期钩子：将beforeCreate和created替换为setup。beforeMount、mounted等钩子名称不变，但需在setup中通过onBeforeMount、onMounted等函数注册。
    • 响应式API：将data()函数返回的对象，改为在setup中使用ref或reactive声明。将computed和watch改为从vue导入的computed和watch函数。
    • 模板语法：检查是否使用了Vue 3中已移除或更改的语法，如filter过滤器（应改用计算属性或方法）。
    • 第三方库：确认所有使用的第三方UI库或工具库是否明确支持Vue 3。许多Vue 2库在Vue 3中需要安装对应的兼容版本或替代库。

  4. 简化与隔离测试：

    • 创建一个全新的、最简单的页面（例如只包含一个文本组件），在鸿蒙模拟器上测试是否能正常渲染。这可以验证基础环境。
    • 逐步将业务界面中的复杂逻辑（如网络请求、状态管理、复杂组件）添加到这个简单页面中，每添加一部分就测试一次，从而定位到引起白屏的具体代码段。

  5. 关注UniApp特定API与组件：

    • 查阅UniApp官方文档中关于HarmonyOS Next平台差异的说明。一些API（如部分设备接口、路由方式）在HarmonyOS Next上可能有不同的实现或限制。
    • 检查白屏界面是否使用了可能不被HarmonyOS Next完全支持的UniApp内置组件或扩展组件。

总结： 当前最优先的行动是按照Vue 3的语法彻底重构Vuex的创建和使用方式，并仔细查看DevEco Studio的Log输出以获取具体的错误堆栈。白屏通常是运行时错误导致的，日志是解决问题的关键。在完成Vuex升级后，如果问题依旧，再按照上述步骤对业务代码进行逐项兼容性审查和隔离测试。

回到顶部