云手机到手后,第一步就卡住了: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 failed
  • hvigor ERROR: 00303024 Configuration Error The project structure and configuration need to be upgraded
  • error: 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 竖屏,渲染正常:

应用启动

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

连接成功

六、几个补充提醒

  1. 云手机有时间限制。 我开的那台剩余时长 13 小时多,用之前先看 hdspace cloudphone list 的剩余时长,别做一半被回收。
  2. 隧道是单点。 隧道进程一断,所有 hdc 操作全失效。跑长任务时建议放 nohup 或独立窗口。
  3. Command Line Tools 下载要登录。 官方下载页必须华为账号,CI 环境要考虑预置缓存或找镜像。
  4. aa start 失败不代表没起来,install 未签名也能成功,这两点能省很多排查时间。

希望这些能帮到同样卡在第一步的同学。完整工程和实测数据我整理在仓库里:

  • 仓库:https://gitcode.com/cpyaxjq/harmonyos-cloudphone-task-continuation
  • 系列另一篇《多设备任务接续:云手机 + 4 节点后端全链路实测》讲服务端部分
Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