企业官网建设流程全解析

上周一个做教育直播的同行把问题丢给我：同一个 HLS 的 m3u8 地址，安卓端 H5 用 hls.js 插件播得挺顺，一到 iOS 的 H5 页面就黑屏，控制台偶尔蹦一句Hls Error就没有然后了。他前后换了三个版本的 hls.js，改了一堆配置项，还是不行。我看了两分钟就笑了——不是插件版本的问题，是 iOS 上这套技术路线本身就走不通。HLS 在 iOS 上有一条完全不同的通路：系统原生支持 m3u8，但偏偏不给浏览器的 MSE 接口，而 hls.js 这类插件恰恰是踩在 MSE 上工作的。路线选错了，配置怎么调都是白费。这篇文章就把这件事从头到尾讲清楚：iOS 和各路 WebView 里 HLS 到底怎么播、hls.js 插件的适用边界在哪、双引擎方案怎么落地、索引和分片有哪些容易被忽略的硬性要求，最后附上我自己踩过的坑和一份可以照抄的配置清单。不管你是刚接手 H5 播放器的新人，还是被线上客诉追着跑的老手，应该都能从里面找到能直接用的东西。

1. 先别急着改代码：iOS 上 hls.js 失效的真实原因

1.1 HLS 在 iOS 上走的是另一条路

先把最核心的事实摆出来：HLS 这套协议本来就是苹果推出来的，iOS 和 macOS 的系统播放器（AVFoundation 那一层）天生就能直接解析 m3u8，你只要把地址丢给<video src="xxx.m3u8">，剩下的分片下载、码率切换、音视频同步全部由系统完成，H5 这一层压根不需要参与。这是 iOS 的原生能力，不需要任何插件。

而 hls.js 插件走的是另一条完全不同的技术路径。它的原理是：自己用 XHR 把 m3u8 和 ts 分片拉下来，然后通过MediaSource接口把数据一段段喂给 video 元素。这个接口就是MSE（Media Source Extensions），本质上是一种"让 JS 有能力自己造一条视频流"的浏览器能力。

问题就出在这：iPhone 上的 Safari 长期不提供 MSE。也就是说 hls.js 赖以生存的地基在 iPhone 上压根不存在，它自然什么都干不了。直到 iOS 17.1，iPhone 上才出现了一个受限的ManagedMediaSource，但它并不是桌面端那种可以任意 appendBuffer 的完整 MSE，hls.js 依旧用不了。所以你会看到一个很反直觉的现象：安卓 Chrome 上必须靠 hls.js 才能播的 m3u8，在 iOS 上反而不需要任何插件，直接扔给 video 就行。

再补一个容易让人分裂的细节：iPad 上情况不一样。iPadOS 13 之后 iPad 的 Safari 桌面化了，MSE 是开着的，所以同一个页面在 iPad 上Hls.isSupported()返回 true，hls.js 能正常工作；在 iPhone 上返回 false，必须走原生。于是就出现了"测试同学用 iPad 测都是好的，用户拿 iPhone 一片黑"这种经典事故。你要是不知道这层差异，很容易把问题误判成兼容性问题去瞎改配置。

1.2 hls.js 的能力边界：isSupported 到底在判断什么

很多人把Hls.isSupported()当成一个"这个浏览器能不能播 HLS"的判断，这是个误解。它判断的其实是"这个浏览器有没有可用的 MSE"，跟 HLS 协议本身没关系。源码层面的逻辑大致是检查window.MediaSource是否存在、MediaSource.isTypeSupported('video/mp4; codecs="avc1.42E01E,mp4a.40.2"')是否返回 true。在 iPhone Safari 上，第一步就过不去，直接返回 false。

所以正确的判断逻辑应该是分层的，而不是单点：

• 先看Hls.isSupported()，为 true 说明 MSE 可用，交给 hls.js 掌控，你能拿到码率切换、缓冲统计、错误重试这些能力；
• 为 false 时，再去看video.canPlayType('application/vnd.apple.mpegurl')，iOS Safari 上会返回"maybe"，说明系统原生能接；
• 两者都不行，才需要提示"当前环境不支持播放"，或者降级成 MP4 直链。

