声网 SDK 故障排查工具使用指南
做开发这些年，我见过太多同事在深夜盯着控制台日志抓耳挠腮的场景。说实话，音视频 SDK 的调试确实不像普通业务逻辑那样直观——你看不见数据在网络里怎么跑，也摸不着音视频流在编码解码过程中出了什么岔子。这篇文章我想跟你聊聊声网 sdk 提供的那些故障排查工具，希望能帮你在遇到问题时少走一些弯路。
在正式讲工具之前，我们先建立一个共识：音视频通话的问题通常可以归为几大类——连接层面的问题（比如打不通、频繁断线）、音视频质量的问题（卡顿、画面糊、有回声）、还有就是设备适配的问题（某些机型或系统版本表现异常）。声网的排查工具基本也是围绕这几个方向设计的，接下来我会逐一介绍。
控制台日志：最基础却最重要的一环
很多人一上来就想用各种高级工具，反而忽视了最基础的日志分析。我建议你在排查问题时，第一步先打开声网的详细日志输出。在 SDK 的初始化配置里，有一个 logLevel 参数，默认可能是 INFO 级别，建议临时改成 DEBUG 级别，这样能看到更详细的内部状态信息。
日志里面有几个关键字段你一定要特别留意。比如 network_quality 这个标签，它会显示当前的丢包率、延迟和抖动情况。如果丢包率长期超过 5%，那基本可以肯定是网络问题。还有 rtc_engine_state 这个状态机，它能告诉你当前 SDK 处于什么阶段——是正在初始化、加入频道、还是已经正常通话中。有时候问题很简单，就是状态机卡在某个中间态没动。
另外，声网的日志会记录每一次重连的时间和原因。如果你在日志里看到频繁的 reconnect 关键字，那就要检查一下网络切换场景了——比如 WiFi 和 4G 之间的切换，很多应用在这时候会出现短暂的断连。
实时数据监控：把问题可视化
光看日志有时候还是不够直观，特别是当你想知道整个通话过程中网络质量的变化趋势时。这时候声网提供的 回调数据监控 就派上用场了。
SDK 里有一个 onNetworkQuality 的回调函数，它会每隔几秒钟上报一次当前的网络质量等级。这个等级用 0 到 6 的数字表示，0 代表最好，6 代表最差。你可以在自己的监控面板上把这个数据画成折线图，这样一眼就能看出问题发生在哪个时间点。
还有一个很实用的回调是 onRemoteVideoStats 和 onRemoteAudioStats，它们会告诉你远端的视频帧率、分辨率、码率以及音频的丢包率等关键指标。当你发现画面卡的时候，可以先看看远端的帧率是不是正常；如果帧率没问题但画面还是卡，那可能是你自己的解码或者渲染环节有问题。
核心监控指标一览
| 指标名称 | 含义说明 | 正常范围参考 |
| packetsLost | 丢包数量（音频或视频） | 通话全程丢包率应低于 3% |
| jitter | 网络抖动值（毫秒） | 低于 30ms 为优，超过 100ms 明显卡顿 |
| rtt | 往返延迟（毫秒） | 国内建议低于 100ms，跨国场景可放宽至 200ms |
| frameRate | 视频帧率 | 普通场景 15fps 起步，高清场景建议 25fps 以上 |
| bitrate | 视频码率（kbps） | 根据分辨率和帧率动态调整，720p 建议 1000-1500kbps |
我个人的经验是，当你发现通话质量下降时，先快速扫一眼这些核心指标，通常能帮你锁定大概的方向。比如丢包率高和网络相关，帧率低可能和编码配置或设备性能有关，而只有延迟高但其他指标都正常，那可能是服务器节点选择的问题。
声网自带的诊断工具箱
除了 SDK 内部的回调，声网还提供了一些独立的诊断工具，我觉着挺好用的，这里给你介绍一下。
Pre-call 检测：在正式通话前摸清底细
这个功能我强烈建议在用户点击"开始通话"之前调用。它会做一系列的预检查，包括但不限于：设备权限是否正常、网络连通性如何、是否能连接到声网的服务器、编码解码能力是否支持当前配置。
具体来说，startLastmileProbeTest 这个方法会先探测你的上行网络质量，然后模拟一个很小码率的视频流来测试下行质量。整个过程大概需要 30 秒左右，探测结束后会给你一份详细的报告，告诉你当前网络环境适合什么样的通话质量——标清、高清还是超清。
这个工具特别适合在弱网环境下给用户一个合理的预期管理。你可以在 UI 上显示"当前网络质量较差，已自动调整为流畅模式"这样的提示，让用户知道是网络问题而不是你的应用有问题。
设备管理器：排查硬件相关问题
有时候问题出在设备层面——麦克风权限被系统回收了、摄像头被其他应用占用了、或者某个型号的手机就是有兼容性问题。声网的 DeviceManager 提供了枚举设备、检测设备状态的能力。
你可以通过 getCameraDevices 获取当前可用的摄像头列表，然后检查你想使用的那一个是否在列表里。更重要的是，SDK 会在设备状态异常时触发相应的回调，比如 onCameraReady 和 onCameraUnready，你可以监听这些事件来及时发现问题。
还有一个我常用的技巧是调用 setCameraMute 切换几下来测试摄像头响应是否正常。如果切换没反应，那基本可以确定是设备层的问题，而不是你的业务逻辑有问题。
常见问题场景与排查思路
聊完了工具，我们来实战一下，说几个我遇到过的典型问题场景。
场景一：加入频道超时
这个问题我见过最多次，也最让人头疼。首先你得分清楚是网络不通还是服务器连接不上。如果 SDK 触发了 onJoinChannelFailed 回调，错误码是 1 到 10 之间的，通常是网络层面的问题；如果是 17 或 18，那可能是 App ID 配置错了。
我建议的排查顺序是这样的：先确认 App ID 和 Token 是否正确，尤其是 Token 的有效期；然后检查防火墙设置，声网的服务器需要使用特定的端口范围；如果是在公司网络环境下，最好让运维同事帮忙确认有没有做流量限制；最后可以换个网络环境测试，比如用手机热点试试。
场景二：自己能听到自己的声音（回声）
回声问题虽然不致命，但体验极差。解决这个问题首先要理解回声产生的原理——扬声器播放的声音被麦克风重新采集进去了。声网 SDK 默认是开启 AEC（回声消除）的，但如果你的应用有特殊的音频路由需求，比如使用蓝牙耳机或者外接设备，可能需要手动调整一些参数。
排查回声问题的时候，建议先用 setEnableAudioVolumeIndication 打开音量回调，看看在没人说话的时候，麦克风输入的音量是不是异常高。如果是，那可能是你的采集音量设置得太大；如果不是，那可能要检查一下播放设备的选择，是否存在声音泄漏到麦克风的问题。
场景三：特定机型问题
安卓的碎片化问题大家都懂，总有一些奇奇怪怪的兼容性问题。这种情况下，声网的日志就特别重要了。你需要关注 onError 和 onWarning 回调里的错误码和警告码。
比如说错误码 1002，通常是显卡或编解码器不支持当前的视频配置。你可以在官网的文档里查到每个错误码的含义和常见的解决办法。如果日志里显示的是编解码器初始化失败，你可以尝试换一种编码格式或者降低分辨率来规避这个问题。
还有一种情况是某些机型的摄像头会强制旋转 90 度或者 180 度，这时候你需要用到 setCameraZoomFactor 和相关的旋转设置接口来修正画面方向。
写在最后
故障排查这件事，说白了就是建立一套系统的思维框架，然后不断积累经验。声网提供的这些工具和方法论，个人觉着已经覆盖了大部分常见场景。但实际开发中，你可能会遇到一些很奇葩的问题，比如用户安装了某个安全软件把 SDK 的网络权限禁用了，或者手机开了省电模式限制了后台活动。
我的建议是，在应用里增加一个"诊断模式"的入口，让用户可以把设备信息、网络状态、日志文件一键分享给你。这样遇到问题的时候，你不用一遍遍问用户"你网络怎么样""你手机什么型号"，直接看数据就行。
音视频这条路挺好玩的，虽然坑多，但每解决一个问题都是实实在在的成就感。希望这篇文章能对你有帮助。如果有什么问题，也欢迎在开发者社区里交流。
