Appearance
为什么用 Sentinel,而不直接用 xgplayer
先把话说在前面:Sentinel 不是 xgplayer 的替代品,它就是 xgplayer——内核精确锁在 3.0.26, 播放能力一行没改。
所以问题不是"哪个播放器更强",而是:
直接用 xgplayer,你需要自己解决哪些问题?Sentinel 已经替你解决了哪些?
一、真实差距:35 个生产坑
xgplayer 是个好内核。但把它放进真实业务——微信里、UC 里、iOS 上、断网时、切后台后—— 会撞上一批内核本身不负责解决的问题。
我们把这些问题逐个编号、复现、归档,一共 35 个,其中 27 个已处理:
| 处置方式 | 数量 |
|---|---|
| 做成稳定性插件 | 19 |
在 create-player 里直接处理 | 1 |
| 决策规避(永久拒引某插件 / 精确锁版本 / 换方案) | 7 |
| 尚无处理 | 8 |
下面分开列,不混为一谈。
已处理的(27 个)
| 类别 | 坑数 | 典型症状 | 谁解决 |
|---|---|---|---|
| 断流 / 重连 | 4 | 断网后播放器就此躺平,不重连也不报错 | ReconnectPlugin · ErrorRecoveryPlugin |
| destroy 残留 | 3 | 组件卸载后 timer 和监听器还在跑,反复切页面直接崩 | safeDestroy |
| iOS 后台 / 全屏 | 3 | 切后台再回来播放器挂死 / 音频丢失 / iOS 26 微信全屏崩溃 | VisibilityPlugin · FullscreenGuardPlugin |
| 浏览器劫持提示 | 2 | UC / 夸克强行劫持成内置播放器 —— 检测到并告诉你,SDK 无法对抗 | CompatPlugin |
| 平台强制分流 | 4 | iOS / 微信 / UC / 夸克 播不了 FLV | SourceRouter 强制走 HLS |
| 卡顿测量 | 1 | 卡了但业务侧完全不知道,没法上报 | HealthMonitorPlugin(只测量,不修) |
| 屏幕 / 电源 | 1 | 看着看着屏幕自己灭了 | WakeLockPlugin |
| Autoplay 限制 | 1 | 自动播放被浏览器拒绝,但没人告诉业务层 | AutoplayGuardPlugin |
| 版本 / 兼容 | 3 | Chrome 116+ MSE 变更把 flv 打挂、Firefox 不原生支持 HLS | 内核精确锁 + SourceRouter |
| 层级冲突 | 2 | 覆盖层 z-index 打架、全屏时被兄弟元素遮住 | ZIndexGuardPlugin |
| xgplayer 内部 | 3 | xgplayer-mp4 插件卡死 / SourceBuffer 溢出 | 永久拒引,MP4 走原生 |
| 直播 / LL-HLS | 1 | 不显式开就享受不到低延迟(ADR-056 后:所有浏览器) | SourceRouter |
| 媒体源要求 | 2 | iOS < 17 MP4 兼容 / iOS 拦不到 header | 决策:HLS 兜底 + 签名 URL |
| 字幕 | 1 | 加载失败被 xgplayer 用空 catch 吞掉,表现为"点了没反应" | setSubtitle 直接接引擎 rejection |
只登记、还没做的(8 个)
诚实起见单独列出来:
| # | 症状 | 现状 |
|---|---|---|
| #6 | 微信 WebView 竖屏点全屏没反应 | 无代码 |
| #8 | 微信小程序 WebView 播放中止 | 无代码 |
| #11 | 老版本 Android WebView canvas 白屏 | 无代码 |
| #12 | 三星浏览器 fullscreen 请求异常 | 无代码 |
| #14 | seek 后 currentTime 抖动 | 源码注释:留给后续 healthreport,本版不做 |
| #19 | 微信 Android 需要 x5-video 属性 | 无代码 |
| #27 | iOS 画中画状态残留 | 无代码 |
| #34 | 直播断流重连后进度跳回 | 重连逻辑无 live 分支 |
#34 值得单独提醒:直播断线重连后,播放位置可能停在断点而不是追到最新。 如果你做的是互动直播,重连后建议自己 load() 一次刷新到最新。
这些多数需要真机复现、收益不确定。如果你的主战场正好是微信 WebView 深度交互, 这 8 个里有 3 个和你相关,请把这一点计入选型判断。
这张表就是本项目的全部价值主张
如果你的场景一个都撞不上——比如只在桌面 Chrome 内网放点播——那直接用 xgplayer 更划算, 少一层抽象。我们不劝你用。
面向接入方的坑点影响与处理结论见 35 个坑与 11 个插件。
二、另外三件事,和播放能力无关
2.1 一份代码,五种接入
同一套契约,React inline / Vue inline / React iframe / Vue iframe / 静态 iframe URL 五种方式行为逐字一致。 这不是口号,是一条叫 cross-mode-parity 的测试红线——四条路径跑同一组断言,不一致就 CI 挂掉。
意味着:你在 React 项目里验证过的行为,搬到 CMS 里用静态 URL 嵌,不用重测一遍。
→ 五种接入怎么选
2.2 视频源自动分流
你只管把手上有的源都传进来,SDK 按运行环境挑:
iOS / 微信 / UC / 夸克 / 无 MSE → 强制 HLS
其余环境 · 直播 → FLV 优先(延迟更低)
其余环境 · 点播 → HLS 优先不用自己写 UA 判断,也不用担心在 iPhone 上把 FLV 喂进去导致黑屏。
→ 怎么选视频源
2.3 事件和错误是契约,不是约定俗成
所有事件、命令、错误码都在 protocol 包里用 Zod 注册,严格 semver。 每个错误码自带 category 和 retryable,业务层可以直接照着写重试逻辑,不用猜。
这对埋点和监控尤其有用——错误分类是稳定的,不会某次升级后你的看板全乱。
三、什么时候不该用 Sentinel
我们更希望你选对,而不是选我们。
| 你的情况 | 建议 |
|---|---|
| 只跑桌面 Chrome / Edge,不碰移动端和微信 | 直接用 xgplayer。35 个坑你基本撞不上,没必要多一层。 |
| 需要 DRM(Widevine / FairPlay) | v1.0 不支持。用商业播放器或自己接 Shaka Player。 |
| 需要 DASH | v1.0 不支持,只做 HLS / FLV / MP4。 |
| 需要 Cast / AirPlay 投屏 | v1.0 不支持。 |
| 原生 App(iOS / Android / Flutter) | 本 SDK 是 Web-only,用不上。 |
| 想深度定制 xgplayer 内部行为 | 可能会难受。我们刻意不提供透传逃生舱,见 为何没有逃生舱。 |
| 想要一套开箱即用的漂亮 UI | 不提供。SDK 只做技术,品牌 UI 由你自己封装(ADR-021)。但我们给了 8 个场景的可运行参考实现,见 在播放器上做 UI。 |
最后这条要特别注意
Sentinel 不带业务 UI。默认只有 xgplayer 的原生控件。 如果你期待的是"装上就有一个和 B 站一样的播放器",那不是本项目。
四、代价
诚实起见,用 Sentinel 你要付出的:
- 多一层抽象——出问题时排查路径变长(为此我们做了按症状分的故障排查)
- 内核版本被锁死——xgplayer 精确锁 3.0.26,你不能自己升
- 没有逃生舱——xgplayer 的能力如果我们没在契约里暴露,你就用不了,只能提 ADR
- UI 要自己写——虽然有范例,但确实是工作量
如果这几条里有你完全不能接受的,上面那张"不该用"的表可能更适合你。