

去年开始学唱歌，问题很朴素：清唱时听不出自己跑没跑调。手机自带的录音要录完再回放，练一句听一句太碎。市面上有耳返类工具，但要么延迟高到能听出回声，要么只能在特定硬件上用。
手上有一台 Pura X 和一副 FreeClip 2，我想：既然 HarmonyOS 开放了低延迟音频接口，为什么不自己做一个？
我不是专业音频开发，DSP 那些谱减、混响的公式也是现查的。整个过程我基本把 WorkBuddy 当结对伙伴——写代码、查 API、读崩溃日志、生成上架材料，都是它陪我磨出来的。
这篇文章不讲产品，讲过程。特别是**上架阶段踩的坑**，那是查文档查不到、只能靠实际撞出来的部分。


----
## 一、技术骨架：两路 FAST 流 + 无锁环形缓冲

核心链路很短：麦克风采集 → 音效处理 → 耳机播放。难点全在延迟上。
HarmonyOS 的 OHAudio 提供了 `LATENCY_MODE_FAST`，但有两个硬约束容易忽略：
- FAST 模式下采样率必须是 48kHz、位深 S16LE、编码 RAW，采集和播放两路都要这样；

- 系统会**静默降级**。你声明了 FAST，实际协商成 NORMAL 也不报错——必须启动后回读 `OH_AudioRenderer_GetLatencyMode` 才知道生没生效。

