从空目录到跑在模拟器上:我搭了一个最小鸿蒙工程,踩了两个坑

一、为什么要自己搭一个

我手头有个真实的鸿蒙项目,功能挺全,分布式同步、麦克风权限、卡片都有。但每次想验证一个很基础的问题——“这个构建流程到底能不能跑通”——都会被它庞大的工程结构拖住:几十个 ets 文件,一堆资源,编译一次心里没底。

所以我决定另起一个:一个最小工程,一个页面,一个按钮,只验证三件事——能不能编译、能不能装上、能不能看到界面。名字就叫 harmony-demo。

后来发现,这个"最小"决定是对的。因为问题恰恰都出在最小的地方。

二、模板从哪来

我没有手写整个工程结构。手写 AppScope/app.json5、module.json5、hvigorfile.ts、资源目录这一套,一步写错就是一个编译错误,而且错在哪很不直观。

DevEco 里其实自带一个最小工程模板,路径是:

/Applications/DevEco-Studio.app/Contents/plugins/codegenie-plugin/previewProjectTemplate

一共 37 个文件,结构完整:AppScope(应用级配置和图标)、entry(一个模块)、hvigor(构建配置)、resources(字符串、颜色、媒体)、还有 test 和 ohosTest 两个测试目录。

直接 ditto 一份出来,改改包名就能用。这比我凭印象抄结构靠谱得多——官方模板本身就是"能编译"的基准。

顺便说一句,这套模板原本是给预览器用的,所以它带一份 phoneSettingConfig_Phone.json,里面写着预览器的分辨率和设备类型:

"Resolution": { "args": { "Resolution": "360*780" } },
"DeviceType":  { "args": { "DeviceType": "phone" } }

这个文件我一开始顺手删了,后来发现它其实解释了"预览器为什么不需要设备也能渲染"——它就是一份虚拟设备的描述。删了不影响构建,但留着更有信息量。

三、工程结构里我特意看了几个目录

复制完模板,我没有急着改代码,先把几个"非源码"目录看了一遍。事后证明这一步挺值。

.hvigor/ 是构建缓存,里面有个 cache/project-config.json,记录了上一次构建用的 SDK 路径:

"sdkPath": "/Applications/DevEco-Studio.app/Contents/sdk"

这条信息在第五节的构建里帮了大忙——我机器上有两套 DevEco(26.0.0 和 6.1.1),光看版本号猜不出该用哪套,看这个文件就一目了然。它也解释了为什么我一直用 /Applications/DevEco-Studio.app 而不是版本号更"新"的那个文件夹。