这里有个坑得提醒：某些安卓浏览器canPlayType也会返回"maybe"，但实际播放会失败，尤其是部分定制内核的 WebView，它声称支持 HLS，真播起来却卡在第一帧。所以我个人的习惯是：主判Hls.isSupported()，走 hls.js；兜底才走原生，并且给原生路径配一个错误监听，一旦video.error报出来，立刻切回 hls.js 或者提示重试，而不是让用户对着黑屏发呆。

还有一个细节：iOS 上 hls.js 即使被你强行初始化，attachMedia之后也不会有任何报错，只是永远停在MEDIA_ATTACHING状态，静悄悄地什么都不干。这种"静默失败"最坑人，排查的时候一定要先确认isSupported()的返回值，别一头扎进网络请求里查。

1.3 一张环境矩阵表，先定位你踩的是哪个坑

不同运行环境对 HLS 的支持路径差别很大，我在项目里一般会先画这么一张表，对着表定位比盲猜快得多。

这张表里最需要注意的是最后两行。App 内嵌 H5 场景下，H5 侧怎么写只是一半，原生容器那边的配置同样决定生死。iOS 的WKWebViewConfiguration里有allowsInlineMediaPlayback，不打开的话视频在某些容器里会被强行拉去全屏播放；mediaTypesRequiringUserActionForPlayback不设成WKAudiovisualMediaTypeNone，自动播放就会被拦。安卓侧对应的是setMediaPlaybackRequiresUserGesture(false)。我在实际项目里遇到过好几回，H5 代码一个字没改，只是原生同学把这两个开关打开，视频立刻就正常了——所以排查这类问题，一定要把端上同学拉进群里一起看。

2. 播放引擎选型：原生与 hls.js 的双引擎方案

2.1 能力探测的三行代码和它的坑

能力探测这件事，代码量很小，但写错的概率很高。我见过不少项目是这么写的：

if (Hls.isSupported()) { // 用 hls.js } else { // 报错，提示不支持 }

这段代码在 iPhone 上会直接走进 else 分支，然后给用户弹一个"当前浏览器不支持视频播放"，但事实上 iPhone 完全能播。正确写法至少要有三层兜底：

const HLS_MIME = 'application/vnd.apple.mpegurl'; const video = document.getElementById('player'); const canPlayNative = video.canPlayType(HLS_MIME) !== '' || video.canPlayType('application/x-mpegURL') !== ''; let engine = null; if (window.Hls && Hls.isSupported()) { engine = createHlsJsEngine(video, src); } else if (canPlayNative) { engine = createNativeEngine(video, src); } else { showFallbackTip(); }

这里有两个容易忽略的点。第一，canPlayType的返回值有三个档位："probably"、"maybe"、""，只要不是空字符串就代表有一定支持能力，不要写成=== 'maybe'，因为不同内核返回"probably"的情况也存在。第二，Hls这个全局变量本身可能不存在（脚本没加载完、CDN 挂了），所以window.Hls &&这一层校验必须加上，否则你的兜底逻辑会先因为Hls is not defined崩掉。

再补一个实战经验：探测要在拿到 video 元素之后做。canPlayType是 video 元素的方法，不是全局方法。有些同学图省事写成document.createElement('video').canPlayType(...)，虽然也能跑，但如果你后面要对同一个元素做多次探测、或者元素上挂了自定义属性，就会绕远路。直接用真实的那个元素最稳。

2.2 统一播放器封装：对外只暴露一套接口

双引擎的麻烦在于两套 API 完全不一样：hls.js 用的是hls.loadSource()+hls.attachMedia()，还能监听Hls.Events.ERROR；原生走的是video.src直接赋值，错误只能从video.error里拿。如果业务层到处if (engine === 'hls')，代码很快就会烂掉。

我的做法是包一层统一的播放器对象，对外只吐这几个方法：play()、pause()、seekTo()、switchQuality()、destroy()，内部用策略对象分别实现。

function createHlsJsEngine(video, src) { const hls = new Hls({ maxBufferLength: 30, maxMaxBufferLength: 60, enableWorker: true, lowLatencyMode: false, }); hls.loadSource(src); hls.attachMedia(video); hls.on(Hls.Events.ERROR, (event, data) => { if (!data.fatal) return; if (data.type === Hls.ErrorTypes.NETWORK_ERROR) hls.startLoad(); else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) hls.recoverMediaError(); else hls.destroy(); }); return { play: () => video.play(), seekTo: (t) => { video.currentTime = t; }, destroy: () => hls.destroy(), }; } function createNativeEngine(video, src) { video.src = src; const onError = () => { const err = video.error; console.warn('native video error', err && err.code, err && err.message); }; video.addEventListener('error', onError); return { play: () => video.play(), seekTo: (t) => { video.currentTime = t; }, destroy: () => { video.removeEventListener('error', onError); video.removeAttribute('src'); video.load(); }, }; }

