HarmonyOS开发者社区

在 Harmony 开发中遇到 BusinessError 时如何快速判断是权限问题、参数问题还是 API 不支持？

李游Leo 2025-11-17 10:00:55

harmonyos

在使用 AudioKit（createAudioCapturer、createAudioLoopback 等接口）时，经常会抛出 BusinessError，常见的 code 包括：

201
801
6800101
6800301
6800104

每次都要去翻“通用错误码”和“Audio 错误码”文档，定位效率比较低，想知道有没有比较通用的排查思路，顺便请教下这些常见错误大概对应什么问题。

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

audio.createAudioCapturer(options)
  .then((capturer) => {
    // ...
  })
  .catch((err: BusinessError) => {
    console.error(`createAudioCapturer error, code=${err.code}, msg=${err.message}`);
  });

不同接口抛出的 code 不同。

写回答

全部评论(1)

TechnologyDream

1 楼

可以把常见错误大致分成三大类：权限 / 授权、API 支持情况、参数与业务逻辑。结合你提到的几个 code，总结一个实战版小表：

具体含义以你当前版本的「通用错误码说明」和「Audio 错误码说明」文档为准，这里重点给排查思路。Gitee

1. 权限 / 授权相关

201 Permission denied
典型场景：
- 忘记在 module.json5 里声明 ohos.permission.MICROPHONE 就调用 createAudioCapturer；
- 或者声明了但没有在运行时向用户弹框申请 / 用户拒绝了。

排查步骤：

检查配置文件 requestPermissions 是否声明了对应权限；
是否在业务代码中调用了 verifyPermission / requestPermissionsFromUser；
真机上确认用户是否点击了“允许”。

2. API 支持情况

801 Unsupported API
常见原因：
- 调用了 System API（如 AudioVolumeManager.setVolume 等）而应用不是系统应用；
- 或当前设备 / 模拟器根本不支持该能力。

排查步骤：

打开对应接口文档，检查是否标记为 “System API”；
查看接口的 “SystemCapability” 要求，确认当前设备是否具备该能力；
如为 System API，普通应用应直接做功能降级，不再坚持使用。

6800104 Loopback mode is unsupported（AudioLoopback 专属）
含义：当前返听模式（比如 HARDWARE）不支持。
一般需要在调用 createAudioLoopback 前先使用 isAudioLoopbackSupported 做判断，不支持则关闭该功能。Gitee

3. 参数与业务逻辑相关

6800101 Parameter verification failed
常见场景：
- AudioRendererOptions 中缺少必填字段（例如缺少 rendererInfo）；
- 使用普通数字代替枚举类型，导致类型校验失败；
- 某些字段为 undefined 或类型错误。

排查思路：

对照文档逐一检查入参类型和必填字段；
优先使用枚举常量（AudioSamplingRate、AudioChannel 等），不要自己写 magic number；
在创建前打印 JSON.stringify(options) 确认没有 undefined。

6800301 参数校验异常 / 权限校验异常 / 系统处理异常
这是一个比较“汇总型”的错误码，常见在 createAudioCapturer 里出现。
可能原因包括：
- 参数不合法（同 6800101）；
- 权限未通过校验（同 201 场景）；
- 系统内部处理异常（需要看系统日志）。

排查步骤：

先按 6800101 的步骤检查参数；
再按 201 的步骤确认权限配置与授予情况；
如果都确认没问题，使用 HDC / DevEco 控制台查看系统日志，搜索关键字 createAudioCapturer 或错误码，定位更详细原因。

一个通用的调试小工具

可以封装一个打印 BusinessError 的帮助函数：

import { BusinessError } from '@kit.BasicServicesKit';

export function logBusinessError(prefix: string, err: BusinessError) {
  console.error(
    `${prefix} failed, code=${err.code}, message=${err.message}, stack=${err.stack}`
  );
}

调用：

audio.createAudioCapturer(options)
  .catch((err: BusinessError) => {
    logBusinessError('createAudioCapturer', err);
  });

配合上面的分类记忆：

2xx → 优先看权限；
801 → 优先看是否 System API / 能力不开放；
6800xxx → 结合接口文档重点排查参数 + 权限 + 系统日志。

养成这个习惯之后，遇到 BusinessError 基本可以在几分钟内定位到是哪一类问题。

2025-11-17 10:48:41