web rts 本地混流 pushClient.startMicrophone 失败

pushClient.startMicrophone 失败是阿里云 Web RTS (Real-Time Streaming) SDK 在本地混流场景中最常见的问题。这通常不是 SDK 本身的 Bug，而是由 浏览器权限、HTTPS 协议限制、音频上下文策略 或 设备占用 导致的。

以下是详细的排查步骤和解决方案：

1. 核心原因排查 (按优先级排序)

A. 协议必须是 HTTPS (最常见原因)

现代浏览器（Chrome, Edge, Safari）出于安全考虑，严禁在非加密上下文 (HTTP) 中访问麦克风。

• 现象：代码执行到 startMicrophone 直接报错，或者 Promise 被 reject，错误信息包含 NotAllowedError 或 Permission denied。

• 例外：只有 localhost 或 127.0.0.1 允许使用 HTTP 调用麦克风。

• ✅ 解决方案：

• 如果你是在本地开发，确保访问地址是 http://localhost:端口 或 http://127.0.0.1:端口。不要用局域网 IP (如 http://192.168.1.5) 测试麦克风，必须配 SSL 证书换成 https://。

• 如果是生产环境，必须部署 SSL 证书，使用 https:// 访问。

B. 用户交互缺失 (浏览器自动播放策略)

浏览器禁止网页在没有任何用户交互（点击、触摸）的情况下自动获取麦克风权限。

• 现象：页面加载完成后立即调用 startMicrophone 失败。

• ✅ 解决方案：

• 必须将 pushClient.startMicrophone() 放在用户的点击事件回调中。

• 错误写法：

  // 页面加载直接调用 -> 必败
  window.onload = () => { pushClient.startMicrophone(); };

• 正确写法：

  document.getElementById('startBtn').addEventListener('click', async () => {
      try {
          await pushClient.startMicrophone();
          console.log('麦克风启动成功');
      } catch (e) {
          console.error('启动失败', e);
      }
  });

C. 麦克风权限被拒绝或未授权

• 现象：浏览器地址栏右侧出现“摄像头/麦克风被拦截”的图标。

• ✅ 解决方案：

1. 点击浏览器地址栏左侧的 “锁”图标 或 “设置”图标。

2. 找到 麦克风 选项，将其设置为 “允许” (Allow)。

3. 刷新页面重试。

4. 如果是 Mac OS，检查 系统设置 -> 隐私与安全性 -> 麦克风，确保你的浏览器（Chrome/Edge）有权限。

D. 音频设备被独占或不存在

• 现象：电脑上插了多个音频设备，或者会议软件（腾讯会议、Zoom）独占了麦克风。

• ✅ 解决方案：

• 关闭其他可能占用麦克风的软件。

• 检查浏览器设置中是否选择了正确的输入设备。

• 如果是虚拟机或无头服务器，可能根本没有麦克风硬件，需要虚拟音频驱动。

2. 代码层面的调试与优化

如果以上基础检查都通过了，请通过以下方式获取具体错误信息进行精准修复：

A. 捕获并打印详细错误

startMicrophone 返回的是一个 Promise，务必捕获错误：

async function startMic() {
    try {
        // 确保先 initPushClient
        await pushClient.initPushClient({
            url: 'your_rts_url',
            // 其他配置...
        });

        // 启动麦克风
        await pushClient.startMicrophone();
        
        console.log('✅ 麦克风启动成功，可以开始推流了');
        
        // 启动推流
        await pushClient.startPush(); 

    } catch (error) {
        console.error('❌ startMicrophone 失败:', error);
        
        // 根据错误类型提示用户
        if (error.name === 'NotAllowedError' || error.name === 'PermissionDeniedError') {
            alert('无法访问麦克风：请在浏览器设置中允许麦克风权限，并确保使用 HTTPS 访问。');
        } else if (error.name === 'NotFoundError' || error.name === 'DevicesNotFoundError') {
            alert('未找到麦克风设备：请检查是否连接了麦克风。');
        } else if (error.name === 'NotReadableError' || error.name === 'TrackStartError') {
            alert('麦克风被占用：请关闭其他使用麦克风的软件（如会议软件）。');
        } else {
            alert('启动失败：' + error.message);
        }
    }
}

B. 检查 SDK 版本与初始化顺序

• 顺序：必须先 initPushClient (或创建实例)，再 startMicrophone，最后 startPush。

• 版本：确保引入的是最新版的 aliyun-web-rts-sdk。旧版本可能存在兼容性 bug。

  <!-- 推荐使用阿里云 CDN 最新版 -->
  <script src="https://g.alicdn.com/de/prismplayer/2.x.x/aliyun-web-rts-sdk.min.js"></script>
  <!-- 或者检查你的 node_modules 版本 -->

C. 本地混流的特殊配置

如果你是在做本地混流（即：摄像头画面 + 麦克风声音 + 屏幕分享/本地视频文件 混合推流）：

• 确保你没有重复创建 AudioContext。

• 如果你手动获取了 navigator.mediaDevices.getUserMedia({ audio: true })，请直接将这个 stream 传给 SDK，而不是让 SDK 再去请求一次，避免冲突。

• 部分新版 SDK 支持传入 stream：查阅文档看是否支持 pushClient.setMediaStream(stream)。

3. 特殊场景排查

4. 终极调试大招

如果依然无法解决，请在浏览器控制台 (F12) 执行以下原生 JS 代码，测试浏览器本身是否正常：

// 在 Console 中直接运行
navigator.mediaDevices.getUserMedia({ audio: true })
  .then(stream => {
      console.log('✅ 原生 API 测试成功，麦克风正常', stream);
      // 记得停止轨道释放资源
      stream.getTracks().forEach(track => track.stop());
  })
  .catch(err => {
      console.error('❌ 原生 API 测试失败', err);
  });

• 如果原生 API 也失败：说明是浏览器、操作系统或硬件问题，与阿里云 SDK 无关。

• 如果原生 API 成功，但 SDK 失败：说明是 SDK 调用时机、版本或配置问题。

总结

绝大多数 startMicrophone 失败都是因为 没有用 HTTPS (除 localhost 外) 或者 没有在点击事件中调用。请优先检查这两点！