注意 hls.js 那段的错误处理逻辑：只有data.fatal为 true 时才需要干预。非致命的错误 hls.js 内部会自己重试，你在外层再加一层重试反而会打架，导致请求风暴。另外NETWORK_ERROR通常对应网络抖动或分片 404，重试startLoad()就够了；MEDIA_ERROR多是解码问题，recoverMediaError()会尝试换个 buffer 重建；如果是manifestParsingError这一类，重试没有意义，直接报错更合适，因为索引本身就有问题。

原生引擎那段我也加了 error 监听，原因很简单：iOS 原生播放器失败时页面是完全静默的，日志里什么都没有，不加监听你连用户报的是哪种错都不知道。video.error.code的取值是固定的四个：1 是用户中止，2 是网络错误，3 是解码错误，4 是源不支持或格式不兼容。在 iOS 上最常见的是 4，它通常意味着 m3u8 索引本身不合法，或者 404，而不是编码问题——这个区分很重要，方向错了会白查半天。

2.3 实例销毁与资源回收，别让页面越用越烫

单页应用里播放器组件被反复挂载卸载是很常见的，这里如果处理不好，会出两种典型症状：一是切了好几次视频之后手机开始发烫、掉帧；二是内存涨上去就不下来了。

hls.js 内部会持有 Worker、定时器、buffer 队列，destroy()必须显式调用，光把 video 的 src 清掉是不够的。我在组件卸载钩子里固定做两件事：

onBeforeUnmount(() => { engine && engine.destroy(); engine = null; video.pause(); video.removeAttribute('src'); video.load(); });

原生引擎那边的video.load()是个关键动作。它会让浏览器重新走一遍资源加载流程，把已经缓冲的分片释放掉。如果你只removeAttribute('src')而不调load()，某些 iOS 版本上缓冲数据会一直挂着，切十个视频就能明显感觉到卡顿。

还有一个细节很多人不知道：iOS 原生播放 m3u8 时会自己做缓存，而且这个缓存是按 URL 走的。同一路径不同 query 参数会被认为是不同的资源。这个特性有两个用处，一个坏处。用处是切换清晰度时可以通过加不同的 query 强制刷新；坏处是如果你用的是带签名、会过期的地址，缓存命中之后即便签名过期了它也不重新请求，表现就是"明明刷新了页面还是播的旧内容"。我在后面第 6 节还会专门讲这个坑怎么绕。

3. 让 iOS 真的播起来：属性、编码与容器配置

3.1 playsinline 与自动播放的三个前提

iOS 上的 video 元素有一堆"历史包袱式"的行为，最典型的是默认全屏播放。在早年，iPhone 上点一下 video 就会全屏，页面里的内联播放根本不存在。现在虽然支持了，但必须显式声明：

<video id="player" playsinline webkit-playsinline x5-playsinline x5-video-player-type="h5" preload="auto" controls ></video>

