鸿蒙云手机怎么用?从连不上到跑通 ArkTS 应用的完整答疑鸿蒙云手机ArkTSDevEco
云手机到手后,第一步就卡住了:
hdc list targets是空的。这篇把我踩过的坑按问答整理出来,希望后来者少折腾。
一、为什么写这篇
我在华为开发者空间开了一台鸿蒙云手机,想用它做「多设备任务接续」的真实端侧验证。整个过程里,我遇到的报错有:
[Fail]ExecuteCommand need connect-key? please confirm a device by help info[Fail]Not match target founded, check connect-key please[Fail]Connect failedhvigor ERROR: 00303024 Configuration Error The project structure and configuration need to be upgradederror: failed to start ability.
这些报错在文档里都搜不到确切原因。我花了几个小时才逐个定位,下面按问题整理。
二、云手机基础信息怎么查
连上之后,第一件事是把设备信息读全:
hdc -t 127.0.0.1:8712 shell "param get const.product.software.version; \
param get const.ohos.apiversion; \
param get const.product.model; \
param get const.product.devicetype"
我的云手机返回:
5.0.1.130(SP2C00E1R4P1log)
17
ALN-AL00
phone
对应:HarmonyOS 5.0.1、API 17、Mate 60 Pro、手机形态、分辨率 1260×2720、8 vCPU / 12 GB。
注意必须带 -t 127.0.0.1:8712。不带的话 hdc 不知道你指哪台设备,报的就是第一条 need connect-key。
三、Q&A
Q1:隧道显示 connect to tunnel server success,但 hdc 就是 Connect failed
这是最坑的一个。
现象:
hdspace cloudphone start-tunnel输出client is listening on localhost:8712+connect to tunnel server success- 但
hdc tconn 127.0.0.1:8712一直[Fail]Connect failed hdspace cloudphone list显示实例Running
原因有两层,必须都处理:
第一层:hdc 客户端缓存了死连接。 隧道断过一次之后,hdc 内部还握着上一个 socket,重连时直接复用,必然失败。
第二层:隧道进程可能已经退出。 命令行窗口关闭、命令超时被 kill,都会导致 hdspace 进程消失,但端口文件残留。
正确的复位顺序(顺序错了永远连不上):
# 1. 先确认隧道进程活着
ps aux | grep hdspace # Linux/WSL
Get-Process hdspace # Windows PowerShell
# 2. 隧道死了就重启
hdspace cloudphone start-tunnel --name=<你的云手机名> --port=8712
# 3. 关键:先杀 hdc 服务,再重连
hdc kill
hdc tconn 127.0.0.1:8712
# 4. 验证
hdc list targets
# 输出 127.0.0.1:8712 才算成功
hdc kill 这一步不能省。我一开始直接 tconn,重试十几次全是 Connect failed,加上 hdc kill 后一次就通。
Q2:hvigor 报「工程结构需要升级」,但我是命令行环境,没有 DevEco Studio
完整报错:
hvigor ERROR: 00303024 Configuration Error
Error Message: The project structure and configuration need to be upgraded before use.
* Try the following:
> Use the migration tool to update the project structure and configuration with Deveco Studio
命令行里没有 Studio,这条建议等于没用。
真实原因是 modelVersion 缺失或不一致。hvigor 的校验逻辑在 validate-util.js 里:
const i = HvigorConfigLoader.getInstance().getHvigorConfig()?.modelVersion; // hvigor/hvigor-config.json5
const r = parseJsonFile('oh-package.json5').modelVersion; // 项目根目录
i && r ? (i === r ? 继续 : 报 INCONSISTENT_MODEL_VERSION)
: 报 PROJECT_STRUCTURE_AND_CONFIGURATION;
也就是说:两个文件都必须有 modelVersion,且值必须完全相等。
// hvigor/hvigor-config.json5
{
"modelVersion": "5.0.0",
"dependencies": {}
}
// oh-package.json5(项目根目录)
{
"name": "harmonyshadow",
"version": "1.0.0",
"modelVersion": "5.0.0",
"dependencies": {}
}
只改一边,报错一模一样,看不出差别。这是最容易误判的地方。
另外 hvigor/hvigor-config.json5 这个文件如果完全不存在,会先报另一个错:
Error Message: Hvigor config file ...hvigor/hvigor-config.json5 does not exist.
手动建工程时要记得建 hvigor/ 目录。
Q3:No signingConfig found for product default 是不是必须配签名?
不是。这是警告,不是错误。
hdc -t 127.0.0.1:8712 install entry-default-unsigned.hap
# [Info]App install path:...entry-default-unsigned.hap msg:install bundle successfully.
未签名 HAP 在云手机开发环境可以直接安装。配签名要实名、CSR、Profile,流程很长,开发调试阶段完全没必要。
生产发布才需要签名。
Q4:aa start 返回 error: failed to start ability.,是不是没起来?
大概率是起来了,只是返回值不可信。
验证方法看 hilog:
hdc shell hilog -r
hdc shell "aa start -a EntryAbility -b com.example.harmonyshadow"
hdc shell "hilog -x | grep harmonyshadow | tail -20"
如果看到类似:
C03F00/com.example.harmonyshadow/ArkCompiler: [gc] SmartGC: app cold start just finished
说明进程已经在跑,ArkCompiler 做过冷启动 GC 了。
最可靠的判断标准是截图,不是命令返回码:
hdc shell "snapshot_display -f /data/local/tmp/s1.jpeg"
hdc file recv /data/local/tmp/s1.jpeg ./s1.jpeg
Q5:云手机能连公网服务吗?
能。我的应用直接连了公网 IP 上的 WebSocket 服务:
this.ws.connect('ws://1.92.107.89/ws?device=hm-phone-01&type=phone');
实测点「连接」后 5 秒内建链并收到首包:
12:16:36 已连接 hm-phone-01
12:16:41 收到 seq=272 来自=hm-tablet-01: 平板侧第272次编辑
不用做任何端口映射或内网穿透。
Q6:怎么在云手机上模拟点击和输入?
uinput 命令,坐标按实际分辨率算(1260×2720),不是截图缩放后的尺寸。
# 点击
hdc shell "uinput -T -c 374 677"
我的「连接」按钮在截图里是 (140, 255),截图尺寸 472×1024,换算:
x = 140 × 1260 / 472 = 374
y = 255 × 2720 / 1024 = 677
按截图坐标直接点会点偏。
Q7:编译一次要多久?值得用云手机吗?
我实测的完整链路:
| 步骤 | 耗时 |
|---|---|
| hvigor 增量编译 | 18.3 s |
| hdc install | ~3 s |
| aa start | ~1 s |
| 截图 + 回传 | ~1.5 s |
| 合计 | 约 24 s |
改一行 ArkTS,24 秒后在本地看到云手机截图。
对比:等真机快递按天算,模拟器冷启动就要 1 分钟以上。云手机在「改-看」循环上明显更快。
四、一个完整的可用流程
把上面所有结论串起来:
# 1. 配置密钥(只需一次,SK 要输入两次确认)
hdspace config
# 2. 建隧道(保持这个进程别关)
hdspace cloudphone start-tunnel --name=HMCPhone_xxxx --port=8712
# 3. 连接
hdc kill && hdc tconn 127.0.0.1:8712
hdc list targets
# 4. 环境变量
export JAVA_HOME=/path/to/jdk-17
export DEVECO_SDK_HOME=/path/to/command-line-tools/sdk
# 5. 编译
hvigorw --mode module -p product=default -p module=entry@default assembleHap --no-daemon
# 6. 安装
hdc -t 127.0.0.1:8712 install entry/build/default/outputs/default/entry-default-unsigned.hap
# 7. 启动
hdc -t 127.0.0.1:8712 shell "aa start -a EntryAbility -b com.example.harmonyshadow"
# 8. 截图验证
hdc -t 127.0.0.1:8712 shell "snapshot_display -f /data/local/tmp/s1.jpeg"
hdc -t 127.0.0.1:8712 file recv /data/local/tmp/s1.jpeg ./s1.jpeg
五、运行效果
按上面流程跑出来的界面,1260×2720 竖屏,渲染正常:

连上公网服务后收到对端消息:

六、几个补充提醒
- 云手机有时间限制。 我开的那台剩余时长 13 小时多,用之前先看
hdspace cloudphone list的剩余时长,别做一半被回收。 - 隧道是单点。 隧道进程一断,所有 hdc 操作全失效。跑长任务时建议放
nohup或独立窗口。 - Command Line Tools 下载要登录。 官方下载页必须华为账号,CI 环境要考虑预置缓存或找镜像。
aa start失败不代表没起来,install未签名也能成功,这两点能省很多排查时间。
希望这些能帮到同样卡在第一步的同学。完整工程和实测数据我整理在仓库里:
- 仓库:https://gitcode.com/cpyaxjq/harmonyos-cloudphone-task-continuation
- 系列另一篇《多设备任务接续:云手机 + 4 节点后端全链路实测》讲服务端部分
更多推荐


所有评论(0)