1. 我为什么选择用uni-app开发鸿蒙Next应用

先说说背景。我本身是个偏前端的开发者，主要技术栈是Vue和微信小程序，对于鸿蒙Next原生开发（ArkTS + ArkUI）了解得不算深。但鸿蒙Next这波势头确实猛，从应用市场到用户心智都在快速起量，谁不想把自己的产品放到鸿蒙生态里分一杯羹？可问题来了——如果按照常规路径，老老实实学一遍ArkTS，再从头写一遍界面逻辑，周期至少两三个月起步，对于个人开发者或者小团队来说，这个时间成本是真的扛不住。

这时候uni-app就成了一个很实际的备选方案。uni-app本身就是一套代码多端发布，之前我做过小程序和App，代码里已经有了完整的业务逻辑和页面结构。鸿蒙Next发布之后，uni-app官方也很快跟进，在HBuilderX 3.98+版本里加入了鸿蒙Next的编译支持，这意味着我只需要把已有的uni-app工程稍作调整，就能直接产出鸿蒙Next的应用包（HAP格式）。

当然，这里要讲清楚一个核心事实：

uni-app编译到鸿蒙Next，并不是WebView套壳

。它走的是“编译到鸿蒙原生”的路线——具体来说，uni-app的静态模板、样式和逻辑部分会被转换为鸿蒙ArkTS的UI组件和页面结构，最终产物是鸿蒙的ArkUI组件树加上业务逻辑的TypeScript代码。这一点非常关键，因为如果只是用WebView把H5包进去，性能和体验都会差很多，鸿蒙商店审核也很难通过。

所以这篇文章的定位很清晰：我会从零开始，把你需要做的所有事情串起来——装好HBuilderX和鸿蒙开发环境、创建uni-app工程、理解入口文件与生命周期、处理鸿蒙Next特有的适配问题、最后打出HAP包并上架应用市场。整个过程我会穿插我自己踩过的坑，尽量让你少走弯路。

适合谁来读？如果你是uni-app老手但没接触过鸿蒙Next，或者你是个前端小白想快速拥抱鸿蒙生态，这篇文章都值得你花十几分钟过一遍。我默认你有基本的JavaScript和Vue语法基础，但不要求你有任何鸿蒙原生经验。

2. 开发环境准备：从HBuilderX到鸿蒙SDK

2.1 HBuilderX版本与下载注意

uni-app开发鸿蒙Next的第一步，就是把你的HBuilderX升级到支持鸿蒙编译的版本。以我写这篇文章的时间点为例，

HBuilderX 4.0以上版本对鸿蒙Next的支持已经比较完善

，4.6版本时甚至已经把鸿蒙的配置项整合到了常规App项目的manifest可视化界面中。

安装的时候有一个容易被忽略的细节：HBuilderX是绿色软件，解压后直接打开就能用，但它依赖Java运行环境来做某些编译任务。如果你电脑上没装过JDK，我建议装一个JDK 17（网上有现成的安装包），否则后面构建时可能会报一些奇怪的错误。装好之后可以在命令行里输入

java -version

确认一下，能正常输出版本号，就说明环境OK。

另外，如果你是Mac用户，注意选择对应的芯片版本——Apple Silicon（M1/M2/M3）和Intel版本是不同的安装包，选错了HBuilderX打开会有明显的卡顿，或直接无法启动。

2.2 鸿蒙Next SDK与DevEco Studio的关系

这一步很多小白会困惑：我到底要不要安装DevEco Studio？答案是：

做uni-app的鸿蒙Next打包，你不用写ArkTS代码，但必须装DevEco Studio来拿到鸿蒙SDK和真机调试工具链

。原因是uni-app编译到鸿蒙之后，仍需要调用鸿蒙官方的编译工具把工程打包成HAP文件，而这些工具集成在DevEco Studio的SDK里。