这几个属性的分工不一样，别只写一个。playsinline是标准属性，现代 iOS 认它；webkit-playsinline是老版本 iOS 认的前缀写法，为了兼容还在用旧系统的设备；x5-playsinline和x5-video-player-type是安卓微信 X5 内核的私有标记，写上能避免它劫持成全屏播放器。四个都写不冲突，成本也低，我一般是全加上。

自动播放这块，iOS 的规则是：必须同时满足"静音"和"内联播放"两个条件，才有机会自动播。缺一个都会被拦。而且即便满足，video.play()返回的 Promise 也可能被 reject，抛NotAllowedError，所以调用处一定要 catch：

video.muted = true; const p = video.play(); if (p && p.catch) { p.catch((e) => { console.warn('autoplay blocked', e.name); showPlayButton(); }); }

还有一个体验上的坑：静音自动播放成功后，用户想听声音得点一下"取消静音"，而**video.muted = false这个动作必须在用户手势的回调里执行**，不能在定时器或者 Promise 里异步执行，否则会被判定为"非用户触发"而失败，表现就是点了按钮音量图标变了但没声音。我踩过这个坑，后来统一改成按钮的 click 事件里同步执行。

3.2 视频编码与切片规格的硬性要求

编码这块的坑比很多人想的要多。hls.js 解码失败时你还能看到详细报错，iOS 原生播放器则是直接黑屏给你看，什么都不说。所以源本身的规格必须提前对齐。

视频轨必须用 H.264，Profile 建议卡在 Baseline 或 Main，Level 别超过 4.1；音频轨必须是 AAC-LC，采样率 44.1kHz 或 48kHz，声道数 2。这些不是绝对红线，但超出范围的组合在 iOS 上失败概率显著高于安卓。我遇到过一版源用了 HEVC 编码，安卓 Chrome 因为落到了平台解码器上还能播，iOS Safari 直接拒绝，换成 H.264 立刻正常。还有一种情况是音频用了 PCM 或者不太主流的采样率，视频画面能出来但一直没声音，用户投诉"视频是哑的"，查了半天才发现是编码问题。

分片规格方面，GOP（关键帧间隔）建议和分片时长对齐，常见做法是分片 2 到 4 秒。如果 GOP 比分片长，切分片时会找不到独立可解码的关键帧，iOS 上容易出现起播慢、拖动卡顿。音频和视频的 PTS 起点要对齐，否则音画会漂移，这种问题在短视频里不明显，长视频播到后面能差出好几秒。

如果用 fMP4（也就是 CMAF 那套）切片，m3u8 里必须有#EXT-X-MAP指向 init 段，并且#EXT-X-VERSION要大于等于 7。iOS 10 之后是支持 fMP4 的，但索引里少了 MAP 或者版本号写小了，原生播放器会直接判为不支持。这一点在 hls.js 上反而宽松些，所以就出现了"安卓能播 iOS 不能播"的分裂现象。

3.3 App 内嵌 WKWebView 的额外开关

如果你的 H5 是嵌在 App 里的（现在大部分场景都是），那有一半的工作在原生那边。iOS 的 WKWebView 需要关注这几个配置：

• allowsInlineMediaPlayback：允许内联播放。iOS 10 之后 iPhone 上默认是开的，但 iPad 和部分定制容器里默认不开，会强制全屏。我的建议是无论默认值如何都显式设成 true。
• mediaTypesRequiringUserActionForPlayback：设成WKAudiovisualMediaTypeNone才能允许自动播放，默认值是会拦截的。
• 如果页面里用到了 canvas 截图或者需要读像素，还得注意 CORS 配置，否则 canvas 会被污染。

安卓 WebView 侧对应的是setMediaPlaybackRequiresUserGesture(false)和setJavaScriptEnabled(true)。另外部分 App 会自己接管 video 标签，把播放交给自己的播放器内核，这时候 H5 侧的playsinline和样式可能全部失效，表现就是"页面里的小窗口突然变成全屏播放器，还有自己的 UI"。遇到这种情况别在 H5 里挣扎，直接找端上确认是不是接管了播放。