oh_modules/ 是依赖目录,等价于 npm 的 node_modules。模板里没有外部依赖,所以它是空的。以后加了 @ohos/* 的包,这个目录会膨胀,记得别提交到 Git。

code-linter.json5 是静态检查规则,默认配置挺宽松。我没改它,但留了个心:等代码多了再收紧,一开始就开严格规则,会被一堆风格警告淹没。

AppScope/app.json5 是应用级配置,改了两个地方:bundleName 改成 com.example.demoapp,label 保持引用字符串资源。bundleName 很关键,后面 hdc install、aa start、签名 profile 全都认这个值,一旦改了就要重新签名。

entry/src/main/module.json5 里的 deviceTypes 是 ["phone", "tablet", "2in1", "wearable"]——官方模板默认就给了四个设备类型,这点比我预想的大方。不过我没动它,先保证单设备能跑通,跨端的事留到后面。

四、第一处必改:SDK 版本对不上

模板默认写的是 API 12:

"compatibleSdkVersion": "5.0.0(12)",
"targetSdkVersion": "5.0.0(12)"

我这台机器上装的是 DevEco 26.0.0(SDK API 26)和 DevEco 6.1.1(SDK API 24),没有 API 12。不改就会在编译阶段直接失败。

于是改成:

"compileSdkVersion": "26.0.0",
"compatibleSdkVersion": "6.1.1(24)",
"targetSdkVersion": "26.0.0"

这里有个容易忽略的细节:compileSdkVersion(用哪个 SDK 编译)和 compatibleSdkVersion(最低能跑在什么系统上)是两回事。前者决定你能不能用到新 API,后者决定安装时的门槛。我图省事,把兼容版本设成 6.1.1(24),这样 API 26 编出来的包在更低一点的系统上也能装。

另外模板里有一行 "signingConfig": "default",我没有对应证书,删掉,否则 hvigor 会去找一个不存在的签名配置。

五、页面:一个能看出状态变化的计数器

模板自带的页面是 Hello World,点一下文字会变。这种页面看不出状态到底有没有更新,所以我换成了一个计数器:

@Entry
@Component
struct Index {
  @State count: number = 0;
  @State items: string[] = ['HarmonyOS', 'ArkTS', 'CodeArts Agent'];

  build() {
    Column({ space: 14 }) {
      Text('Hello HarmonyOS')
        .fontSize(30).fontWeight(FontWeight.Bold).fontColor('#1A73E8')
      Text(`点击次数:${this.count}`).fontSize(20)
      Button('点我 +1').width(160).height(44)
        .onClick(() => { this.count += 1; })
      ForEach(this.items, (item: string) => {
        Text(item).fontSize(16).fontColor('#666666')
      }, (item: string) => item)
    }
    .width('100%').height('100%').justifyContent(FlexAlign.Center)
  }
}

选计数器的原因是:它同时验证了三件事——@State 能不能触发刷新、Button 的点击回调有没有生效、ForEach 的 keyGenerator 写得对不对。如果界面静止不动,那说明状态机制根本没起来,一眼就能看出来。

六、构建:三条环境变量比命令本身更重要

我没有在 IDE 里点按钮,而是直接命令行跑,因为想把"到底依赖什么"搞清楚。

NODE_HOME=/Applications/DevEco-Studio.app/Contents/tools/node \
DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  --mode module -p product=default -p module=entry@default \
  -p buildMode=debug assembleHap --no-daemon

第一次跑的时候我只写了 hvigorw 的路径,结果报 NODE_HOME is not set and not 'node' command found in your path。看了 hvigorw 这个脚本本身才明白:它是个 bash 包装,里面先找 NODE_HOME,找不到就退化成 node,而 node 走的是系统 PATH——我这台机器的 node 是 nvm 装的 v24,跟 DevEco 自带的不是一回事。

所以正确的姿势是显式指定 DevEco 自带的 node。DEVECO_SDK_HOME 同理,不指定的话它会去猜 SDK 位置。

跑通之后输出是这样:

在这里插入图片描述

三个数字值得记一下:CompileArkTS 用了 2 秒多,PackageHap 0.4 秒左右,整体 4.5 秒。33 个任务里 20 个执行、13 个命中缓存——这是第二次构建,第一次是 34 个任务全部执行,耗时 4.581 秒。

也就是说:增量构建几乎没有变快。因为真正的耗时集中在那 20 个必须执行的编译任务上,任务调度和缓存只是省了个零头。这个观察后来帮我判断了另一件事——编译速度不是瓶颈,签名和设备才是。

顺便说说这 33 个任务都在干什么。输出里比较有代表性的几条:

ProcessProfile        处理 module.json5 等描述文件
GenerateLoaderJson    生成模块加载表
CompileResource       编译资源(图片、字符串、颜色)
CompileArkTS          把 .ets 编译成字节码
PackageHap            打包成 .hap
SignHap               签名(没配证书时 1ms 就"完成",只打警告)

其中 SignHap 那条最值得注意:它明明跑了,也"Finished",但产物还是 unsigned。因为 signingConfigs 是空数组,它没有证书可用,于是跳过签名、打一条 WARN: No signingConfig found for product default 就结束了。这个行为很容易误导人——看日志你会以为签名阶段没问题,实际上什么都没做。

这也解释了为什么后面安装时要挑文件名:有没有签名,全看产物叫 -signed.hap 还是 -unsigned.hap。

截图里还有一条黄色的 ArkTS 警告:

WARN: ArkTS:WARN File: .../ets/entryability/EntryAbility.ets:9:42
Function may throw exceptions. Special handling is required.

意思是 hilo.info 那一行前面有个可能抛异常的调用,建议显式 try-catch。它不中断构建,但会一直挂在输出里。我一开始以为是噪音,后来发现这类警告在真机上确实会变成问题——比如权限被拒的时候,异常一路冒到 UI 层,表现就是"点了没反应"。

七、124 KB 的包里装了什么

解包看一下,就五个东西:

条目体积作用
module.json1.6 KB模块清单:入口 ability、设备类型、页面路由
ets/modules.abc12.9 KBArkTS 编译产物(字节码)
resources.index1.1 KB资源索引:字符串、颜色、媒体的映射表
resources/base/media/~103 KBbackground / foreground / startIcon 三张图
resources/base/profile/main_pages.json27 B页面清单(路由表)

两件事挺反直觉。一是图标占了八成体积,我这几百行代码编译完只有 12.9 KB——以后要压缩体积,先换图,别在代码上抠。二是最后那个 27 字节的文件,main_pages.json。

就是这个 27 字节的文件,让我白屏了半个小时。

八、设备:一开始是空的

编译成功了,下一步是装。先看有没有设备:

hdc list targets
[Empty]

空空如也。这台机器上装了模拟器的系统镜像(~/Library/Huawei/Sdk/system-image/HarmonyOS-6.1.1/ 下面有 phone_all_arm 和 pc_all_arm),但没有任何已创建的实例。签名材料也不匹配当前包名——~/.ohos/config 里有四套历史证书,绑的分别是 com.example.mo_fang、com.example.flutter_oh_demo、com.huawei.ohos_electron、com.shuming.harmonynotes,没有一个是 com.example.demoapp。

到这一步我本来准备放弃了,转去 DevEco 里配签名。结果在 DevEco 里点开预览器之后,hdc list targets 突然多了一行:

127.0.0.1:5555

查了一下:

hdc -t 127.0.0.1:5555 shell param get const.product.model
emulator
hdc -t 127.0.0.1:5555 shell param get const.product.software.version
emulator 6.1.0.125(SP9DEVC00E120R4P11)

是一台本地模拟器,DevEco 打开预览器的时候把它拉起来了,还自动注册到了 hdc 的设备列表里。

这件事挺有意思:你以为"预览器"只是个渲染面板,其实它背后跑着一台真正的模拟器实例。所以后面我干脆不折腾预览器了,直接把包推到这台模拟器上。

九、装上了,但屏幕是白的

hdc -t 127.0.0.1:5555 install -r entry-default-unsigned.hap
[Info]App install path:.../entry-default-unsigned.hap msg:install bundle successfully.

未签名的包,装成功了。 这点和大多数文档说法不一样,我特意确认了两次,产物文件确实叫 entry-default-unsigned.hap,build-profile.json5 里 signingConfigs 确实是空数组 []。结论是这台模拟器不校验签名——真机不行,但模拟器放行。这条先记下来,后面单独说。

装完之后拉起来:

hdc -t 127.0.0.1:5555 shell aa start -b com.example.demoapp -a EntryAbility
start ability successfully.

start ability successfully,听起来一切正常。然后从设备端截屏:

hdc -t 127.0.0.1:5555 shell snapshot_display -f /data/local/tmp/shot.jpeg
hdc -t 127.0.0.1:5555 file recv /data/local/tmp/shot.jpeg ./emu.jpeg

拿到的画面上,只有状态栏(时间、电量),下面一大片白。

在这里插入图片描述

第一反应是"是不是还没渲染完",等了十几秒再截,还是白。

顺手说两个 snapshot_display 的细节,第一次用容易卡住。

第一,它必须带 -f 参数指定输出路径,且路径要在设备上(比如 /data/local/tmp/)。不带路径直接跑,它会把二进制数据打到标准输出,终端里就是一堆乱码。

第二,文件要 hdc file recv 拉回本地,不能直接 cat。我第一次尝试 hdc shell cat /data/local/tmp/shot.jpeg > local.jpeg,图片能打开,但全是坏像素——因为 shell 的管道会把二进制当文本处理,中间有换行转换。

顺带记一下时间戳:截图里状态栏显示 02:44,是模拟器内部时间,跟本机时间不一致。别拿它当"卡了多久"的依据,判断有没有刷新,看的是页面内容。

十、日志给了答案:ret=1003

鸿蒙的日志工具叫 hilog,可以从设备上直接拉:

hdc -t 127.0.0.1:5555 shell hilog -x | grep -E "demoapp|load content"

关键就两行:

11-18 14:43:33.030 I C04200/JsWindowStage: Window [31, demoapp0] load content end, ret=1003
11-18 14:43:33.041 I C03900/Ace: [(100000:100000:scope)] ArkUi flush first frame messages.

ret=1003。

这条日志的意思是:WindowStage.loadContent() 调用结束了,但返回码不是 0。也就是说 Ability 活得好好的、窗口也创建了、首帧也刷了——只是没有内容可渲染。白屏不是崩溃,是"页面没加载上"。

到这里问题就很清楚了。回看 EntryAbility.ets 里那句:

windowStage.loadContent('pages/Index', (err) => {
  if (err.code) { ... }
});

它要加载 pages/Index。再看路由表 main_pages.json:

{
  "src": [
    "generated/Index"
  ]
}

写的是 generated/Index——这是官方模板自带的那个页面路径(模板里确实有个 ets/generated/Index.ets)。我把页面写到了 ets/pages/Index.ets,但忘了改路由表。

loadContent 是按 main_pages.json 找页面的。路由表里没有 pages/Index,于是返回 1003,窗口一片白。

十一、为什么预览器没暴露这个问题

这是整个排查里最值得说的一点。

我在这之前一直用 DevEco 的预览器看这个页面,它渲染得好好的,按钮点了计数也会变:

在这里插入图片描述

预览器正常,真机白屏。为什么?

因为预览器走的是"直接编译并渲染这个 .ets 文件"的路径,它不需要经过 Ability 的 loadContent,也不需要查 main_pages.json。换句话说:预览器验证的是"这个页面写得对不对",不是"这个应用能不能启动"。

这两件事经常被混为一谈。我自己就混了——看到预览器能跑,就默认应用没问题,直到在模拟器上白屏才发现,真正拦住我的是一个 27 字节的配置文件。

后来我总结了一句话:预览器管页面,模拟器管应用。要验证"能不能装、能不能启动、首屏对不对",必须走模拟器或真机,绕不过去。

十二、改一个字段,然后就好了

修复本身很简单,把路由表改成实际路径:

{
  "src": [
    "pages/Index"
  ]
}

然后重新构建、重新安装、重新拉起:

bash build.sh                    # BUILD SUCCESSFUL in 4 s 674 ms
hdc install -r ...hap            # install bundle successfully
hdc shell aa start -b com.example.demoapp -a EntryAbility

再截屏,界面出来了:

在这里插入图片描述

顺手又拉了一次日志确认:

请添加图片描述

ret=0,NotifyCompleteFirstFrameDrawing 也出现了。同一台设备、同一个包名、同一个未签名 HAP,唯一的差异就是那行路由表。

十三、白屏这件事,不止一种成因

修好之后我复盘了一下"白屏"这个现象。它太笼统了,同样是白屏,原因可能完全不同。按我这次的经验,能分成五类:

第一类,路由表不对。 也就是我遇到的这种。特征是日志里有 load content end, ret=1003,进程不崩、窗口正常、就是没内容。

第二类,module.json5 里 pages 字段丢了。 如果写成 "pages": "$profile:main_pages" 但资源里没有这个 profile 文件,编译可能过得去,运行时会找不到路由表。查法一样:看 hilog 里的加载错误。

第三类,资源缺失。 $string:xxx、$media:xxx 引用了不存在的资源。这类问题编译期通常能发现(资源编译会失败),但如果只在某个分支里用到,可能编译过了、运行时才炸。特征是有 Resource not found 之类的日志。

第四类,首屏渲染时抛异常。 比如 onCreate 里读权限、读配置,异常没接住,Ability 起来了但页面挂掉。这次我那条 ArkTS 警告(Function may throw exceptions)就属于这类风险。特征是 hilog 里有 JS 异常的堆栈。

第五类,白屏但不是白屏。 页面其实渲染了,只是内容全白——比如背景色和文字色都是白的。我第一版把 fontColor 写成了 '#FFFFFF',在浅色主题下看着就是一片空白,差点去查路由。

区分方法很土但有效:先看 hilog 有没有 ret 非 0,有就是加载失败;没有的话,把页面换成一个纯色 Column().backgroundColor('#F00'),能变红说明渲染链路是通的,问题在内容。

这个"分层排除"的思路,比挨个猜配置快得多。

十四、复盘:五条经验

第一,路由表是最容易漏的一环。 新建页面之后,除了写 .ets,还要在 main_pages.json 里登记。模板自带的页面路径是 generated/Index,如果你自己新建 pages/Xxx.ets,一定要改这里。这个错误不会有编译期提示,只在运行时表现成白屏。

第二,ret=1003 这类返回码要当成线索而不是错误。 它不告诉你"哪里错了",只告诉你"哪一步没成"。往下追一步,就是 loadContent 的参数,再往下就是路由表。

第三,预览器和模拟器验证的是两件事。 前者渲染单页,后者跑整个应用生命周期。两个都要看,顺序上建议先预览器(快,秒级),再模拟器(慢,但真实)。

第四,未签名包在模拟器上能装,别把这个当结论。 我这台模拟器(model=emulator,6.1.0.125)确实放行了未签名 HAP。但这是模拟器的宽松策略,不代表真机也这样。真机和上架都要签名,这是硬约束,后面我会单独写一篇讲签名的三道关。

第五,环境变量比命令重要。 NODE_HOME 和 DEVECO_SDK_HOME 这两个不设,hvigor 会去猜,猜错了报的错还挺误导人的("找不到 node"其实是你自己的 node 版本不对)。

还有一条不在列表里的:别在同一次排查里改两个地方。我中间有一次同时改了 main_pages.json 和 EntryAbility.ets 里的加载路径,结果好了以后不知道是哪个生效的,后来又故意回滚一个重测了一遍才敢确定。排查的乐趣在于收敛,一次只动一个变量,哪怕慢一点。

十五、把命令存成脚本

最后我把整套流程写成了一个脚本,放在工程根目录:

#!/bin/bash
DEVECO="/Applications/DevEco-Studio.app/Contents"
export NODE_HOME="$DEVECO/tools/node"
export DEVECO_SDK_HOME="$DEVECO/sdk"
cd "$(dirname "$0")"
"$DEVECO/tools/hvigor/bin/hvigorw" --mode module \
  -p product=default -p module=entry@default -p buildMode=debug \
  assembleHap --no-daemon

装和启动那就三条:

HDC=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc
$HDC list targets                                  # 先确认设备在
$HDC install -r entry/build/default/outputs/default/entry-default-signed.hap
$HDC shell aa start -b com.example.demoapp -a EntryAbility

注意安装那行的文件名:换成有签名的产物时是 -signed.hap,没签名是 -unsigned.hap。我一开始就是用 signed 的名字去装 unsigned 的产物,报了个"file not found",还以为是签名流程出了问题。

十六、装完之后,怎么确认装的是"对的那个"

装包成功不代表装对了。同一台模拟器上可能有旧版本,或者包名写错装成了另一个应用。我常用的三个确认动作:

第一,看设备连接状态。

hdc list targets -v
127.0.0.1:5555   TCP   Connected   localhost   hdc

Connected 才算真的通了,Offline 一般是模拟器还在启动。TCP 那一列说明这是网络连接的设备,模拟器和无线调试的真机都是这个形态。

第二,看设备上这个包的信息。

hdc -t 127.0.0.1:5555 shell bm dump -n com.example.demoapp

输出是一段 JSON,开头能看到:

"appId": "com.example.demoapp_",
"appIdentifier": "",
"appIndex": 0,

appIdentifier 是空的,这跟"未签名包"是对得上的——签名信息会写在这个字段附近。如果你装了签名包但这里是空的,说明签名没生效。

第三,看启动结果。

hdc shell aa start -b com.example.demoapp -a EntryAbility

-b 是包名,-a 是 ability 名,两个必须都在 module.json5 里注册过。启动失败时它不一定会报很明确的原因,通常只回一句 error,真正的线索还是要去 hilog 里找。

这三个动作加起来不到十秒,但能省掉很多"我明明装了怎么还是旧的"的困惑。我遇到过一次改了代码、构建成功、装也成功,界面却没变——原因是 aa start 拉起来的时候复用了已经运行的实例,得先 aa force-stop 或者把应用杀掉再启。这类问题跟代码无关,纯粹是运行时状态。

十七、为什么我全程用命令行,没点 IDE 里的按钮

原因说起来有点尴尬:我一开始就是在 IDE 里找"运行"按钮的,找了半天没找到。

当时用的是 CodeArts Agent——一个 VS Code 系的 AI 编码 IDE,写代码体验很好,但它没有鸿蒙的构建和调试能力。运行与调试面板是空的,我配了个 .vscode/tasks.json 想用任务跑构建,按了 Ctrl+Shift+B 也没反应,后来才想明白:工作区没受信任,任务被禁用了。

折腾了二十分钟没有结果,我干脆退回终端。现在回看,这次"退步"反而是收获——因为命令行把每一步都摊开了:哪条命令用了哪个 node、哪个 SDK、产物叫什么名字、签名有没有生效、设备连的是谁。这些东西在 IDE 里都被按钮包装掉了,出问题时你也看不见。

所以这篇文章里的数字和日志,全部来自命令行。不是我偏好终端,是被逼的。不过如果你只想快速验证,IDE 里点按钮也没什么问题——前提是它有那个按钮。

十八、如果你也想照着做

把我这次的步骤压成一份清单,省得你再摸一遍:

  1. 从 plugins/codegenie-plugin/previewProjectTemplate 复制一份工程出来,改 AppScope/app.json5 里的 bundleName;
  2. 改 build-profile.json5 的 compileSdkVersion / compatibleSdkVersion 为你机器上实际装的 SDK,删掉不存在的 signingConfig 引用;
  3. 写页面放在 entry/src/main/ets/pages/ 下,同时把路径登记进 resources/base/profile/main_pages.json;
  4. 用 NODE_HOME + DEVECO_SDK_HOME 调 hvigorw assembleHap,确认 BUILD SUCCESSFUL;
  5. hdc list targets 确认有设备,没有就去 DevEco 里开一次预览器(会带起本地模拟器);
  6. hdc install -r 装包,hdc shell aa start -b <包名> -a <ability> 启动;
  7. hdc shell snapshot_display + file recv 截屏,肉眼确认首屏;
  8. 不对就 hilog -x 过滤应用名,先看返回码,再对配置。

八步里有两步最容易漏:第 3 步的登记、第 5 步的设备。我两次卡住都在这里。

最后

搭这个最小工程,本来只是想要一个干净的实验环境。结果它教会我的东西比预期多:编译链路怎么依赖 DevEco 的工具链、路由表怎么决定首屏、预览器和模拟器的边界在哪、未签名包在什么条件下能装。

如果你也在做鸿蒙的第一次"从 0 到跑通",建议别用现成的大工程练手。找个空目录,从模板抄一份,把页面上那三行文字改掉,然后逼自己走完"编译 → 安装 → 启动 → 截屏"这四步。中途一定会卡,但卡住的地方,恰恰是你以后每天都要打交道的部分。

这个工程现在留在我的桌面上,一共不到 40 个文件、124 KB 的产物。它不会变成产品,但它是我后面所有实验的底座:跨端要改它的 deviceTypes,签名要拿它试 profile,开源托管要拿它试 .gitignore。用一个小的、自己完全理解的工程当底座,比在别人几十万行代码里改一处看一处要踏实得多。

下一次卡住大概是签名。因为我到现在还不知道,为什么未签名的包在这台模拟器上能装——这件事我得单独查清楚,顺便把真机那套流程也走一遍。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