安装过程中它会引导你下载HarmonyOS SDK，这个SDK体积比较大，大概有几个GB，需要耐心等一会儿。安装完DevEco Studio后，先用它创建一个空的HarmonyOS工程，确认模拟器或真机连接正常，再关掉它——这个步骤是为了验证你的电脑能正常编译鸿蒙工程，后面uni-app打包出问题时可用来排查是不是SDK坏掉了。

关于SDK的版本，我建议你直接用DevEco Studio默认推荐的Previewer版本，不用刻意去追求Beta版或最新测试版。测试版可能有一些新特性，但对uni-app这种间接编译场景来说，稳定才是第一位。

2.3 本地调试工具链：hdc与设备连接

鸿蒙真机调试其实非常依赖一个叫做hdc的命令行工具（HarmonyOS Device Connector），它类似于Android的adb。这个工具一般位于DevEco Studio的SDK目录下，路径类似于：

/Applications/[地址已省略]

我强烈建议你把这个hdc的目录加到系统的PATH环境变量里。为什么要这样做？因为uni-app在HBuilderX中运行到鸿蒙真机时，需要自动调用hdc来安装HAP包、启动应用，如果它找不到hdc，就会报一个“设备连接失败”的错误，让你误以为是手机驱动没装好。

真机连接方面，你需要先在鸿蒙手机上开启“开发者模式”，具体路径是：设置 → 关于本机 → 连续点击版本号7次，然后回到设置 → 系统与更新 → 开发人员选项，打开USB调试。之后用USB线连接电脑，手机上会弹出授权窗口，点击允许即可。如果连接后hdc检测不到设备，大概率是驱动问题，Windows电脑去装一下华为手机助手可以解决大部分驱动兼容问题。

3. 项目创建与工程结构拆解：入口文件到底是怎么回事

3.1 创建uni-app鸿蒙工程的具体步骤

打开HBuilderX，点击文件 → 新建 → 项目，选择“uni-app”模板。这里要注意，创建项目时有一个“选择模板”的地方，很多小白直接选了默认模板，然后跑鸿蒙发现各种报错，其实鸿蒙Next要求项目使用Vue 3版本，不能是Vue 2。所以创建时要勾选“默认模板（Vue 3）”，如果你的项目已经存在且是Vue 2写的，那最好先升级到Vue 3再做鸿蒙编译，这个后面会详细说。

项目创建好之后，打开manifest.json，在“基础配置”的“AppID”那里，如果你不打算使用uni-cloud的云服务，可以暂时不填；但在“App模块配置”中，需要确保你需要的原生模块已勾选。最关键的一步在“鸿蒙Next配置”或“鸿蒙配置”标签页——不同版本的HBuilderX名称略有不同，里面会有包名、版本号、证书指纹等配置项。

写清楚了：

鸿蒙包的包名是独立于Android包名的

，一般建议采用反向域名格式，比如

com.example.myapp

。这个包名一旦上架后基本上不能改，所以前期一定要想好，别随便写一个占位符进去。

3.2 三个核心入口文件：main.js、App.vue、pages.json

接着我们看一下工程根目录下的三个关键文件，理解了它们，你就理解了整个uni-app应用的启动逻辑。

首先是

main.js

，它是整个应用最底层的入口。在这里你会看到：

import App from './App'
import { createSSRApp } from 'vue'

export function createApp() {
  const app = createSSRApp(App)
  return {
    app
  }
}

这段代码是uni-app Vue 3的固定写法，注意

createSSRApp

这个名字，虽然带了SSR字样，但它并不是真的做服务端渲染，而是uni-app为了兼容跨端平台封装的一个入口工厂函数。你不需要改动这段代码，只需要知道应用启动时，会先执行这里，然后加载App实例。

然后是

App.vue

，它是整个应用的根组件。但它跟小程序的app.json有一些区别——它不负责配置页面路径，而是负责应用的生命周期和全局样式。常用的

onLaunch