我在项目里形成的习惯是：上线前拿一个最小化的 Demo 页面，把 H5 代码固定在那一版，让端上同学分别用开/关这两组配置各跑一遍。这样能一次性把"H5 的问题"和"容器的问题"分清楚，比事后一层层甩锅高效得多。

4. 索引与分片排查实录：从 .png 分片说起

4.1 m3u8 自查清单：iOS 原生的容错比 hls.js 低得多

这是我最想强调的一点：同一个 m3u8，hls.js 能播，不代表 iOS 原生能播。原生播放器的校验严格得多，很多在 Chrome 上被"宽容处理"的语法问题，在 iOS 上是硬报错。所以当你从安卓切到 iOS 时，第一件事不是改代码，是拿索引去体检。

下面这份清单是我自己每次排查都会过一遍的：

其中#EXT-X-TARGETDURATION这一条我要单独说说，因为它太隐蔽了。这个字段的含义是"所有分片时长的上限，向上取整"。假设你的分片实际时长是 4.2 秒，那 TARGETDURATION 至少要写 5；如果你写了 4，hls.js 可能睁一只眼闭一只眼过去了，iOS 原生播放器会直接判定清单不合法。我遇到过一次线上事故就是切片工具算错了这个值，安卓一切正常，iOS 全量黑屏，最后就是改这一个数字解决的。

另外#EXT-X-ENDLIST的缺失也值得警惕。点播流如果没有这个标记，iOS 会按直播流处理，表现形式是：能播，但进度条拖不动，或者拖了之后回到起点。很多人以为是前端 seek 逻辑写错了，其实是索引里少了一行。

4.2 分片后缀与 Content-Type 错配怎么查

有一种情况挺有意思，也是最近被问到比较多的：m3u8 语法本身完全合法，是一份正常的点播清单，但分片链接全部以.png结尾，实际返回的却是 MPEG-TS 数据。这种"扩展名和内容不一致"的配置，在历史项目里确实存在，原因通常是 CDN 只放行了图片类扩展名，或者早期为了统一缓存策略做过特殊处理。

这种流在不同引擎下的表现差异很大，值得展开说说。

hls.js 这边，它拉分片用的是 XHR 加responseType: 'arraybuffer'，拿到的是一段二进制，它并不关心 URL 以什么结尾，也不会去校验分片的 Content-Type。所以只要服务端老老实实把 TS 字节流吐出来，hls.js 就能正常播，你甚至感觉不到异常。

iOS 原生播放器就不一样了。它对资源类型的判断更依赖响应头和内容嗅探，一旦发现不匹配，可能直接拒绝加载。所以排查这类问题时，你要做的是绕过后缀看真实响应：

1. 用抓包工具或者浏览器 Network 面板，打开一个分片 URL，看Content-Type到底是什么；
2. 把响应体存下来，用file命令或者十六进制查看器看头几个字节。TS 流一般以0x47开头（也就是 ASCII 里的G），如果开头是 PNG 的魔数89 50 4E 47，那说明服务端确实返回了图片；
3. 比较响应体大小和#EXTINF推算的码率是否吻合。

如果确认是 TS 但声明成了image/png，服务端那边至少要把Content-Type改成video/mp2t或者application/octet-stream。还有一种更隐蔽的坑：某些图片 CDN 会对.png做自动无损压缩或者二次处理，那 TS 数据就被破坏了，表现是解码错误、花屏、卡在某一帧。这种情况只能改路径或者换 CDN 策略，前端层面无解。

顺带说一个相关的缓存问题。按扩展名分缓存策略的 CDN，通常会给图片设置很长的缓存时间，比如 30 天。如果分片挂在.png路径下，直播场景会出现"一直播旧分片"的诡异现象，因为 CDN 把分片按图片缓存住了。点播场景问题不大，直播场景是致命的。

4.3 加密流的播放要点：EXT-X-KEY 与密钥获取

HLS 支持 AES-128 加密，索引里通过#EXT-X-KEY声明：