所以我加了一个回读校验，界面右上角显示「低延迟已生效」或「已降级」，不让用户猜。
两路流之间用无锁环形缓冲直通，采集回调里做 DSP（降噪、高频平滑、混响、增益），渲染回调取数据，取不够补静音——绝对不半帧拷贝，否则会有周期性爆音。
![App 主界面：返听运行中，延迟 5~10ms](https://developer.qcloudimg.com/http-save/yehe-12849697/f262619a0b1424765b02865cbf3dee3e.jpg)实测应用侧延迟 **5~10ms**（采集到播放，不含耳机自身传输）。


----
## 二、上架才是真正的战场

代码能跑之后，我以为剩下的就是打包上传。结果从打包到云测试通过，折腾了整整两天。下面 6 个坑按遇到顺序排，每个都附解法。
### 坑 1：`.app` 文件自己也有签名块，漏签直接报错误码 991

第一次上传，AGC 提示：
```

```我一开始想：HAP 不是已经签了吗？
后来对比 hvigor 产出的 signed.app 和 unsigned.app 才发现——**两者的 HAP 大小完全一样，但 signed.app 整体大了 14,767 字节**。
这 14.7 KB 就是 `.app` 文件自身的签名块，挂在 zip 末尾。
`hap-sign-tool` 官方文档写着只支持 `.hap/.bin/.elf`，但实测**可以直接对 `.app` 签名**（两者同为 zip + 签名块结构），参数上把 `-signCode` 设为 0（代码签名只对 hap 有效）：
```

```签完体积增加 14.6 KB，`verify-app` 输出 `Digest verify result: true` 就对了。
![签名校验通过：block count 2](https://developer.qcloudimg.com/http-save/yehe-12849697/098d79c3e82a1b4a4bd26d378a74da8b.png)### 坑 2：手工打的 .app 缺 pac.json

修完签名，第二次上传变成「软件包解析失败」。
拆开 hvigor 的包和我的包对比，发现 hvigor 的包里有**三个**文件：

| | |
|:-:|:-:|
|文件|作用|
|entry-default.hap|应用本体|
|**pac.json**|隐私清单，`{"dataProcess":[],"specialAPIs":[]}`|
|pack.info|包信息|
我的包里只有两个，缺 `pac.json`。用 `app_packing_tool` 从零打包不会生成它。
解法是「骨架替换法」：先让 hvigor 用调试签名打一个完整 `.app` 当骨架，再把里面的 HAP 换成发布签名的版本，`pac.json` 和 `pack.info` 原样保留。注意所有条目必须是 STORED（不压缩）。
### 坑 3：hvigor 不接受明文密码

这个问题卡了我一阵。在 `build-profile.json5` 里填明文口令，hvigor 直接报：
```

```它要求的是 DevEco 加密后的密文（形如 `0000001B...`），加密算法在 IDE 内部，命令行生成不出来。
绕过方式就是前面两步：不走 `assembleApp`，手动分步做「构建 unsigned HAP → 签 HAP → 组 .app → 签 .app」。我把这四步写成了一个脚本，现在改完代码到出包大概 1 分钟。
### 坑 4：so 链接了高版本符号，整个 NAPI 模块失效

这个坑最坑——**应用在自己手机上完全正常，云测试却报启动失败**。
测试机是 HarmonyOS 6.1（API 24），我的包声明支持 API 24，编译用的却是 API 26 的 SDK。
崩溃日志的 JS 栈是这样的：
```

```看起来是某个方法不存在。但这只是表象。
真正的原因在 hilog 里：
```

```**我用了一个 API 26 才有的降噪接口，so 在 API 24 系统上重定位失败，整个 so 加载不起来，于是 NAPI 模块变成 undefined，任何原生方法调用都会抛 TypeError。**
解法是把高版本接口改成运行时查找（dlsym），符号不存在时功能降级：
```

```改完还要全量核对：把 so 的动态符号表列出来，逐个查 NDK 头文件里的 `introduced` 版本，确认**没有一个高于 minAPI**。我这儿一共 43 个未定义符号，最高的是 API 23，这样就安全了。
```

```改完重新提交云测试，Mate 80 Pro 和 Mate X7 两台设备都显示「应用启动无兼容性问题」，这一项才算真过。
### 坑 5：应用图标必须分层，而且不能自己画圆角

审核驳回原文：「应用图标资源必须分为前景图和背景图两层，尺寸要求必须为 1024px × 1024px，资源不允许自行裁切圆角，不允许在资源内添加内间距。」
这里的逻辑是：圆角和裁切由系统在运行时统一处理，你自己画的圆角会和系统的圆角叠加，轻则「圆中圆」，重则四角漏底。
正确做法是两层各 1024×1024：
- **前景**：透明背景，主体图案放在中央安全区（约画布 62.5%），四周留白交给背景层

- **背景**：纯色或渐变，铺满整张，不加任何内边距

然后写一个 `layered_image.json` 把它们组合起来：
```

````app.json5` 和 `module.json5` 的 `icon` 都改成 `$media:layered_image`。另外**必须删掉工程里旧的单层图标**，哪怕没被引用——审核扫包时看到单层图还是会被判。
![分层图标：前景 / 背景 / 合成](https://developer.qcloudimg.com/http-save/yehe-12849697/db8564afa03cdf5f8a9ebd03aab92ffd.png)### 坑 6：手机截图不符合 16:9，而且不能硬裁

上传商店截图，被打回：「最低尺寸 1920×1080，宽高比 16:9」。
我的截图是 1828×2584（竖屏），既不够宽也不是 16:9。想着裁一下就好，结果发现——**界面内容几乎占满整个高度，裁掉 374px 会把底部功能全切掉**。
最后用的是「裁状态栏 + 两侧补边」：
1. 裁掉顶部 92px 状态栏（这个值试出来的，少一像素会有图标残影）

1. 取界面底色作填充色

1. 把截图居中贴到 16:9 画布上，两侧用底色延展

出来的图 3086×1736，比例精确 1.778，视觉上像宽屏界面，内容一点没少。
顺带说，截图内容也有讲究：状态栏、设备型号（「Pura X Max 典藏版」这种）、第三方 App 名字、内部阶段标识（「Phase 1」）、调试参数，都不能出现。我第一版截图全都有，全部重截了一遍。


----
## 三、结果

- 应用侧延迟 5~10ms，双路 FAST 流稳定运行

- 云测试通过（Mate 80 Pro / Mate X7，HarmonyOS 6.1）

- 包体签名、图标、隐私材料、商店文案全部就绪

- 等版权证书下来就能提交上架


----
## 四、WorkBuddy 在哪些环节真正省了事

说实话，写代码环节它帮我最多的是**读别人的东西**：OHAudio 的头文件、AGC 的报错文案、崩溃日志里那些 `MUSL-LDSO` 的术语，我看一眼就懵，它能直接告诉我「这在说符号重定位失败」。
第二个是**排查**。坑 4 那个崩溃，如果只盯着 JS 栈会越查越偏，是把 hilog 整段丢给它，才定位到 so 加载失败。
第三个是**生成规范材料**：隐私政策、商店文案、审核备注、图标和截图的规格转换——这类事不难但琐碎，一次做完省半天。
真正需要我自己判断的还是产品决策：要不要支持 PC、付费模式怎么定、截图里该露出什么。这些它给建议，但拍板的得是我。


----
## 写在最后

如果你也在做鸿蒙应用，希望这 6 个坑能帮你省两天。特别是坑 1 和坑 4——那两个是文档里查不到、社区里也没几篇写过的部分。
有问题的可以在评论区问，我看到会回。

去年开始学唱歌，问题很朴素：清唱时听不出自己跑没跑调。手机自带的录音要录完再回放，练一句听一句太碎。市面上有耳返类工具，但要么延迟高到能听出回声，要么只能在特定硬件上用。手上有一台 Pura X 和一副 FreeClip 2，我想：既然 HarmonyOS 开放了低延迟音频接口，为什么不自己做一个？我不是专业音频开发，DSP 那些谱减、混响的公式也是现查的。整个过程我基本把 WorkBuddy 当结对伙伴——写代码、查 API、读崩溃日志、生成上架材料，都是它陪我磨出来的。这篇文章不讲产品，讲过程。特别是上架阶段踩的坑，那是查文档查不到、只能靠实际撞出来的部分。

# 用 WorkBuddy 做一个鸿蒙低延迟耳返 App：从写代码到上架的 6 个硬坑

## 缘起：我想要一个「戴上耳机就能听见自己」的工具

利用workbuddy开发鸿蒙耳返软件，实现有限星闪的低延迟耳返，过程小记录

人工智能

利用HarmonyOS低延迟音频接口，用PuraX和FreeClip2自建耳返工具，实现5-10ms零回声监听。本文分享上架6大坑：.app签名、pac.json缺失、API符号越级、分层图标、截图比例，附完整解法，助你避开审核陷阱。

代码解释

WorkBuddy 

JSON

WorkBuddy企业版限时双倍 Credits 活动

workbuddy

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

# 用 WorkBuddy 做一个鸿蒙低延迟耳返 App：从写代码到上架的 6 个硬坑

## 缘起：我想要一个「戴上耳机就能听见自己」的工具-腾讯云开发者社区-腾讯云

# 用 WorkBuddy 做一个鸿蒙低延迟耳返 App：从写代码到上架的 6 个硬坑 ## 缘起：我想要一个「戴上耳机就能听见自己」的工具

# 用 WorkBuddy 做一个鸿蒙低延迟耳返 App：从写代码到上架的 6 个硬坑 ## 缘起：我想要一个「戴上耳机就能听见自己」的工具

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