全局样式写在

<style>

里，注意这里写的样式对所有页面生效，但优先级比较低，页面内的样式可以覆盖。

最后是

pages.json

，这才是决定"这个应用有哪些页面、第一个页面是谁"的核心配置。例如：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "我的应用",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  }
}

pages数组里第一项就是启动页（homePage）。如果你发现自己运行鸿蒙应用后打开的不是想要的页面，优先检查这里。鸿蒙Next对页面路由的处理逻辑和微信小程序基本相同，uni-app会在编译时将其转换为鸿蒙的页面路由表。

3.3 组件与静态资源的存放约定

除了这三个文件，还有一个容易被忽略的点：

components

目录、

static

目录和

pages

目录的约定。pages目录下每创建一个

.vue

文件，都要记得在pages.json中注册路径，否则编译到鸿蒙后界面会白屏，或提示找不到页面。static目录下的资源会被原样拷贝到鸿蒙工程，所以图片、字体等静态文件放在这里比较合适；但如果涉及条件编译区分平台的资源，则需要放到特定平台目录下。

对于组件的引用，我建议使用easycom规则，也就是组件放在components/组件名/组件名.vue这样的目录结构下，然后在pages.json里开启easycom自动扫描导入，这样页面里直接写组件标签就能用，不需要手动import再注册。这个功能对于小程序和鸿蒙编译都很友好，能少写不少样板代码。

4. 从零开发业务功能：一个实战小应用的完整拆解

4.1 搭一个简单的首页：列表加载与下拉刷新

纸上谈兵没意思，我们直接上手写一个"新闻资讯类"的首页，包含列表加载、下拉刷新和详情页跳转，这几个能力几乎是所有内容类应用的标配。

第一步，在pages.json里注册两个页面：

pages/index/index

作为首页，

pages/detail/detail

作为详情页。然后在首页的

.vue

文件中，用

<scroll-view>

或页面自带的滚动实现列表，用

<view>

和

<text>

渲染每条数据。因为鸿蒙Next不支持某些小程序专用的组件，我建议列表直接用

<view>

循环渲染，别用

<list>

这类原生组件，跨端兼容性会更好。

列表渲染的代码大致是这样的：

<template>
  <view class="list-container">
    <view class="list-item" v-for="(item, index) in newsList" :key="item.id" @click="goDetail(item)">
      <text class="list-title">{{ item.title }}</text>
      <text class="list-date">{{ item.publishTime }}</text>
    </view>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const newsList = ref([])

const loadData = () => {
  // 模拟接口请求
  setTimeout(() => {
    newsList.value = [
      { id: 1, title: '鸿蒙Next开发入门指南', publishTime: '2025-01-10' },
      { id: 2, title: 'uni-app跨端实践总结', publishTime: '2025-01-12' }
    ]
  }, 300)
}

const goDetail = (item) => {
  uni.navigateTo({
    url: `/pages/detail/detail?id=${item.id}`
  })
}

loadData()
</script>

这里有一个很关键的经验：在多端编译中，尽量避免使用“只在某一端生效”的 API。例如，

uni.createSelectorQuery()

在鸿蒙上的返回值结构与小程序端略有差异，如果你要用它来获取元素高度，建议先做条件编译，或者在真机上验证。

4.2 页面跳转与参数传递的正确姿势

页面跳转是应用中最基本、也最容易出问题的环节。uni-app 提供了

uni.navigateTo

、

uni.redirectTo

、

uni.switchTab

等API，鸿蒙编译后会被映射到鸿蒙的路由管理。参数传递我建议用路径拼接的方式，因为query参数是最稳定可靠的，跨端都不会丢。

一个常见的坑是：

uni.navigateTo

跳转后，在新页面里通过

onLoad(options)

接收参数，但如果参数里有中文或特殊字符，一定要先

encodeURIComponent