#EXT-X-KEY:METHOD=AES-128,URI="https://example.com/key?token=xxx",IV=0x1a2b3c...

播放侧其实不需要你手动解密，hls.js 和 iOS 原生播放器都会自动去拉这个 key 然后解密分片，前提是 key 能被正常获取。这里有几个特别容易翻车的地方。

第一是 key 的跨域问题。hls.js 走 XHR 拉 key，必须带上 CORS 头；原生播放器则不受 CORS 限制。所以会出现"切到原生之后就好了"的假象，实际上是 CORS 配置的问题被掩盖了。如果你的 key 服务和页面不同域，务必让服务端配上Access-Control-Allow-Origin。

第二是 key 的鉴权。iOS 原生播放器拉 key 时不会带你的自定义请求头，只认 URL 里的参数。所以如果你的 key 地址是靠Authorization头鉴权的，在 iOS 上一定失败。正确做法是把签名放到 query 参数里，并且签名有效期要覆盖整个播放时长——因为直播流播放过程中会周期性重新拉 key，如果签名只有 5 分钟有效期，播着播着就断了。

第三是 IV 的处理。如果索引里显式写了 IV，就用这个 IV；如果没写，规范规定用分片序号作为 IV。这个细节在服务端和播放端理解不一致的时候，表现就是画面全花。排查时把索引里的 IV 抄下来，和切片时的加密参数对一对，一般就能发现。

我们团队后来形成一个约定：所有加密流的 key 地址都必须能在浏览器地址栏里直接打开并返回 16 字节内容。这个简单的自检动作能挡掉八成的密钥问题。

5. 报错定位：错误码对照与常见问题速查

5.1 hls.js 错误事件怎么读

hls.js 的错误事件里有两个字段最关键：type和details。type只有三个值：networkError、mediaError、otherError。details更细，标明了具体环节。我把常用的几个整理一下：

判断是否要处理，看data.fatal。真致命的时候才动手，networkError走startLoad()，mediaError走recoverMediaError()，其他类型直接销毁并报错更干净。特别要提醒的是fragLoadError不要无脑重试，如果是签名过期，重试一百次也是失败，只会在日志里刷出一堆请求。合理做法是给重试设一个上限，超过就触发上层刷新播放地址。

原生的错误码前面提过了，再补一句：iOS 上video.error.message有时会带上比较具体的描述，比如提示清单格式或者分段相关问题，这个信息比code值钱得多，日志一定要打出来。

5.2 常见问题速查表

下面这张表是我这几年攒下来的，基本覆盖了 iOS H5 播 HLS 的绝大多数现场问题。按症状查比按原因查效率高。

我特别想说"播放几秒后卡住"这一条。它的迷惑性在于，用户描述的往往是"网络不好"，但真实原因常常是签名过期。分片 URL 上带的签名有效期如果是 60 秒，而视频缓冲了 30 秒，播到第 40 秒需要拉新分片时就 403 了。排查方法是看 Network 里失败请求的响应头，如果返回带时间戳的错误说明，基本就能确认。解决办法要么延长签名有效期，要么在播放器里监听错误后自动刷新地址重载。

5.3 真机调试：把 iOS Safari 的网页检查器用起来

iOS 上的问题，光靠加 console.log 效率太低，一定要用真机调试工具。流程是：iPhone 上打开"设置 - Safari - 高级 - 网页检查器"，然后用数据线连到电脑，在桌面 Safari 的"开发"菜单里选中你的设备，就能打开当前 H5 页面的完整开发者工具，Network、Console、Elements 全都有。

这套工具能让你看到几个关键信息：分片请求的真实响应头、m3u8 的响应内容、video.error的具体值。我遇到过好几次"以为是编码问题，一看 Network 发现是 404"，省掉大量瞎猜。

如果 H5 是嵌在 App 里的 WKWebView 中，普通连线可能看不到，这时候可以让端上同学在开发包里开启 Web Inspector 支持（inspectable设为 true）。实在不行就用抓包工具看 HTTP 层，虽然看不到 console，但请求和响应足够定位大部分网络类问题。

