# 如何处理 RTC 小程序 SDK 常见问题? (/zh-CN/reference/faq/integration/mini_program) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文汇总 RTC 小程序 SDK 常见问题和解决方法。 ## 功能类问题处理 [#功能类问题处理] ### 推流/拉流处理 [#推流拉流处理] 推流/拉流处理可以参考或直接使用 [GitHub 上开源代码](https://github.com/AgoraIO/Agora-Miniapp-Tutorial)。 ### 退后台处理 [#退后台处理] 可以通过设置小程序的 live-pusher 组件中的 waiting-image 属性来处理。设置后,推流端退到后台时,可以推送静态图片来维持推流,其他端会收到本端预设的 waiting-image 图片来代替视频流。 除非通过一些方式 (例如后台播放背景音乐),小程序会在某些场景下断开 websocket 或者 rtmp 连接,例如点击右上角按钮将程序退到后台。这种情况下,若回到前台后收到 error code 904 或 501,则应使用 SDK 进行重连,具体方法请参考 重新加入频道 rejoin 中的描述。 ### 只启用音频 [#只启用音频] 如需只启用小程序的音频功能,不需要发送视频,你直接使用微信小程序的接口处理即可。在小程序的 live-pusher 组件中,通过设置 enable-camera 来实现开启/关闭摄像头。详见 [小程序 live-pusher 组件文档](https://developers.weixin.qq.com/miniprogram/dev/component/live-pusher.html)。 ### 播放背景音乐 [#播放背景音乐] 在某些社交娱乐场景中,小程序会需要播放背景音乐。微信小程序的背景音频需要用微信小程序的原生 API 来集成实现,声网微信小程序 SDK 无法建立音频播放器。 你可以通过 [`wx.getBackgroundAudioManager()`](https://developers.weixin.qq.com/miniprogram/dev/api/media/background-audio/wx.getBackgroundAudioManager.html) 接口获取全局唯一的背景音频管理器,并调用 [`BackgroundAudioManager`](https://developers.weixin.qq.com/miniprogram/dev/api/media/background-audio/BackgroundAudioManager.html) 类提供的接口来管理背景音频。 ### 采样率 [#采样率] 小程序 SDK 只支持 48 kHz 采样率。集成时,请在 live-pusher 组件中将音质设为高音质,以表示采样率为 48 kHz: ```javascript audio-quality = "high" ``` 如果设置其他采样率,远端用户可能无法听到小程序用户的声音。 ### 日志 [#日志] 集成小程序 SDK 时,你可以调用如下 API 实现上传,保存和打开日志: * 上传日志: 如果你使用 v2.6.0 或更高版本的小程序 SDK,无需自己保存日志,可通过 [`uploadLogs`](/zh-CN/api-reference/rtc/mini-program/interfaces/log#uploadlogs) API 上传日志。 * 保存日志: 如果想要获取日志,需要将 text 保存在一个文件中。如果需要排查问题,可以将出现问题时间段的日志提供给声网支持人员。 ```javascript // text 为字符串形式。 AgoraMiniappSDK.LOG.onLog = (text) => { Utils.log(text); }; ``` * 打开日志: ```javascript AgoraMiniappSDK.LOG.setLogLevel(-1); ``` ### 与 Native 互通 [#与-native-互通] 频道中有小程序 SDK 和 Native SDK 时,可以选择如下一种方式实现互通: - Native 端在直播模式下,将用户角色设置为 `AgoraClientRoleBroadcaster` = 1:主播,实现互通 - Native 端在直播模式下,不设置用户角色为主播,也可以接收到小程序端的流,实现互通 小程序和 Native 互通时,Native 端视频画面可能出现上下颠倒。该问题可能是由于 Native SDK 中的 `setVideoEncoderConfiguration` 设置的方向模式 `orientationMode` 为 `ORIENTATION_MODE.ORIENTATION_MODE_ADAPTIVE` 导致的。解决方法是,将方向模式改成 `ORIENTATION_MODE.ORIENTATION_MODE_FIXED_PORTRAIT` 就可以解决问题。 ### 与 Web 互通 [#与-web-互通] 小程序和 Web 互通时,可能出现 Web 端可以看到小程序的视频,但小程序看不到 Web 端的视频。该问题可能是由于编解码格式不被支持导致的。 Web 与小程序互通时,小程序端只支持 H264 模式的编码,不支持 VP8。将 Web SDK 的 `index.html` 文件修改为如下设置即可: ```javascript client = AgoraRtc.createClient({mode: "live", codec: "h264"}); ``` ### live-pusher 中的 src [#live-pusher-中的-src] 客户端调用 client.publish 方法后,会回调一个以 rtmp 开头的临时地址,这个地址就分别是 live-player 和 live-pusher 组件中的 rtmp 播放地址 和 rtmp 推流地址。你可以将其填入 src 字段。 ### WebView 中调用接口 [#webview-中调用接口] 微信小程序可以在 WebView 网页中调用声网 Web SDK 4.x 的接口,详见 [Web SDK 4.x API 文档](/zh-CN/api-reference/rtc/web/overview)。 ### view 标签 [#view-标签] 你可以使用小程序的 `cover-view` 标签覆盖在用于实时音视频播放和录制的 `live-player` 和 `live-pusher` 的组件。详见[微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/component/cover-view.html)。 ## 通用类问题排查 [#通用类问题排查] ### 闪退 [#闪退] 这个问题可能是因为启用了其它 Websocket,但没有开启验证 Https 引起的。如需启用其它的 Websocket,请查看**本地设置**,不要勾选“不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”。 ### 初始化失败 [#初始化失败] 通常,客户端初始化失败,会伴随着错误码 901 或 903,处理方法如下: - 901:出现错误码 901 绝大部分原因是没开小程序的服务权限,或没有配置域名,或 uid 参数格式不正确(uid 必须为整型)。请参考快速开始中的[准备开发环境](/zh-CN/realtime-media/rtc/get-started/quick-start)完成设置后再尝试; - 903:这个错误通常是网络原因引起的;也可能是因为鉴权失败,如没有填 Token,或 Token 无效导致的。请检查并填入有效的 Token 进行尝试。 ### 错误码排查 [#错误码排查] 小程序 SDK 在调用 API 或运行时,可能会返回一个错误码对象,也可能会返回一个错误码。详细可以参考[错误码和警告码](/zh-CN/realtime-media/rtc/reference/error-code) 进行排查。 ### 编译报错 [#编译报错] 编译小程序时,出现如下图所示的 `MiniProgramError: @babel` 相关报错。 ![小程序编译报错](https://web-cdn.agora.io/docs-files/1675663879303) 问题原因:小程序使用了符合 ES6+ 语法标准的代码,但低版本手机系统只能编译符合 ES5 语法标准的代码,所以在低版本手机系统中编译小程序时会出现该问题。需要将代码编译成 ES5 才能真机调试。 解决方案:你可以尝试在微信开发者工具中开启[将 JS 代码编译成 ES5](https://developers.weixin.qq.com/miniprogram/dev/devtools/codecompile.html)功能,再重新编译程序。