从空目录到跑在模拟器上:我搭了一个最小鸿蒙工程,踩了两个坑
从空目录到跑在模拟器上:我搭了一个最小鸿蒙工程,踩了两个坑
一、为什么要自己搭一个
我手头有个真实的鸿蒙项目,功能挺全,分布式同步、麦克风权限、卡片都有。但每次想验证一个很基础的问题——“这个构建流程到底能不能跑通”——都会被它庞大的工程结构拖住:几十个 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.json | 1.6 KB | 模块清单:入口 ability、设备类型、页面路由 |
ets/modules.abc | 12.9 KB | ArkTS 编译产物(字节码) |
resources.index | 1.1 KB | 资源索引:字符串、颜色、媒体的映射表 |
resources/base/media/ | ~103 KB | background / foreground / startIcon 三张图 |
resources/base/profile/main_pages.json | 27 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 里点按钮也没什么问题——前提是它有那个按钮。
十八、如果你也想照着做
把我这次的步骤压成一份清单,省得你再摸一遍:
- 从
plugins/codegenie-plugin/previewProjectTemplate复制一份工程出来,改AppScope/app.json5里的bundleName; - 改
build-profile.json5的compileSdkVersion/compatibleSdkVersion为你机器上实际装的 SDK,删掉不存在的signingConfig引用; - 写页面放在
entry/src/main/ets/pages/下,同时把路径登记进resources/base/profile/main_pages.json; - 用
NODE_HOME+DEVECO_SDK_HOME调hvigorw assembleHap,确认BUILD SUCCESSFUL; hdc list targets确认有设备,没有就去 DevEco 里开一次预览器(会带起本地模拟器);hdc install -r装包,hdc shell aa start -b <包名> -a <ability>启动;hdc shell snapshot_display+file recv截屏,肉眼确认首屏;- 不对就
hilog -x过滤应用名,先看返回码,再对配置。
八步里有两步最容易漏:第 3 步的登记、第 5 步的设备。我两次卡住都在这里。
最后
搭这个最小工程,本来只是想要一个干净的实验环境。结果它教会我的东西比预期多:编译链路怎么依赖 DevEco 的工具链、路由表怎么决定首屏、预览器和模拟器的边界在哪、未签名包在什么条件下能装。
如果你也在做鸿蒙的第一次"从 0 到跑通",建议别用现成的大工程练手。找个空目录,从模板抄一份,把页面上那三行文字改掉,然后逼自己走完"编译 → 安装 → 启动 → 截屏"这四步。中途一定会卡,但卡住的地方,恰恰是你以后每天都要打交道的部分。
这个工程现在留在我的桌面上,一共不到 40 个文件、124 KB 的产物。它不会变成产品,但它是我后面所有实验的底座:跨端要改它的 deviceTypes,签名要拿它试 profile,开源托管要拿它试 .gitignore。用一个小的、自己完全理解的工程当底座,比在别人几十万行代码里改一处看一处要踏实得多。
下一次卡住大概是签名。因为我到现在还不知道,为什么未签名的包在这台模拟器上能装——这件事我得单独查清楚,顺便把真机那套流程也走一遍。
更多推荐
所有评论(0)