常见问题 (FAQ)

这里收集了使用 AaaS Pilot Kit 过程中的常见问题和解决方案。

问：为什么需要用户主动触发点击或其他行为才能开启声音？

答： 现代浏览器为了防止恶意网站自动播放音频干扰用户，实施了自动播放限制策略。数字人的语音播放功能受此限制影响，只有在以下情况下才允许音频播放：

• 用户已与页面产生交互行为（点击、触摸、按键等）
• 音频处于静音状态或音量为 0
• 网站已被用户信任（浏览器根据用户访问频率自动判断）
• 通过浏览器权限策略明确授权

解决方案： 在初始化数字员工时，需要提供用户激活按钮，引导用户主动点击启动音频功能（按钮可以叫“开启对话之旅”）。这是浏览器安全机制的要求，必须通过用户的主动操作来激活。

问：iPhone 微信浏览器中数字人无法展示怎么办？

答： 部分移动端浏览器存在媒体播放限制，需要用户手动激活才能正常播放。

解决方案： 调用 activateManually() 方法进行手动激活，详见 API 文档。

问：为什么数字人渲染失败或无法正常工作？

答： WebRTC 技术要求必须在 HTTPS 环境下运行，HTTP 环境下无法正常工作。

解决方案： 确保你的应用部署在 HTTPS 环境中。本地开发时，可使用 localhost 或配置本地 HTTPS 证书。

问：字幕显示与数字人播报不同步怎么办？

答： 设置了 typeDelay 和 enTypeDelay 后，字幕按固定速度显示，但数字人播报有自然的语气停顿和节奏变化，因此无法完全同步。

解决方案： 这是正常现象。如需更好的同步效果，可以适当调整 typeDelay 参数，或考虑使用事件监听来优化字幕显示时机。

问：无法进行语音输入，麦克风不工作？

答： 浏览器需要用户明确授权才能访问麦克风设备。

解决方案：

1. 检查浏览器地址栏是否有麦克风权限提示
2. 在浏览器设置中确认已允许该网站访问麦克风
3. 确保设备麦克风功能正常

// 监听麦克风权限错误
controller.emitter.on('error', (error) => {
    if (error.code === '3103') {  // 更新为新的权限错误码（旧版本 3008 已废弃）
        showMessage('请允许麦克风权限以使用语音功能');
    }
});

问：安卓浏览器中数字人不动作怎么办？

答： 部分安卓浏览器对 WebRTC 支持不完善，或需要用户交互才能激活媒体播放。

解决方案：

1. 使用 activateManually() 方法手动激活
2. 建议用户使用 Chrome、Edge 等主流浏览器
3. 确保浏览器版本较新，支持完整的 WebRTC 功能

问：数字人无法显示或出现黑屏怎么办？

答： 可能的原因和解决方案：

1. 网络连接问题 - 检查网络连接状态
2. figureId 配置错误 - 确认 figureId 参数是否正确
3. 容器元素问题 - 确认挂载容器存在且可见
4. 浏览器兼容性 - 确认浏览器支持 WebRTC 功能

问：如何优化性能？

1. 调整分辨率：

figureResolutionWidth: 720,  // 降低分辨率提升性能
figureResolutionHeight: 1280

2. 合理的音频采样率：

ttsSample: 16000  // 平衡音质与性能

3. 结束时调用 dispose() 清理

// 以 React 技术栈为例
useEffect(
    () => {
        const cleanup = () => {
            controller.dispose();
        };
        return cleanup;
    },
    []
);

问：rendererMode 为 cloud-native 时，自定义内容层级被数字人形象覆盖怎么办？

答： 在 rendererMode 设置为 cloud-native 的情况下，数字人形象采用 position: absolute 定位，z-index: 1。如果需要在数字人形象上方实现字幕或其他自定义元素，您需要手动调整这些自定义元素的定位（position）和 z-index 值，确保其层级高于数字人形象（即 z-index 值大于 1）。

问：如何调试问题？

开启调试模式获取详细日志：

const controller = createAaaSPilotKit({
    token: 'your-auth-token-here',
    // ... 其他配置
    env: 'development',
    enableDebugMode: true,
});

