平台支持

摘自完整使用手册的 iOS 限制与平台矩阵章节,构建时 @include 抽取,零漂移同步。 各平台各协议(HLS / MP4 / FLV)能不能播、iOS Safari 为什么特殊,看这一页。文中 § N 指向完整手册对应章节。

iOS Safari 硬限制

iOS Safari 有几个浏览器层面的硬限制,SDK 无法绕过。团队封装时必须理解这些限制,让业务方不踩坑。

11.1 完全不支持的能力

标准 window.MediaSource 路径不可用:

• ❌ flv.js 无法运行(FLV 视频无法播放)
• ❌ DASH 无法运行(SDK 也不做 DASH)
• ❌ 自定义 fMP4 MSE 管线不是受支持的播放路径

这不等于 iOS 没有 HLS 播放路径：iOS / iPadOS 17.1+ 提供 ManagedMediaSource，SDK 会让 hls.js 使用它；只有没有标准 MSE 和 MMS 的旧版本才回落原生 HLS。MMS 不是 flv.js 所需的标准 MediaSource，因此它不能让 FLV 变成可播放格式。

HTTP 请求拦截:

• ❌ 旧版原生 HLS 分片请求无法拦截——不能加 header,不能改 URL,不能刷新签名
• ❌ MP4 请求无法拦截——同上

所有路径都不提供可靠的逐分片改写 hook；授权更新走 §5.4 的宿主完整换源，而不是给某一个内核增加例外。

11.2 iOS / iPadOS 的 HLS 路径

iOS / iPadOS 17.1+ 的 HLS 走 hls.js + ManagedMediaSource；更低版本没有标准 MSE 与 MMS， 回落原生 HLS。版本只是当前已验证的边界，运行时实际按能力选择；两条 HLS 路径都不使 flv.js 可用。

11.3 SDK 的应对策略

FLV 场景:

• 仅提供 FLV 候选时，SDK 会在构造前得到 E_MEDIA_NOT_SUPPORTED
• 提供 sources[] 中的 HLS（或适用时 MP4）候选，iOS 才能选到可播放源

HLS 场景:

• ADR-056 后 iOS / iPadOS ≥ 17.1 走 hls.js(经 ManagedMediaSource);只有 iOS < 17.1 回落原生 HLS
• 认证只能靠签名 URL(见 § 5.5)

MP4 场景:

• 走原生 <video>,无法加自定义 header
• 认证只能靠签名 URL

11.4 团队封装时的检测

SDK 不导出平台检测 API(没有 detectPlatform)。团队封装组件若需要根据平台做 UI 决策(如 iOS 场景引导用户去 App 观看),用标准 Web 手段自行判断,或消费 SDK 的 onCompatWarning 事件:

function TeamVideoPlayer(props: VideoPlayerProps) {
  const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent)

  // iOS 场景引导用户去 App 观看
  if (isIOS && shouldShowAppBanner) {
    return <IOSAppInstallBanner />
  }

  return (
    <VideoPlayer
      {...props}
      onCompatWarning={({ code }) => {
        if (code === 'W_BROWSER_INCOMPATIBLE') {
          // 团队 UI: 引导用户换浏览器
        }
      }}
    />
  )
}

平台能力矩阵

12.1 iOS iPhone / iPadOS

场景	支持
HLS(iOS / iPadOS 17.1+ 为 hls.js + MMS；更低版本原生)	✅
MP4(原生 <video>)	✅
FLV	❌ 硬约束
自定义请求 header	❌
逐分片动态改签名	❌ 所有平台都不支持(ADR-057)；授权更新走宿主完整换源(§ 5.4)
PiP	✅(iOS 14+)
全屏	✅
autoplay 静音	✅
autoplay 有声	❌ 用户交互后才能

12.2 微信 WebView(iOS + Android)

场景	支持
HLS	✅(SDK 自动加 x5- 属性)
MP4	✅
FLV	❌ 不稳定,不推荐
全屏	⚠️ 需要 x5-video-player-fullscreen
后台播放	❌
autoplay 静音	✅

12.3 UC / 夸克浏览器(Android)

场景	支持
HLS	✅
MP4	✅
FLV	⚠️ 可能被内置播放器劫持,不推荐
SDK 会派发 compatwarning 提示引导用户	-

12.4 Android Chrome

场景	支持
HLS(via hls.js)	✅
MP4	✅
FLV(via flv.js)	✅
autoplay 静音	✅

12.5 Desktop 桌面浏览器

浏览器	HLS 原生	HLS via hls.js	MP4	FLV
Chrome	❌	✅	✅	✅
Edge	❌	✅	✅	✅
Firefox	❌	✅	✅	✅
Safari	✅	✅	✅	❌