编码，否则在鸿蒙上会偶尔出现乱码。我之前一次开发中，因为直接把用户昵称拼在url里，结果在鸿蒙上出现了参数截断的bug，排查了半天，最后才发现是没做编码。

如果你需要传递比较复杂的对象，比如一个包含多层嵌套的JSON结构，有两种选择：要么放在全局store（比如Vuex/Pinia）里通过状态管理获取；要么用

uni.setStorageSync

暂存，到目标页面再读取。我个人偏好用Pinia做全局状态，因为这样刷新页面数据也不会丢，而storage需要在页面栈中小心清理，容易埋坑。

4.3 状态管理：从Vuex到Pinia的推荐方案

提到状态管理，uni-app Vue 3项目我更推荐用Pinia而不是Vuex，原因是它的API更简洁，类型提示也更好，而且和Vue 3的响应式系统结合得更紧密。在鸿蒙Next的uni-app工程中，Pinia是经过官方测试可用的，但有一个细节要注意：

不要使用Pinia的setup store写法，尽量使用options store写法。

为什么？因为setup store依赖组合式API的工厂函数执行上下文，在部分平台编译时会出现初始化顺序问题，导致

getCurrentInstance

报错。而options store就是传统的

defineStore('id', { state, actions })

写法，跨端兼容性最好。这是我实际在鸿蒙Next上踩到的坑：项目第一次用setup store写登录状态，在App平台和小程序上都正常，唯独鸿蒙上偶尔报"Pinia state is not initialized"，改回options store后问题消失。

Pinia的引入也不复杂，在main.js里加两行：

import { createPinia } from 'pinia'
app.use(createPinia())

然后在页面里：

import { useUserStore } from '@/stores/user'

const userStore = useUserStore()

4.4 网络请求封装：uni.request的鸿蒙适配

网络请求是应用的命脉。uni-app中

uni.request

是跨端统一的网络API，但到了鸿蒙Next上，它的底层会被替换为鸿蒙的

@ohos.net.http

模块。绝大多数情况下你不需要改业务代码，但有三个点需要特别注意。

第一是请求头的

Content-Type

，如果服务端是常见的SpringBoot或Node后端，默认用

application/json

没问题；但如果你的后端是PHP或部分老系统，对charset要求比较严格，鸿蒙端可能不会自动补

charset=utf-8

，这时要在请求头里显式带上。

第二是HTTPS证书问题。鸿蒙Next对证书校验比较严格，如果你的后端没有配置有效的SSL证书（比如还在用自签名证书测试），开发阶段会直接请求失败，连错误提示都不明显。如果你遇到所谓“网络不给力”或直接无响应的bug，优先查证书链是否完整。

第三是超时时间。鸿蒙端的默认超时时间比小程序端短一些，如果业务上有慢接口，建议在配置里显式设置

timeout: 10000

之类的值，避免用户遇到奇怪的超时现象。

建议把你的请求过程封装成一个request.js，统一处理baseURL、token注入、错误提示和超时重试。这不仅仅是代码整洁的问题，更因为鸿蒙编译后的错误堆栈信息不如浏览器直观，统一封装能帮你把日志打在一个可控的出口，出问题时定位更快。

5. 鸿蒙Next适配：从UI到原生能力的那些差异

5.1 状态栏与安全区域的处理

提到多端适配，第一个绕不开的就是状态栏和刘海屏安全区域。鸿蒙Next的状态栏高度、导航栏样式跟其他平台不完全一样，如果你在小程序上用过

custom-navigation-bar

这类自定义导航栏，到了鸿蒙上会有一些惊喜和惊吓。

我的经验是：

优先使用uni-app的pages.json里的原生导航栏配置

，也就是不自定义导航栏，让系统来处理返回按钮和右上角菜单。这样最简单也最稳定。如果你追求视觉效果必须自定义导航栏（比如透明渐变那种），那就要用

uni.getSystemInfoSync()

获取

statusBarHeight

和