// 监听所有错误
controller.emitter.on('error', (error) => {
    console.group('AaaS Kit 错误详情');
    console.error('错误代码:', error.code);
    console.error('错误信息:', error.message);
    console.error('严重程度:', error.severity);
    console.error('元数据:', error.metadata);
    if (error.stack) {
        console.error('错误堆栈:', error.stack);
    }
    console.groupEnd();
});

问：常见错误代码及解决方案

通用错误 (1000-1999)

错误代码	错误描述	解决方案
1001	网络连接错误	检查网络连接状态，确保网络畅通后重试
1002	请求超时	检查网络延迟，增加超时时间配置
1003	配置参数无效	检查 figureId、token、robotId 等配置参数是否正确
1004	身份验证失败	检查 token 是否有效，联系技术支持确认权限

Agent 服务错误 (2000-2999)

错误代码	错误描述	解决方案
2001	Agent 查询失败	检查 robotId 配置，确认 Agent 服务状态
2002	Agent 响应解析错误	检查 Agent 返回数据格式，联系技术支持
2003	Agent 请求超时	检查网络连接，适当增加超时时间
2005	Agent 连接失败	确认 Agent 服务地址和网络连通性

语音识别错误 (3000-3999)

错误代码	错误描述	解决方案
3001	ASR 初始化失败	检查浏览器兼容性，确认音频设备可用
3002	ASR 启动失败	检查麦克风权限，确保设备正常工作
3007	ASR 网络错误	检查网络连接，确认语音服务可访问
3008	ASR 权限被拒绝	⚠️ 已废弃，请使用 3103 代替
3009	ASR 设备未找到	确认音频输入设备已连接并正常工作
3100	浏览器不支持 MediaDevices API	升级浏览器或使用现代浏览器（Chrome 53+, Firefox 36+, Safari 11+）
3101	需要 HTTPS 安全上下文	使用 HTTPS 协议访问，或在开发时使用 localhost
3102	音频设备枚举失败	检查设备连接，重新插拔麦克风
3103	用户关闭权限请求	引导用户在浏览器设置中开启麦克风权限（参见下方"麦克风设备问题排查"）
3104	设备被占用或不可读	关闭其他使用麦克风的应用
3105	音频设备检测超时	检查网络连接，重试操作

数字人服务错误 (4000-4999)

错误代码	错误描述	解决方案
4001	数字人挂载失败	检查容器元素是否存在，确认页面 DOM 结构
4003	数字人渲染错误	检查 figureId 配置，确认浏览器支持 WebRTC
4005	数字人 RTC 错误	确保 HTTPS 环境，检查浏览器 WebRTC 支持
4006	数字人认证错误	验证 token 有效性，检查数字人服务权限
4007	会话数量达到上限	等待现有会话结束或联系技术支持提升额度
4012	数字人形象 ID 无效	确认 figureId 参数正确，联系技术支持确认可用形象
4013	数字人 token 无效	检查 token 格式和有效期，重新获取有效 token

部署和环境问题

问：生产环境部署注意事项

1. 关闭调试模式：

env: 'production',
enableDebugMode: false

2. 配置错误监控：

controller.emitter.on('error', (error) => {
    // 上报到监控系统
    if (error.severity === 'high' || error.severity === 'critical') {
        reportToMonitoring(error);
    }
});

如果仍有问题，联系技术支持获取域名白名单配置。

麦克风设备问题排查

问：如何检测麦克风是否可用？

使用 controller.checkAudioDevice() 方法进行设备检测：

// 监听检测结果
controller.emitter.on('microphone_available', (result) => {
    console.log('设备可用:', result.available);

    if (!result.available) {
        console.error('错误类型:', result.error);
        console.error('错误提示:', result.userMessage);
    }
    else {
        console.log('找到', result.devices?.length, '个音频设备');
        console.log('权限状态:', result.permissionState);
    }
});

// 执行检测
await controller.checkAudioDevice();

问：常见麦克风错误及解决方案

错误 3100：浏览器不支持 MediaDevices API

现象: 提示"浏览器不支持 MediaDevices API"

原因: 浏览器版本过旧

解决方案:

1. 升级到现代浏览器：
   • Chrome 53+ / Edge 79+
   • Firefox 36+
   • Safari 11+
   • Opera 40+

错误 3101：需要 HTTPS 安全上下文

