# 浏览器兼容性和已知问题 (/zh-CN/realtime-media/rtc/reference/browser-compatibility)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" />
声网 Web SDK 是一款基于 WebRTC 技术的实时音视频 SDK，因此 WebRTC 技术的浏览器兼容性决定了声网 Web SDK 的浏览器兼容性。本文介绍声网 Web SDK 支持在哪些浏览器中使用。

<a id="desktop"></a>
## 桌面端 [#桌面端]

Web SDK 在桌面端的 Chrome、Firefox、Safari、Edge 等浏览器上的支持度较好。为保证最佳的用户体验，声网建议在最新版本的操作系统中使用上述浏览器的最新版本：

- 下载 [Chrome 官方最新版本](https://www.google.com/intl/zh-CN/chrome/)。
- 下载 [Firefox 官方最新版本](https://www.mozilla.org/firefox/new/)。
- 下载 [Edge 官方最新版本](https://microsoft.com/edge)。
- 下载 [Safari 官方最新版本](https://support.apple.com/en-hk/HT201541)。

### 兼容性 [#兼容性]

下文列出了浏览器的最低版本要求。为获得更好的体验，声网推荐你使用最新版本的浏览器。

<Tabs defaultValue="mac" groupId="operating-systems" persist>
<TabsList>
  <TabsTrigger value="mac">macOS</TabsTrigger>
  <TabsTrigger value="win">Windows</TabsTrigger>
  <TabsTrigger value="chrome">ChromeOS</TabsTrigger>
</TabsList>

<TabsContent value="mac">

| 浏览器                       | 浏览器版本要求  | 接收音视频流 | 发布音视频流 | 屏幕共享 |
| :--------------------------- | --------------- | :----------- | :----------- | -------- |
| Chrome                       | 65 或以上版本   | ✔         | ✔         |    ✔   |
| Firefox                      | 69 或以上版本   | ✔         | ✔         |    ✔  |
| Safari                       | 11 或以上版本   | ✔         | ✔         |    ✔ （需要 Safari 13 或以上版本）     |
| Edge                         | 无明确信息   | ✔         | ✔         |    ✔   |

</TabsContent>

<TabsContent value="win">

| 浏览器                       | 浏览器版本要求  | 接收音视频流 | 发布音视频流 | 屏幕共享 |
| :--------------------------- | --------------- | :----------- | :----------- | -------- |
| Chrome                       | 65 或以上版本   | ✔         | ✔         |    ✔   |
| Firefox                      | 69 或以上版本   | ✔         | ✔         |    ✔  |
| Edge                         | 80 或以上版本   | ✔         | ✔         |    ✔   |

</TabsContent>

<TabsContent value="chrome">

| 浏览器             | 浏览器版本要求  | 接收音视频流 | 发布音视频流 | 屏幕共享 |
| :----------------- | --------------- | :--- | :--- | -------- |
| Chrome             | 89 或以上版本   | ✔ | ✔ |   ✔    |

</TabsContent>
</Tabs>

<a id="desktop-issues"></a>
### 已知问题和限制 [#已知问题和限制]

由于各平台和应用内置浏览器的实现方式各不相同，导致支持的 Web SDK 功能也可能有所不同，因此会存在已知问题和已知限制：

- 已知问题：由特定浏览器版本的 Bug 所造成的问题。针对已知问题，声网提供规避方案。
- 已知限制：由于浏览器自身存在问题，Web SDK 无法支持的 API 或功能。

<Accordions>
<Accordion title="Chrome 浏览器已知问题">

- 在 Windows 系统上，Chrome 122 及以上版本使用 Web SDK 进行窗口屏幕共享时，若切换到全屏幻灯片放映模式，屏幕共享的画面在接收端会停留在非全屏状态，无法显示全屏后的幻灯片页面。

  解决方案：重新分享整个屏幕而非特定窗口。

- 从 Chrome 117 起，Web SDK 4.9.3 及以下版本中不再支持 `getStats()` 方法，调用该方法时返回值全部为 0。

  问题原因：旧版 `getStats()` WebRTC API 将从 Chrome 117 中移除，详见 [Chrome 官方说明](https://developer.chrome.com/blog/getstats-migration)。

  解决方案：升级到更高版本的 Web SDK。

- 在所有使用 AMD 芯片和部分使用 Intel 芯片的 Windows 设备上，Chrome 使用 H.264 编码时，发送码率可能达不到设定值。

  解决方案：使用 VP8 编码或者尝试关闭硬件加速。

- macOS 上 Chrome 84 存在缺陷，采用 H.264 格式进行编码时， WebRTC 有概率出现帧率突然下降导致图像卡顿。详见 Google 官方说明 [Issue 1088650](https://bugs.chromium.org/p/chromium/issues/detail?id=1203206&can=2&q=webrtc%20drop%20component%3ABlink%3EWebRTC%3EVideo) 和 [Issue 12704](https://bugs.chromium.org/p/webrtc/issues/detail?id=12704#c3)。

  解决方案：建议你在 macOS 上 Chrome 84 及以后版本中使用 VP8 ，直至 Google 修复该缺陷。

- 特定场景下 Chrome 的回声消除 (AEC) 失效。

  问题原因：如果对接收的远端音频流进行了额外处理（比如空间音频），AEC 无法获取到参考信号，详见 Chrome 官方说明 [Issue 687574](https://bugs.chromium.org/p/chromium/issues/detail?id=687574)。

  解决方案：建议用户戴上耳机，避免使用扬声器。如果需要使用扬声器，请[联系技术支持](https://ticket.shengwang.cn/)。

- 在部分 Windows 设备上选择音频采集设备为立体声混音，远端用户将听不到声音。

  解决方案：建议避免选择立体声混音作为音频采集设备。

- 在 Windows 设备上使用 `deviceId` 为 `"default"` 或 `"communications"` 的麦克风时，如果插入新的麦克风再拔出，原麦克风的采集可能中断。

  解决方案：建议避免使用 `deviceId` 为 `"default"` 或 `"communications"` 的麦克风。

</Accordion>

<Accordion title="Safari 浏览器已知问题和限制">

- 在 macOS Ventura 的 Safari 16.2 和 16.3 上通过 `createScreenVideoTrack` 创建屏幕共享视频轨道后，调用 `setEncoderConfiguration` 修改该轨道的视频分辨率时可能会出现绿屏。

  问题原因：WebKit 的功能回退，详见 [Bug 254652](https://bugs.webkit.org/show_bug.cgi?id=254652)。

  解决方案： 升级至 macOS Ventura 13.3、Safari 16.4 版本。

- Safari 16.1 上调用 `createScreenVideoTrack` 方法时，如果在 `encoderConfig` 中传入自定义的视频编码配置，该方法会调用失败。

  问题原因：WebKit 的屏幕共享功能有回退，详见 [Bug 247310](https://bugs.webkit.org/show_bug.cgi?id=247310)。

  解决方案：在 `encoderConfig` 中通过 `ScreenEncoderConfigurationPreset` 传入 SDK 内置的编码配置。调用示例：

  ```Javascript
  AgoraRTC.createScreenVideoTrack({encoderConfig:'720p_1'})
  ```

- Safari 17.2 上使用 Web SDK 存在无法正常切换到小流的问题。
- Safari 17 上调用 `getDisplayMedia` 时，对屏幕共享视频流的约束设置不生效，导致视频模糊。
- Safari 15.4 及以上版本如果将本地音频轨道的采样率设为 32000 Hz，本地音频轨道会终止（即触发 `LocalAudioTrack.on('track-ended')` 事件）。
- Safari 15.1 上使用 H.264 编码时，[MediaStreamTrack.enabled](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/enabled) 设为 `false` 会导致页面崩溃。
- Safari 14.0.1 和 14.2 上音频可能断断续续。
- Safari 13 的用户可能听不到远端用户的声音。
- Safari 12.1 及之前版本仅支持 H.264 编解码。
- Safari 11 只支持 480P 及以上分辨率。
- 在 Safari 上切换到其它标签页后，新订阅的远端音频流不会自动播放，需要切回 SDK 所在的标签页才开始播放。
- Safari 无法获取输出设备信息，因此不支持 `getPlayoutDevices` 和 `setAudioOutput` 这两个方法。
- Safari 上如果调用 `setAudioFrameCallback` 添加了原始音频数据回调，调用 `setAudioFrameCallback(null)` 后 Safari 的音频图标不会消失。原因是 Safari 的 [ScriptProcessorNode](https://developer.mozilla.org/zh-CN/docs/Web/API/ScriptProcessorNode#%E6%96%B9%E6%B3%95) 对象调用 `disconnect` 方法有问题。
- Safari 上调用相关方法获取质量相关统计数据时，多个字段的值为 0。例如调用 `getLocalAudioStats` 获取本地音频轨道的质量相关信息时，`sendPacketsLost` 字段值为 0。
- 在部分使用 Intel 芯片的 Mac 设备的 Safari 浏览器上，调用 `enableDualStream` 开启 H.264 编码的视频双流模式时，小流与大流分辨率比率低于 1/4 可能会导致系统卡顿。
- 如果 Safari 没有打开**自动播放**（如下图所示），直接播放音视频流会听不到声音，必须在播放前调用 `navigator.mediaDevices.getUserMedia` 方法获取设备权限。
  ![img](https://web-cdn.agora.io/docs-files/1591078696865)

</Accordion>

<Accordion title="Firefox 浏览器已知问题和限制">

- Firefox 138 版本接收端黑屏问题

  问题描述：用户在使用 Firefox 138 浏览器进行实时音视频互动时，接收端可能出现视频黑屏现象。

  问题原因：这个问题是由 Firefox 浏览器自身版本回退导致。Firefox 138 版本进行了临时性调整，导致视频流解码失败。此问题属于浏览器厂商的兼容性变更，详见：https://bugzilla.mozilla.org/show_bug.cgi?id=1965831 。

  规避方案：声网目前已经通过配置下发临时处理该问题。对于一些无痕模式的用户，配置下发可能无效，需要修改集成。建议你[联系技术支持](https://ticket.shengwang.cn)。

- 使用 Windows 设备在 Firefox 98 版本上发送 H.264 视频流时，接收端无法在订阅后立即收到关键帧，导致出图时间变慢。
- Firefox 上使用 Web SDK 时与某些设备互通时，Firefox 端看其他端的视频画面会发生旋转。
- Firefox 只支持视频帧率设为 30 fps。
- Firefox 上不支持设置音频编码码率。
- 在部分设备上 Firefox 设置视频编码配置不生效，目前已知有此问题的设备如下：
  - MacBook Pro (13-inch, 2016, Two Thunderbolt 3 ports)
  - Windows 10 (MI)
- 在使用 Apple M1 芯片的 Mac 设备上 Firefox 不支持 H.264 编解码，详见 [Firefox 官方说明](https://bugzilla.mozilla.org/show_bug.cgi?id=1686470)。
- Firefox 上不支持获取 `codecType`、`sendFrameRate` 和 `captureFrameRate`。
- Firefox 上 Web SDK 最低视频码率的默认设置不生效。
- Firefox 上不支持 H.264 视频流的 SEI 信息发送功能。

</Accordion>

<Accordion title="桌面端其它已知限制">

- Chrome 81 及以上版本、Safari 和 Firefox 浏览器需要在获得媒体设备权限后才能获取设备 ID，详见[为什么在 Chrome 81 浏览器上无法获取设备 ID？](/zh-CN/realtime-media/rtc/reference/browser-compatibility)该限制影响 `getMicrophones`、`getCameras`、`getPlaybackDevices` 方法。
- `setPlaybackDevice` 方法仅支持 Chrome 浏览器，其他浏览器调用将会抛出 `NOT_SUPPORTED` 错误。
- `setOptimizationMode` 方法以及 `CameraVideoTrackInitConfig`、`ScreenVideoTrackInitConfig` 和 `CustomVideoTrackInitConfig` 类中的 `optimizationMode` 字段仅支持 Chrome 浏览器。
- 调用 `createScreenVideoTrack` 开启屏幕共享有以下限制：
  - Chrome 要求 58 或以上版本。如果 Chrome < 72，需要先安装声网提供的 Chrome 屏幕共享插件并获取插件的 `extensionId`，在创建轨道时填入 `extensionId`。如果 Chrome ≥ 72，则直接调用 `createScreenVideoTrack`。
  - Firefox 要求 56 或以上版本。Firefox 在 Windows 平台不支持 `application` 模式。
  - Windows 10+ 平台上的 Edge 要求 80 及以上版本。
  - Safari 要求 13 或以上版本。在 Safari 上屏幕共享默认共享整个显示器屏幕，不可选择共享哪些内容。
  - 共享音频功能（`createScreenVideoTrack` 中的 `withAudio` 参数）仅支持 Chrome 74 及以上版本。Windows 平台支持在共享整个屏幕和共享 Chrome 标签页时分享音频，不支持在共享应用窗口时分享音频。macOS 平台仅支持在共享 Chrome 标签页时分享音频。

</Accordion>
</Accordions>

<a id="mobile"></a>
## 移动端 [#移动端]

:::info[信息]
自 4.6.0 起，Web SDK 优化了在移动端浏览器上的体验。如果你想提升在移动端的体验，声网强烈建议你升级到 4.x 最新版本。
:::

### 兼容性 [#兼容性-1]

下文列出的版本为浏览器的最低版本要求。

<Tabs defaultValue="android" groupId="operating-systems" persist>
<TabsList>
  <TabsTrigger value="android">Android</TabsTrigger>
  <TabsTrigger value="ios">iOS</TabsTrigger>
  <TabsTrigger value="HarmonyOS">HarmonyOS</TabsTrigger>
</TabsList>

<TabsContent value="android">

Android 支持自研 WebView 或引入第三方 WebView，不同设备、不同应用的 WebView 可能实现不同，因此对 Web SDK 的支持与应用版本和设备硬件有关。

| 浏览器                                    | 浏览器版本要求      | 接收音视频流 | 发布音视频流 | 屏幕共享 |
| :---------------------------------------- | ------------------- | :--- | :--- | -------- |
| Chrome                                    | 78 或以上版本       | ✔ | ✔ | ✘         |
| 微信内置浏览器 | 微信 7.0.20 或以上版本 | ✔ | ✔ | ✘         |
| 企业微信内置浏览器                        | 企业微信 3.1.6 或以上版本            | ✔ | ✔ | ✘         |

</TabsContent>

<TabsContent value="ios">

iOS 只支持系统 WebView，因此对 Web SDK 的支持只与 iOS 系统版本有关。

**iOS 版本 ≥ 12.2 且 < 14.3**

| 浏览器             | 浏览器版本要求      | 接收音视频流 | 发布音视频流 | 屏幕共享 |
| :----------------- | ------------------- | :--- | :--- | -------- |
| Safari             | 与 iOS 系统版本对应                  | ✔ | ✔ | ✘         |
| Chrome             | 无明确信息       | ✔ | ✘     |    ✘     |
| 微信内置浏览器     | 微信 8.0.13 或以上版本 | ✔ | ✘     |   ✘       |
| 企业微信内置浏览器 | 企业微信 3.1.15 或以上版本①           | ✔ | ✘     |     ✘     |

**iOS 版本 ≥ 14.3**
| 浏览器             | 浏览器版本要求      | 接收音视频流 | 发布音视频流 | 屏幕共享 |
| :----------------- | ------------------- | :--- | :--- | -------- |
| Safari             | 与 iOS 系统版本对应                  | ✔ | ✔ | ✘         |
| Chrome             | 92 或以上版本       | ✔ | ✔ |  ✘       |
| 微信内置浏览器     | 微信 8.0.13 或以上版本 | ✔ | ✔ |    ✘     |
| 企业微信内置浏览器 | 企业微信 3.1.15 或以上版本①         | ✔ | ✔ |   ✘      |

:::info[信息]
① 在企业微信内直接打开链接无法互通。需要开启麦克风和相机权限后，重启企业微信，打开链接刷新页面才能正常互通。
:::

</TabsContent>

<TabsContent value="HarmonyOS">

目前仅 Mate 60 Pro 机型支持升级至 HarmonyOS NEXT 5.0 或以上版本的鸿蒙系统，你需要在该类设备上使用华为浏览器，才能使用 Web SDK 接收和发布视频流。

| 浏览器                                    | 浏览器版本要求      | 接收音视频流 | 发布音视频流 | 屏幕共享 |
| :---------------------------------------- | ------------------- | :--- | :--- | -------- |
| 华为浏览器                                    |  无明确信息     | ✔ | ✔ | ✘         |

</TabsContent>
</Tabs>

### 已知问题和限制 [#已知问题和限制-1]

由于各平台和应用内置浏览器的实现方式各不相同，导致支持的 Web SDK 功能也可能有所不同，因此会存在已知问题和已知限制：

- 已知问题：由 iOS/Android/HarmonyOS 平台特定浏览器/机型的 Bug 所造成的问题。针对已知问题，声网提供规避方案。
- 已知限制：由于 iOS/Android/HarmonyOS 平台的问题，Web SDK 无法支持的 API 或功能。

#### 已知问题 [#已知问题]

<Tabs defaultValue="android" groupId="operating-systems" persist>
<TabsList>
  <TabsTrigger value="android">Android</TabsTrigger>
  <TabsTrigger value="ios">iOS</TabsTrigger>
  <TabsTrigger value="harmonyos">HarmonyOS</TabsTrigger>
</TabsList>

<TabsContent value="android">

<Accordions>
<Accordion title="Android 12: Chrome 上使用 WebRTC 视频硬件编码可能会导致花屏">

**影响范围**：部分安装了 Android 12 的设备，如 Pixel 3 和 Pixel 4，且使用 Chrome 浏览器或 Chromium 内核浏览器 97 或以下版本。

**问题描述**：在 Android 12 上使用 Chrome 浏览器或 Chromium 内核浏览器 97 或以下版本，如果默认开启 WebRTC `H264` 或 `VP8` 视频硬件编码，可能会导致花屏。

**问题原因**：该问题是由 Chromium WebRTC 模块视频编码回退导致，详见 [Chromium issue 1237677](https://bugs.chromium.org/p/chromium/issues/detail?id=1237677)。

**规避方案**：Chrome 97 已修复该问题，建议用户升级至 Chrome 97 或以上版本。

</Accordion>

<Accordion title="Android Chrome 119 上回声消除失效">

**影响范围**：Android Chrome 119.0.6045.67 版本。

**问题描述**：用户 A 使用该版本的 Android Chrome 加入频道，用户 B 使用其它浏览器加入频道，如果用户 A 不佩戴耳机，用户 B 会听到自己的回声。

**问题原因**：该问题由 [Chromium issue](https://bugs.chromium.org/p/chromium/issues/detail?id=1501352) 导致。

**规避方案**：Android Chrome 119 最新版本已修复该问题，建议用户升级至 119.0.6045.134 或以上版本。

</Accordion>

<Accordion title="Android Chrome 上视频发送码率无法达到 Web SDK 的预设值">

**影响范围**：部分 Android 设备，如部分小米及 One Plus 机型。

**问题原因**：可能是因为硬件编码导致特定视频编码帧率下码率无法达到预设值。

**规避方案**：大部分情况下，视频编码帧率为 15 fps 时，码率会过低，而帧率为 30 fps 时码率则相对较高。因此声网建议遇到码率问题时，尝试将帧率设为 30 fps。请注意，将帧率设为 30 fps 可能会带来性能问题。

</Accordion>

<Accordion title="Android Chrome 上创建两个参数不同的摄像头视频轨道出现报错">

**问题描述**：Android Chrome 上调用 `createCameraVideoTrack` 创建两个参数不同的视频轨道，浏览器报错 `NotReadableError: Could not start video source`。

**影响范围**：大部分 Android 设备。

**规避方案**：先调用 `close` 或 `setEnable(false)` 释放已有的视频轨道，再创建新的视频轨道。

</Accordion>

<Accordion title="微信浏览器中视频无法自动播放">

**影响范围**：使用 Chromium 89 内核的微信浏览器。

**问题描述**：微信浏览器中视频无法自动播放。并且当用户通过手势（点击、触摸）恢复播放后，下一次视频仍然无法自动播放。

**问题原因**：可能是微信浏览器对自动播放的行为处理有异常，与其他浏览器的行为不一致。

**规避方案**：参考以下步骤规避此问题：

1. 升级至 Web SDK 4.6.0 或以上版本。
2. 监听 `AgoraRTC.onAutoplayFailed` 事件。在此事件中，引导用户点击页面，恢复播放：

    ```javascript
    AgoraRTC.onAutoplayFailed = ()=>{
        document.alert('请点击页面后恢复播放');
    }
    ```

</Accordion>

<Accordion title="本地用户佩戴蓝牙耳机，开始发送音频流后就无法听到远端音频">

**影响范围**：部分小米及 One Plus 机型。

**问题描述**：如果本地用户佩戴蓝牙耳机，在通话过程中通过蓝牙耳机采集本地音频且发送音频流后，有概率会无法收听到远端用户的声音。

**问题原因**：可能是由于 Chromium 在蓝牙设备协议 (Bluetooth Profile) 切换后会产生音频异常。

**规避方案**：声网建议你在业务层面添加提示，告知用户使用蓝牙耳机可能出现无声问题。

</Accordion>

<Accordion title="本地用户在发送音频流时，切换音频路由不生效">

**影响范围**：Android 设备上使用 Chromium 为内核的浏览器。

**问题描述**：本地用户在发送音频流时，如果从扬声器切换到蓝牙耳机，远端用户的音频仍然通过扬声器播放。

**问题原因**：Android 设备的音频路由全部由 Android 操作系统分配，Chromium 不能修改。详见 [Chromium issue 1317548](https://bugs.chromium.org/p/chromium/issues/detail?id=1317548&q=bluetooth&can=2)。

</Accordion>

<Accordion title="某些 Android 机型特有的问题">

- 在搭载**联发科芯片**的设备上无法使用 H.264 编码在 Chrome 浏览器中发送视频流。
- 在搭载**华为海思麒麟芯片**的设备上，Android Chrome 88 以下版本上，无法使用 H.264 编码发送视频流。
- 在 **OnePlus 6**上使用 Chrome 浏览器接收远端视频流期间熄灭屏幕，可能会导致视频流冻结。
- **鸿蒙系统**不支持发 180p 的视频流。
- 在部分 OPPO 机型（如 Reno4 和 A11）上运行 Android 11 系统时，由于不支持 WebRTC，导致出现黑屏和无声现象。

</Accordion>
</Accordions>

</TabsContent>

<TabsContent value="ios">

<Accordions>
<Accordion title="iPhone 14 系列手机音频采集失败">

**影响范围**：运行 iOS 16 系统的所有 iPhone 14 系列手机。

**问题原因**：iPhone 14 系列手机上 WebKit 的 WebAudio 相关功能有回退，导致 WebAudio 启用后音频采集相关功能异常。详见 [WebKit Bug 246019](https://bugs.webkit.org/show_bug.cgi?id=246019)。

**规避方案**：使用 `LocalAudioTrack.setMuted` 代替 `LocalAudioTrack.setEnabled` 来控制本地音频的采集和发送，并且不要调用 `LocalAudioTrack.close` 关闭本地轨道。

</Accordion>

<Accordion title="iOS 15.x 和 16.x: iPad 和 iPhone 特定机型进入频道后可能出现杂音问题">

**影响范围**：安装 iOS 15.x 和 16.x 系统的 iPad 和 iPhone 特定机型上的 Chrome 和 Safari 浏览器。特定机型包括：

- iPad (5th Gen)
- iPad (6th Gen)
- iPad (7th Gen)
- iPad Pro (1st Gen)
- iPhone SE (1st Gen)

**规避方案**：升级到最新 iOS 版本。

</Accordion>

<Accordion title="iOS 16.0 上往特定方向旋转屏幕后，视频画面被拉伸">

**影响范围**：iOS 16.0 上的所有浏览器和内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

**问题原因**：iOS 16.0 上 WebKit 的 WebRTC 模块功能有回退，对 RTP 协议的图像方向（Coordination of video orientation, CVO）功能支持异常，导致手机旋转后画面被拉伸。

**规避方案**：建议在业务层面添加提示。

</Accordion>

<Accordion title="iOS 15.1.x: 使用 H.264 编码发送视频流导致页面崩溃">

**影响范围**：iOS 15.1.x 上的所有浏览器和内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

**问题描述**：iOS 15.1.x 上如果你调用 `createClient` 时将 `codec` 设为 `'h264'`，发送视频流后，页面会崩溃。

**问题原因**：该问题是由 iOS 15.1.x 上 WebKit 视频编码功能回退导致，详见 [WebKit Bug 231505](https://bugs.webkit.org/show_bug.cgi?id=231505)。

**规避方案**：使用 VP8 进行视频编码。

```javascript
createClient({codec:'vp8', mode})
```

</Accordion>

<Accordion title="iOS 15.x: 使用 H.264 编码发送视频流时，实际发送码率低于预期码率">

**影响范围**：iOS 15.x 上的 Safari 浏览器。

**问题原因**：该问题是由 iOS 15.x 上的 Safari 默认开启 **WebRTC H264 LowLatency encoder** 导致，详见 [Webkit bug 238366](https://bugs.webkit.org/show_bug.cgi?id=238366)。

**规避方案**：可以通过以下方案规避：

  - 使用 VP8 进行视频编码，示例代码如下：

    ```javascript
    createClient({codec:'vp8', mode})
    ```

  - 在 iOS 设备上前往**设置** > **Safari 浏览器** > **高级** > **Experimental Features**，关闭 **WebRTC H264 LowLatency encoder**。

</Accordion>

<Accordion title="iOS 15.0 至 15.3: 本地用户听到远端音频流的音量极低">

**影响范围**：iOS 15.0 至 15.3 上的所有浏览器及内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

**问题描述**：iOS 15.0 至 15.3 上订阅并播放远端音频轨道 `RemoteAudioTrack` 后，播放音量有概率极低，且音频从听筒中而不是扬声器中播放出来。

**问题原因**：该问题是由 iOS 15.0 至 15.3 上 WebKit 音频功能回退导致，详见 [WebKit Bug 230902](https://bugs.webkit.org/show_bug.cgi?id=230902)。

**规避方案**：iOS 15.0 至 15.3 上使用 `WebAudio` 进行音频播放并使用 `GainNode` 调整音量后，可以提高播放音量。声网建议你按照以下步骤规避该问题：

1. 升级至 Web SDK 4.9.0 或以上版本。
2. 设置 SDK 私有参数 `REMOTE_AUDIO_TRACK_USES_WEB_AUDIO` 为 `true`。SDK 内部会使用 `WebAudio` 播放远端音频流。示例代码如下：

  ```javascript
  function isIOS15(ua){
      // 通过 UA 判断 iOS 版本是否为 15
  }

  if(isIOS15(navigator.userAgent)){
      // Typescript 开发者在调用 setParameter 前需要加上 ”@ts-ignore“ 标签，JavaScript 不需要
      // @ts-ignore
      AgoraRTC.setParameter("REMOTE_AUDIO_TRACK_USES_WEB_AUDIO", true);
  }
  ```

</Accordion>

<Accordion title="iOS 15.x 和 16.x: 播放视频有概率出现黑屏">

**影响范围**：iOS 15.x 和 16.x 上的所有浏览器及内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

**问题描述**：iOS 15.x 和 16.x 上在 DOM 中播放视频且在 `video` 元素或其父元素添加某些 CSS 属性（如 `transform`、`animation`）后，或者改变 CSS 属性重绘视频渲染区域后，有概率视频播放出现黑屏。

**问题原因**：该问题是由 iOS 15.x 和 16.x 上 WebKit 视频渲染功能回退导致，详见 [WebKit Bug 230532](https://bugs.webkit.org/show_bug.cgi?id=230532)。

**规避方案**：升级至 Web SDK 4.7.3 或以上版本，并且尽量减少更改 `video` 元素及其父元素的 CSS 属性。

</Accordion>

<Accordion title="iOS 15.x: 用户佩戴蓝牙耳机后，播放音频有概率明显失真">

**影响范围**：iOS 15.x 上的所有浏览器及内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

**问题原因**：该问题是由 iOS 15.x 上 WebKit 音频播放功能回退导致，详见 [WebKit Bug 231422](https://bugs.webkit.org/show_bug.cgi?id=231422)。

**规避方案**：声网建议你在业务层面添加提示，告知用户使用蓝牙耳机可能出现音频失真问题。

</Accordion>

<Accordion title="浏览器或应用切换到后台时，音频流发送中断">

**影响范围**：iOS 15.x 上的 Safari 浏览器；iOS 14.4 至 15.x 上内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

**问题原因**：

- Safari 浏览器：由于 WebKit 的 [bug](https://bugs.webkit.org/show_bug.cgi?id=231105)，浏览器切换至后台后，`WebAudio` 的 `AudioContext` 会停止音频处理。
- 内嵌 WKWebView 的应用：iOS `WKWebView` 不允许在后台使用麦克风，详见苹果论坛说明 [Microphone gets muted in background](https://developer.apple.com/forums/thread/689182)。

**规避方案**：内嵌 WKWebView 的应用暂时无法规避此问题。iOS 15.x 上的 Safari 浏览器可以参考以下步骤规避此问题：

1. 升级至 Web SDK 4.7.3 或之后版本。
2. 调用 `createMicrophoneAudioTrack` 创建音频轨道时，将 `bypassWebAudio` 参数设为 `true`，本地音频流会不经由 `WebAudio` 处理直接发布。请注意此方案会导致混音功能 (`MixingAudioTrack`) 失效。

   ```javascript
   const localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack({bypassWebAudio: true});
   ```

</Accordion>

<Accordion title="iOS 15.x: 被其它语音或视频通话应用、Siri 呼叫、闹钟等打断后，音视频播放有概率无法自动恢复">

**影响范围**：iOS 15.x 上的所有浏览器及内嵌 WKWebView 的应用（如微信浏览器和 Chrome 浏览器）。

**问题原因**：音视频播放被打断后，DOM `video` 元素和 `audio` 元素的状态变为 `paused`。打断结束后，状态无法自动切回 `playing`，且调用 `HTMLMediaElement.play` 方法也无法恢复媒体的播放。详见 [WebKit bug 232599](https://bugs.webkit.org/show_bug.cgi?id=232599) 和 [WebKit bug 226698](https://bugs.webkit.org/show_bug.cgi?id=226698)。

**规避方案**：参考以下方案：

- 方案一：升级至 Web SDK 4.7.3 或以上版本。SDK 会尝试在打断事件后恢复媒体播放。声网建议你在业务层面增加提示，引导用户刷新页面。
- 方案二：升级至 Web SDK 4.20.0 或以上版本。SDK 会抛出打断事件通知，并且提供 `resumeAudioContext` 方法用于恢复媒体播放。详见 [API 文档](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#resumeaudiocontext)。

</Accordion>

<Accordion title="其他历史已知问题">

- iOS 13 和 14 上可能出现远端用户音量随机变化的问题。
- 切换前置、后置摄像头后采集画面可能会瞬间旋转。
- 语音路由随机切换，即可能出现插着耳机但是仍然从扬声器出声，或者没有耳机却从听筒出声的情况。
- 连续两次调用 `getUserMedia` 获取相同媒体类型的轨道，第一次获取的媒体轨道会静音或黑屏。
- 使用过其他使用音视频输入设备的 app 后（例如 Siri 或者 Skype 通话），无法采集本地音频或视频。

</Accordion>
</Accordions>

</TabsContent>

<TabsContent value="harmonyos">

<Accordions>
<Accordion title="被其它语音或视频通话应用（例如闹钟）等打断后，音频流的发送和接收有概率无法自动恢复">

**影响范围**：HarmonyOS NEXT 5.0 或以上版本的华为浏览器。

**规避方案**：参考以下方案：

- 方案一：手动刷新浏览器页面。
- 方案二：调用 `setEnabled` 方法禁用本地音频轨道后再重新启用。

</Accordion>
</Accordions>

</TabsContent>
</Tabs>

#### 已知限制 [#已知限制]

<Tabs defaultValue="android" groupId="operating-systems" persist>
<TabsList>
  <TabsTrigger value="android">Android</TabsTrigger>
  <TabsTrigger value="ios">iOS</TabsTrigger>
  <TabsTrigger value="harmonyos">HarmonyOS</TabsTrigger>
</TabsList>

<TabsContent value="android">

<Accordions>
<Accordion title="不支持调用 createScreenVideoTrack 进行屏幕共享">

原因：移动端浏览器及 WKWebView 未实现 `mediaDevices.getDisplayMedia` 接口。

</Accordion>

<Accordion title="不支持调用 setBeautyEffect 开启美颜">

原因：移动端设备在进行美颜算法处理时性能消耗过大。

</Accordion>
</Accordions>

</TabsContent>

<TabsContent value="ios">

<Accordions>
<Accordion title="不支持调用 createScreenVideoTrack 进行屏幕共享">

原因：iOS Safari 及 WKWebView 不支持 `mediaDevices.getDisplayMedia` 接口。

</Accordion>

<Accordion title="不支持调用 setBeautyEffect 开启美颜">

原因：iOS Safari 及 WKWebView 对 WebGL 支持不佳，且 iOS 设备在进行美颜算法处理时性能消耗过大。

</Accordion>

<Accordion title="不支持 IBufferSourceAudioTrack.seekAudioBuffer 方法">

原因：iOS 上 `WebAudio` 不支持实现该方法。

</Accordion>

<Accordion title="无法使用 H.264 编码发送 1080p 及以上分辨率的视频流">

原因：Web SDK 使用 H.264 Baseline Profile 进行协商，因此 iOS 上不支持编码发送 1080p 及以上分辨率的视频流。

</Accordion>

<Accordion title="发送小流时，不支持设置 LowStreamParameter.bitrate，且小流分辨率需要与大流分辨率成比例">

原因：iOS Safari 及 WKWebView 中 `RTCRTPSender.setParameters` 方法无法指定帧率，通过 `scaleResolutionDownBy` 属性进行分辨率压缩后，小流分辨率与大流成固定比率。

</Accordion>

<Accordion title="不支持获取 encodeDelay">

原因：iOS 上无法通过 WebRTC 的 `getStats` 接口计算出 `encodeDelay`。

</Accordion>

<Accordion title="浏览器或应用切换到后台后，本地用户的视频在远端显示为黑屏">

原因： iOS `AVCaptureSession` 不允许在后台使用摄像头。详见苹果官方说明 [AVCaptureSessionInterruptionReason](https://developer.apple.com/documentation/avfoundation/avcapturesession/interruptionreason/videodevicenotavailableinbackground?language=objc) 和 [Chromium issue 4294](https://bugs.chromium.org/p/webrtc/issues/detail?id=4294)。

</Accordion>

<Accordion title="调用 RemoteAudioTrack.setVolume 方法无法改变音量">

原因：iOS 以及 iOS 上的 WebView 不支持通过设置 `HTMLMediaElement.volume` 属性改变音量。

</Accordion>
</Accordions>

</TabsContent>

<TabsContent value="harmonyos">

<Accordions>
<Accordion title="H.264 视频编码格式发送帧率偏低">

原因：HarmonyOS 系统问题。

</Accordion>

<Accordion title="屏幕翻转后，视频画面可能无法自动适配新的屏幕方向">

原因：HarmonyOS 系统采集问题。

</Accordion>

<Accordion title="桌面端 Web 与移动端 Harmony 某些机型互通时，必现桌面端 Web 说话可以听到自己">

原因：HarmonyOS 系统问题。

</Accordion>
</Accordions>

</TabsContent>
</Tabs>

## 检测浏览器兼容性 [#检测浏览器兼容性]

声网 Web SDK 提供 [`checkSystemRequirements`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#checksystemrequirements) 方法，用于检测 SDK 是否能在当前浏览器中使用。

```typescript
const result = AgoraRTC.checkSystemRequirements();
// result 为 true 代表支持，false 代表不支持
console.log(result);
```
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>