safeAreaInsets

，在页面顶部预留对应高度的占位 view。

有一个坑值得单独说：

uni.getSystemInfoSync()

在鸿蒙 Next 上返回的

safeAreaInsets

字段形态与 iOS 端几乎一致，但

screenHeight

可能不含状态栏，如果你要算列表滚动区域的高度，建议用

uni.createSelectorQuery()

获取容器的实际高度，而不是自己用屏幕高度减去各种高度来计算——我在实际项目中就是在这一步算错，导致鸿蒙上底部有一段内容被手势条遮住。

5.2 原生能力调用：相机、定位与权限

如果你的应用需要调用相机、相册、定位这些原生能力，先别高兴太早。鸿蒙 Next 是一个全新的系统，权限模型跟 Android 和 iOS 都不一样。虽然 uni-app 把这些封装成了

uni.chooseImage

、

uni.getLocation

等统一 API，但在鸿蒙上，你必须在 manifest.json 的“鸿蒙配置”中声明对应的权限，否则即使代码没报错，功能也是静默失败。

例如，调起相机拍照，你需要配置：

"permissions": {
  "ohos.permission.CAMERA": {
    "reason": "用于拍摄并上传头像",
    "when": "inuse"
  }
}

注意这个

reason

字段在鸿蒙商店审核时会被展示给用户，所以一定要写清楚用途，写得太模糊有被打回的风险。另一个需要注意的点：

uni.getLocation

在鸿蒙 Next 上返回的坐标系是 GCJ-02（火星坐标系），这一点跟国内 Android 平台一致，但如果你在高德地图或百度地图上展示坐标，需要根据地图 SDK 的要求做坐标偏移转换，否则标记点会偏移几十到几百米。

5.3 条件编译：一套代码里的平台分支

uni-app 最强大的地方之一是条件编译。你可以用注释的方式，让某段代码只在特定平台编译。例如：

// #ifdef APP-HARMONY
console.log('这段代码只在鸿蒙Next上执行')
// #endif

<!-- #ifdef APP-HARMONY -->
<view class="harmony-only">鸿蒙专用UI</view>
<!-- #endif -->

我的建议是：在项目初期就梳理一下哪些功能在鸿蒙上表现不同，并用条件编译把差异点隔离出来。比如上面提到的安全区域、权限声明、某些原生组件的对齐方式，都可以通过这种方式做分平台处理。尽量不要为了省事写一堆重复的运行时代码去做平台判断，因为运行时的

uni.getSystemInfoSync().platform === 'harmony'

判断越多，你的代码就越乱，而且跨端切换时容易漏改。

6. 真机调试与打包上架：从HAP到应用市场的最后一公里

6.1 HBuilderX运行到鸿蒙真机的完整流程

在开发阶段，你肯定想快速在真机上看到效果。HBuilderX提供了一个"运行 → 运行到手机或模拟器 → 运行到鸿蒙Next"，点完之后HBuilderX会自动编译代码并把HAP安装到手机。这里有两个前置条件很容易被忽略。

第一，ReactNative/Flutter那套逻辑不要搬过来，

鸿蒙运行必须先用DevEco Studio打开过一次鸿蒙工程

，目的是触发SDK初始化。这个概念有点绕，但你可以理解为：HBuilderX只是一个代码生成器和编译器，它把uniapp代码转成鸿蒙工程后，还需要调用DevEco Studio的SDK环境来做最终的HAP打包。如果SDK没初始化，HBuilderX会报错说找不到鸿蒙编译工具链。

第二，HBuilderX运行到鸿蒙的模式有两种：一种是“自动生成鸿蒙工程并运行”，另一种是“使用已有鸿蒙工程”。我推荐你使用后者——先在HBuilderX中生成鸿蒙工程（运行时会自动生成到

unpackage/dist/build/app-harmony