现象: 提示"需要 HTTPS 安全上下文"

原因: 在非 HTTPS 环境下访问（浏览器安全策略要求）

解决方案:

1. 生产环境: 部署时使用 HTTPS 协议
2. 开发环境: 使用以下任一方式：
   • 使用 localhost 或 127.0.0.1 访问
   • 配置本地 HTTPS 证书

   # 使用 localhost 启动
   npm run dev -- --host localhost

错误 3102：音频设备枚举失败

现象: 提示"音频设备枚举失败"

原因: 系统无法列出可用的音频设备

解决方案:

1. 检查麦克风是否正确连接
2. 重新插拔麦克风设备
3. 检查系统声音设置中是否识别到设备
4. Windows: 检查"设备管理器"中音频驱动是否正常
5. macOS: 检查"系统偏好设置 → 声音 → 输入"

错误 3103：用户关闭权限请求

现象: 提示"用户关闭权限请求"或"麦克风权限被拒绝"

原因: 用户点击了浏览器权限弹窗的"拒绝"按钮

解决方案:

Chrome / Edge:

1. 点击浏览器地址栏左侧的 🔒 图标
2. 找到"麦克风"权限，点击下拉菜单
3. 选择"允许"
4. 刷新页面

Firefox:

1. 点击地址栏左侧的 🔒 图标
2. 点击"连接安全"旁边的 >
3. 找到"使用麦克风"，选择"允许"
4. 刷新页面

Safari:

1. 在菜单栏选择"Safari → 设置"
2. 进入"网站"标签页
3. 点击左侧"麦克风"
4. 找到当前网站，选择"允许"
5. 刷新页面

错误 3104：设备被占用或不可读

现象: 提示"设备被占用或不可读"

原因: 其他应用正在使用麦克风

解决方案:

1. 关闭以下可能占用麦克风的应用：
   • 视频会议软件：如流、Microsoft Teams、腾讯会议、钉钉、飞书
   • 即时通讯软件：微信、QQ、Skype
   • 录音软件：Audacity、GarageBand
   • 其他浏览器标签页的语音应用
2. 检查系统任务管理器，结束占用音频设备的进程
3. Windows: 打开"设置 → 隐私 → 麦克风"，确认应用权限
4. macOS: 打开"系统偏好设置 → 安全性与隐私 → 隐私 → 麦克风"，确认浏览器权限

错误 3105：音频设备检测超时

现象: 提示"音频设备检测超时"

原因: 设备检测耗时过长（可能是网络或系统问题）

解决方案:

1. 检查网络连接是否正常
2. 关闭其他占用资源的应用
3. 稍后重试
4. 如果持续失败，尝试重启浏览器或系统

问：Safari 浏览器的特殊注意事项

Safari 不支持 Permissions API，因此 permissionState 字段可能为 undefined。

建议:

• 不要依赖 permissionState 判断权限状态
• 通过 available 字段判断设备是否可用
• 使用 error 字段判断具体错误类型

controller.emitter.on('microphone_available', result => {
    // ✅ 正确做法：使用 available 字段
    if (!result.available) {
        if (result.error === 'PERMISSION_DENIED') {
            showPermissionGuide();
        }
    }

    // ❌ 错误做法：依赖 permissionState（Safari 不支持）
    // if (result.permissionState === 'denied') { ... }
});

问：如何在 ASR 启动前自动检测设备？

使用 checkAudioDeviceBeforeStart 配置项：

const controller = await createAaaSPilotKit({
    checkAudioDeviceBeforeStart: true, // 默认为 true，启动前自动检测
    // ... 其他配置
});

// 监听检测结果
controller.emitter.on('microphone_available', result => {
    if (!result.available) {
        // ASR 启动会被自动阻止，显示错误提示
        showToast(result.userMessage);
    }
});

相关文档:

• microphone_available 事件
• checkAudioDevice() 方法
• checkAudioDeviceBeforeStart 配置

更多帮助

如果以上问题无法解决您的问题，请：

1. 查看控制台错误日志
2. 开启调试模式获取详细信息
3. 联系技术支持团队

联系方式：

• 技术支持邮箱：zhangwenxi@baidu.com、lifuxin@baidu.com、hanbowen01@baidu.com