还有一个小技巧：iOS Safari 对 m3u8 会做缓存，有时候你改了服务端的清单，真机上却还是旧的。这时候在开发者工具的 Network 面板里勾上"停用缓存"，或者手动改一下 query 参数，能避免很多"改了没生效"的乌龙。

6. 几个踩过的坑和我的处理习惯

6.1 清晰度切换在原生播放器上的代价

在 hls.js 上切清晰度是很轻的动作，调用hls.currentLevel = n就行，缓冲可以复用。但在 iOS 原生播放器上，它没有暴露这种能力，你只能改video.src重新加载，代价是黑屏一下、缓冲清空、播放位置回到 0。

处理办法是手动记位置再回跳：

function switchToNative(video, newUrl) { const t = video.currentTime; const wasPlaying = !video.paused; video.src = newUrl; const onLoaded = () => { video.removeEventListener('loadedmetadata', onLoaded); if (t > 0) video.currentTime = t; if (wasPlaying) video.play().catch(() => {}); }; video.addEventListener('loadedmetadata', onLoaded); }

这段逻辑看着简单，但有几个细节值得注意。loadedmetadata触发时视频的时长信息才可用，这时候 seek 才有效；如果提前 seek 会被忽略。另外新地址最好拼一个唯一的时间戳参数，避免命中旧缓存。切换过程中的 loading 态要自己维护，不要指望 video 元素给你状态。

还有一个体验优化：切换前先把 loading 蒙层显示出来，等playing事件触发再隐藏。不然用户会看到一块黑屏闪一下，观感很差。

6.2 带签名 URL 过期与缓存引发的"黑屏"

前面提过的签名问题，这里展开讲一个完整的处理套路。我们的播放地址是服务端下发的，带 10 分钟有效期。线上出现过用户暂停超过 10 分钟再点播放，直接黑屏的情况。

排查路径是这样的：先看video.error.code，是 4（源不支持）；再抓包看分片请求，返回 403；确认是签名过期。最后的方案是加了两个机制：一是播放器监听error事件，一旦发现是网络类错误就回调上层重新拉一次播放地址；二是页面重新获得焦点（visibilitychange）时检查地址签发时间，超过阈值就主动刷新。

这里要注意，重新拉地址之后不要直接赋给video.src，因为那样会丢失播放进度。正确做法还是走上面切换清晰度的那套逻辑，记时间点、换源、回跳。我们上线之后这类客诉基本归零了。

另外提醒一句：iOS 原生对 m3u8 有缓存，刷新地址时务必在 URL 上拼一个变化的参数，否则拿到的可能是缓存里的旧清单，里面还是过期的分片地址。

6.3 我现在的默认配置清单

最后把我在新项目里固定会用的那份配置清单放出来，可以当模板抄。

HTML 侧：

<video id="player" class="player" playsinline webkit-playsinline x5-playsinline x5-video-player-type="h5" preload="auto" controls muted ></video>

JS 侧的判断顺序是：window.Hls && Hls.isSupported()走 hls.js，否则看canPlayType走原生，都不行给降级提示。hls.js 的初始化参数用enableWorker: true、maxBufferLength: 30、maxMaxBufferLength: 60，lowLatencyMode根据是不是直播决定，点播关掉能省不少 CPU。

错误处理上，hls.js 只处理fatal错误，networkError重试startLoad，mediaError走recoverMediaError，其他销毁并上报；原生则监听error，把code和message都打到日志里，其中 code 为 4 时优先怀疑索引和地址而不是编码。

组件卸载时固定执行destroy()、pause()、removeAttribute('src')、load()四连，一个都不省。上线前跑一遍真机验证清单：iPhone Safari、iOS 微信、安卓微信、App 内嵌各走一遍，重点看自动播放、进度条拖动、切清晰度、播放 10 分钟以上四个场景。这几步花不了半小时，但能挡掉线上绝大多数问题——毕竟这类问题一旦漏到线上，用户只会告诉你"视频打不开"，剩下的都得你自己猜。