目录），然后用DevEco Studio打开这个工程，等DevEco Studio完成一次同步。接下来回到HBuilderX，在运行菜单中选择已有鸿蒙工程，这样可以避免每次改动代码都重新生成工程，导致首次编译缓慢。

真机连接后，手机上可能会有“是否允许安装HAP？”的弹窗，一定要点允许。如果你在开发者选项中开启了“仅通过hdc安装应用”，HBuilderX调用hdc安装时一般没问题；但如果开启方式是“仅WLAN调试”，USB安装可能失败，最好保持默认的USB调试模式。

6.2 生成签名证书：Profile与.cer文件

上架之前，你必须给应用签名。鸿蒙应用签名的过程跟Android的keystore不一样，它需要从华为开发者联盟申请证书。登录Agro（华为开发者联盟）后，在“证书管理”页面可以创建发布证书，它会引导你生成一个CSR文件，然后用生成的

.cer

文件、

Profile

文件和密钥库

.p12

文件完成签名配置。

对于个人开发者来说，通常你会有一个

.p12

密钥库文件，生成时一定要设置好密码，并且妥善保存，因为密钥库一旦丢失，就意味着你无法对后续版本做签名升级，上架过的应用也拿不回来。

在HBuilderX的manifest.json中，“鸿蒙Next配置”里需要填上这些文件的路径或内容，我建议直接把

.p12

和

.cer

及

.profile

放在工程目录下一个名为

harmony-cert

的文件夹里（不要上传到代码仓库，可以加到.gitignore里）。签名配置完毕后，再执行“发行 → 原生App-云打包”，选择鸿蒙Next平台，等待云端构建完成。

这里要说一下，

若你没有开通云打包的套餐，本地打包鸿蒙也是可行的

，但步骤稍微繁琐。HBuilderX菜单栏“发行 → 原生App-本地打包 → 生成鸿蒙资源”，会生成一个鸿蒙工程，然后在DevEco Studio里打开，配置好签名，直接Build → Build App Bundle(s) → Build HAP，就能在工程的

build

目录下看到HAP文件。这个过程可以精确控制打包细节，但要求你对DevEco Studio比较熟悉，适合有一定经验的开发者。

6.3 上架华为应用市场的审核资料

拿到HAP文件并不是终点，上架应用市场才是真正的“上线”。华为应用市场的开发者控制台网址是AppGallery Connect（AGC），提交应用时你需要在里面填写大量信息，包括应用名称、简介、截图、隐私政策链接等。这个过程比较繁琐，我提几个容易踩坑的点。

首先，应用名称要在2到20个汉字之间，且不能包含“测试”、“demo”这类词汇。截图要求是鸿蒙真机截图，且尺寸必须满足要求（至少一种分辨率的截图），如果你开发阶段直接用模拟器截图，分辨率往往不达标，建议直接用真机截图。其次，隐私政策必须能正常访问，如果只是写了一个本地文本而没有部署到公网，审核会被打回。

另外，鸿蒙商店对上架应用的权限申请审核很严格，尤其是读取通讯录、定位、相机等敏感权限。在AGC提交页面你声明的权限必须和代码里实际调用的完全一致，多声明或少声明都会导致审核被拒。有时候你只是加了一个第三方SDK，它内部申请了某个权限，而你没有在后台声明，一样会被拒。所以前期尽量精简依赖库，所有权限需求都要了如指掌。

审核周期一般是1到3个工作日，新应用首次提交可能长一些。如果被打回，页面会给出明确原因，按原因修改后重新提交即可。这里我特别提醒：

不要通过打回原因去猜测政策意图，照着字面意思改

。比如它说“截图不清晰”，那就重新截图，不要去想“是不是功能有问题”，因为你猜方向很容易改错。

6.4 迭代升级：版本号管理与热更新方案

应用上架后，开发并不会就此停止。版本更新方面，你的HAP版本号在manifest.json中设置，另外还有一个versionCode（整型）和versionName（字符串）。鸿蒙应用市场会根据versionCode判断新旧版本，versionCode只能增加不能回退。所以建议你把versionCode设置得冗余一点，比如初始版本写成100，避免第二版急于改成101，结果第三个版本号改得太小或跟线上出现冲突。

如果你的应用有比较频繁的内容更新，我推荐做一套热更新方案。uni-app支持App资源热更新，核心思路是：在应用启动时请求你的服务器接口，比较每次包发布的版本号，发现新版本后把新的wgt资源包下载下来，然后调用

uni.openAppAuthorizeSetting

或应用内部的重启逻辑完成更新。不过这套方案在鸿蒙Next上目前还没有完全支持，至少在写这篇文章时，HBuilderX的“应用资源热更新”仍主要面向Android和iOS，所以鸿蒙端建议先老老实实走应用市场整包更新。

但从产品体验角度，即使只走整包更新，也可以做一个“版本更新引导弹窗”——调用服务端接口获取最新版本号，如果不是最新版就提示用户去应用市场更新。这个逻辑用uniapp写起来不复杂，也能避免用户集中在旧版本上产生大量反馈问题。

7. 常见问题与排查技巧实录：这些坑我替你踩过了

7.1 编译报错“Cannot find module '@ohos/hypium'”

这个错误在小白圈里出现频率极高。原因是HBuilderX生成的鸿蒙工程会依赖一些鸿蒙测试框架的模块，当你本地没有缓存这些依赖时，编译就会失败。解决办法是先用DevEco Studio打开一次生成的工程，让DevEco Studio自动下载依赖。大部分情况下，这一步做完，编译报错就能消失。

如果打开DevEco Studio后还报这个错，可能是你的网络无法访问华为的远程仓库，需要配置DevEco Studio的镜像仓库或代理（这里不展开说代理问题，总之换成华为官方引导的配置即可）。另外，不要手动去工程的oh-package.json5里删除

@ohos/hypium

依赖，因为后续编译测试还会用到。

7.2 真机运行白屏：检查App.vue里的onLaunch异步逻辑

我在开发初期遇到过一个诡异的问题：应用在鸿蒙模拟器上运行正常，但真机安装后白屏，控制台也没有明显报错。排查了很久才发现原因——我在App.vue的

onLaunch

里做了同步的本地存储读取，如果读取的那个key不存在，代码抛出异常中断了Page的初始化。

这个问题的教训是：

鸿蒙真机的异常恢复机制跟Android和iOS不太一样，某些异常不会直接弹错，而是导致页面渲染失败

。所以，如果你在鸿蒙上遇到白屏，先检查App.vue里的初始化逻辑是否足够健壮，把这些逻辑都包到try-catch里，或者延迟到首页的onLoad中执行。同样的教训也适用于全局引用的第三方库，如果某个库在鸿蒙上访问了不存在的API，有时候不报错但页面已经卡住不动了。

7.3 uni.request在鸿蒙上偶发超时：复用连接与DNS缓存

鸿蒙Next的网络请求库和Android的OkHttp在连接管理机制上不太一样，如果你在业务代码中高频创建短连接请求，比如每秒钟轮询一次，容易出现偶发性的请求超时，错误码是

201

或

-1

我排查过这个问题，最终的结论是：尽量不要用

setInterval

去掉高频轮询接口，如果确实有轮询需求，把间隔拉大到3秒以上，并开启请求的

keepAlive

。在uni.request中，鸿蒙编译环境下可以通过自定义请求头

Connection: keep-alive

来复用连接。另外，如果你的域名解析本身不稳定，可以考虑在请求失败时做一次

uni.getNetworkType()

检查，或者直接做一次失败重试，能明显提升成功率。

7.4 权限弹窗无法弹出：确认是否已在AGC声明

不少人在真机上调试时发现，明明代码里调用了

uni.authorize

，但鸿蒙系统就是不弹授权框。这个问题通常不是代码问题，而是你的应用没有在AGC后台声明对应的权限。在调试阶段，虽然打包时HBuilderX会调用本地的权限配置，但鸿蒙系统的权限管控策略是“双重校验”的——既查应用声明，又查AGC侧配置。所以如果你已经配置了manifest，还是弹不出弹窗，去AGC把权限重新声明一次，等待10分钟让配置生效，再重新打包安装。

这里还有一个细节：鸿蒙对某些权限做了“分组”处理，比如定位权限，首次弹窗后，即使用户同意，也只能使用模糊定位（大约几公里范围），精确位置还必须额外申请“精确位置”权限。这在测试时要特别注意，别把模糊定位当成Bug上报。

7.5 打包成功但商店审核被拒：常见驳回原因对照

最后整理一下我见过的典型审核驳回原因，做成速查思路：

驳回理由 | 常见原因 | 对策 |

应用名称与功能不符 | 名称带了地域或违禁词 | 改一个描述性、中立的应用名 |

隐私政策无法访问 | 链接是HTTP或者页面被墙 | 换成HTTPS可访问的地址 |

截图中出现非应用内容 | 截图里有测试数据、模拟器状态栏 | 用真机、真实数据重新截图 |

权限声明与应用行为不一致 | 代码里调用某权限但后台没声明 | 完善AGC权限声明并提交 |

页面内容为空 | 首页数据依赖后端但审核环境没数据 | 增加空态页或默认展示内容 |

单独说一下“页面内容为空”这个坑，很多个人开发者在审核时使用的是自己的后端接口，如果审核人员网络环境访问不了你的接口，或者你的服务凌晨因维护宕机，审核打开就是一片空白。所以上线前一定要在应用里加一个“空态兜底”——数据请求失败时展示一个带缓存的默认列表或者友好的文案，这不只是为了过审，也是用户体验的基本功。

8. 经验总结与建议：这套流程能给你的项目带来什么

走到这里，从HBuilderX安装到真机调试，再到HAP打包和上架审核的核心链路已经梳理完了。回看整个开发过程，我个人最深的体会是：

用uni-app开发鸿蒙Next，真正的难点不在于写业务代码，而在于理解各层工具链之间的关系

。HBuilderX负责把你的Vue代码转成鸿蒙工程，DevEco Studio负责把鸿蒙工程编译成HAP，AGC负责审核分发——每一层都有各自的规则和坑，把这条链路跑通一次，比看十篇教程都有用。

如果你正准备启动自己的鸿蒙项目，我有几条比较实在的建议：

第一，不要一上来就追求功能丰富，先做一个只有首页、列表、详情三个页面的最小原型，完整跑通“真机运行 — 打包 — 上架”全流程，再往里加功能。因为无论你在哪里看到的问题，都不如真机上的一个报错来得真实。

第二，重视权限和隐私合规，从第一行代码开始就做好记录，哪些权限、哪些SDK、哪些用户数据——这些鸿蒙商店审核都会追问。与其上线前补材料，不如开发时就顺手整理，能省下大量时间。

第三，留意uni-app和HBuilderX的版本更新节奏，鸿蒙Next的适配一直在快速迭代，很多早期版本的问题可能在新版本中已经修复。如果你遇到了奇怪的编译bug，先去官方社区或更新日志里搜一下，往往比你自己折腾半天更高效。

最后，我再分享一个小技巧：在鸿蒙工程里加一行日志，就能大幅提升排错效率。HBuilderX生成的鸿蒙工程中，找到

entry/src/main/ets/entryability/EntryAbility.ets

，在

onWindowStageCreate

方法里主动打一条日志，这样每次应用启动时你都能在日志窗口中看到一条清晰的启动标记。后续页面卡死或者白屏时，通过这条日志能快速判断是“应用没启动”还是“页面渲染出问题”——这么一个小操作，能帮你省下无数个排查到半夜的时间。