做播放器开发的朋友应该都有个共同的痛点：后端把码流转成了 H265，前端却怎么都播不起来。Safari 上好好的，Chrome 直接黑屏；Windows 上硬解很流畅，换台 Mac 又报“不支持”。这些乱象的根源在于浏览器对 HEVC（H265）的支持一直是一种“有条件、看平台、碰运气”的状态。
这篇文章要聊的就是怎么绕开这些平台差异：用 WebCodecs 的 VideoDecoder 接口，不依赖浏览器内置播放器的解码链路，在 Web 端把 H265/HEVC 视频流完整解出来并渲染到画布上。标题里说的“软解码”，重点不是硬件无关的纯 CPU 计算，而是“在我们自己掌控的代码层完成解码调用”，不把解码结果交给浏览器黑盒处理。适合正在做 H5 播放器、视频编辑、实时预览、监控回看这类项目的开发者参考。文中会用我最近在某个跨平台播放器里落地 H265 支持模块的经历，把实现过程、踩过的坑、总结出来的固定套路都放进来。
1. 软解码的动机：为什么绕不开 H265
1.1 浏览器对 H265 的支持现状是一笔烂账
先说硬解。Safari 因为系统底层有成熟的视频解码框架，对 H265 一直比较友好，这也是很多视频站点在 iOS 上能直接播放 HEVC 的原因。Chrome 和 Edge 的情况就复杂得多：Windows 上要看显卡驱动、系统解码器、浏览器版本三者的配合；Mac 上要看硬件和系统版本；Firefox 更干脆，常年不支持。
最坑的是 MSE（Media Source Extensions）这条路径。MSE 对 HEVC 的支持受版权策略和平台解码器影响很大，同一台电脑、同一个浏览器，换个视频封装格式可能就从“能播”变成“不支持”。很多团队为了规避这些不确定性，最后都绕回到了软解路线。
注意：我这里说的“软解码”，指的是在我们自己控制的 JS 逻辑里完成解码调用，不依赖浏览器内置播放器对 H265 的原生支持。这样做的核心价值是“一致”——编码格式一旦被解码器接受，播放行为在浏览器间就是确定性的。
1.2 软解码能解决什么，不能解决什么
软解码最大的价值是可控。码流经过我们自己的 demux、分包、解码调用，最后输出的 VideoFrame 完全由我们掌控。即使浏览器自身对 HEVC 的支持不完整，只要 WebCodecs 接口能接受这段码流，我们依然能完成解码。
性能是另一面。H265 解码是计算密集型的，1080P 分辨率在桌面端跑起来通常要吃掉 30% 到 50% 的 CPU；移动端更吃力，可能伴随发热和降频。所以软解码定位应该是“兼容兜底”而不是“常态方案”。实际项目里我一般采取两层策略：优先尝试浏览器硬解路径，如果VideoDecoder.configure()抛错或者播放卡顿，再自动降级到软解链路。
1.3 三条路线的选型对比
现在 Web 端做 H265 解码，主流选择无非三种：
| 方案 | 原理 | 浏览器要求 | 性能 | 包体/内存 | 适用场景 |
|---|---|---|---|---|---|
| WebCodecs VideoDecoder | 浏览器原生解码 API | Chrome/Edge 94+，Safari 16.4+ 部分支持 | 高，取决于底层实现 | 几乎无额外包体 | 首选方案，兼容现代浏览器 |
| WASM 解码库 | 把 C/C++ 解码器编译成 WASM | 所有支持 WebAssembly 的浏览器 | 中低，比原生 API 慢 | 包体大，内存占用高 | 需要兼容老浏览器的兜底 |
| 纯 JS 模拟解码 | 软件层面逐像素还原 | 任意 | 极低，不实用 | 无 | 仅教学演示 |
WebCodecs 的优势在于它是浏览器原生能力，性能和内存管理都有保障。WASM 方案虽然真正做到了“纯 CPU 解码”，但包体动辄一两兆，内存拷贝开销也大，适合在确实跑不了 WebCodecs 的场景下做最后兜底。下文主要围绕 WebCodecs 这条路线展开。
2. 解码前必需的基础知识：NALU、参数集与时间戳
2.1 H265 编码效率靠的是什么
H265 比 H264 省码率的核心在编码单元的组织方式上。H265 引入了 CTU（Coding Tree Unit，编码树单元）的概念，默认 64x64 起步，可以按四叉树递归划分到 8x8。大的平坦区域用大块编码，纹理复杂的区域切成小块，这样残差数据更集中，码率分配更合理。帧内预测也从 H264 的 9 种方向扩展到了 35 种，预测更精细。运动补偿、变换编码、熵编码这些环节也都有增强。
不过对做 Web 播放器的人来说，编码原理了解这么多够了。真正要命的是码流怎么组织、参数集怎么传递、时间戳怎么对齐，这些才是解码链路里最常见的翻车点。
2.2 MP4 里的 H265：NALU、参数集与 hvcC 盒子
H265 的裸码流由 NALU（Network Abstraction Layer Unit）组成。每个 NALU 有一个 2 字节的 header，其中低 6 位是nal_unit_type。常见的类型：VPS 是 32，SPS 是 33，PPS 是 34，IDR 关键帧通常是 19 或 20，非关键帧一般是 1。VPS（视频参数集）、SPS（序列参数集）、PPS（图像参数集）这三个参数集合在一起，告诉解码器视频的宽高、档次、级别、参考帧结构等关键信息。
MP4 容器里，H265 视频轨道的stsd下面有hvc1或hev1的 sample entry，里面带一个hvcC盒子，专门存放参数集和长度字段配置。这个hvcC是解码初始化最关键的数据，很多人在 WebCodecs 里配置失败，问题就出在没把这个盒子里面的东西正确提取出来。
hvcC盒子的完整结构比较长，但核心字段有这些：
configurationVersion（1 字节）general_profile_space + profile_idc（1 字节）general_profile_compatibility_flags（4 字节）general_level_idc（1 字节）lengthSizeMinusOne（低 2 位）：表示每个 sample 内 NALU 长度前缀占几个字节，常见值是 3，代表 4 字节长度前缀numOfArrays（1 字节）：后续参数集数组的个数- 之后就是 VPS、SPS、PPS 等参数集的 NALU 数据
我最初踩过的坑就是直接拿整个 MP4 文件去搜索00 00 00 01开头的 Annex-B 格式数据，结果一塌糊涂。MP4 文件里 NALU 用的是长度前缀格式，不存在 start code。必须老老实实从hvcC盒子里按字段解析。
2.3 sample 数据与时间戳：B帧的坑
MP4 里每个视频帧称为一个 sample。sample 在文件中的偏移、大小、时间戳分别由stsc、stsz、stco/co64、stts、ctts这些表格描述。对播放器来说，最重要的是理解时间戳的关系。
解码顺序（DTS，Decoding Time Stamp）和显示顺序（PTS，Presentation Time Stamp）在存在 B 帧时是不一样的。MP4 的stts给出的是解码时间，ctts给出的是合成偏移量，PTS 等于 DTS 加 CTTS。WebCodecs 的EncodedVideoChunk里timestamp字段要求的是显示时间戳。如果直接把 DTS 填进去，B 帧多的视频会出现画面乱序、跳帧。
实操建议：demux 时先把每帧的 DTS 和 CTTS 都解析出来，计算 PTS 后填入EncodedVideoChunk。解码顺序保持 DTS 顺序，解码器内部自然会处理好乱序帧的重排。
3. WebCodecs 软解码实现：从配置到上屏
3.1 第一步：把 extradata 搞对
WebCodecs 里配置解码器，description是最容易出错的参数。VideoDecoder.configure()需要一个description，对于 H265 来说，最常见且稳妥的做法是把hvcC盒子里包含的全部参数集 NALU，用 Annex-B 格式的 start code（00 00 00 01）拼接起来，构造出一个二进制的 extradata。
我封装了一个从 MP4 文件解析出来的hvcC数据（不含 box header）构造 extradata 的函数：
function buildDescriptionFromHvcC(hvcC) { // hvcC 数据结构 // offset 21 的低 2 位是 lengthSizeMinusOne const lengthSize = (hvcC[21] & 0x03) + 1; let offset = 22; // numOfArrays 所在位置 const numArrays = hvcC[offset++]; const vps = []; const sps = []; const pps = []; for (let i = 0; i < numArrays; i++) { const nalType = hvcC[offset] & 0x3f; const numNalus = (hvcC[offset + 1] << 8) | hvcC[offset + 2]; offset += 3; for (let j = 0; j < numNalus; j++) { const nalSize = (hvcC[offset] << 8) | hvcC[offset + 1]; offset += 2; const nal = hvcC.subarray(offset, offset + nalSize); offset += nalSize; if (nalType === 32) vps.push(nal); else if (nalType === 33) sps.push(nal); else if (nalType === 34) pps.push(nal); } } const annexbParts = []; const appendWithStartcode = (nal) => { annexbParts.push(new Uint8Array([0, 0, 0, 1])); annexbParts.push(nal); }; vps.forEach(appendWithStartcode); sps.forEach(appendWithStartcode); pps.forEach(appendWithStartcode); const description = new Uint8Array( annexbParts.reduce((acc, p) => acc + p.length, 0) ); let writeOffset = 0; for (const part of annexbParts) { description.set(part, writeOffset); writeOffset += part.length; } return { description, lengthSize }; }这段代码没有太多复杂的逻辑，就是把参数集从 hvcC 的数组结构里提取出来，再转成 Annex-B 格式。重要的是顺序：VPS 在前，SPS 次之，PPS 在后。顺序错了，一些实现会直接初始化失败，一些则会花屏。
3.2 第二步：构建 EncodedVideoChunk 数据流
拿到 MP4 的每个 sample 后，数据还是长度前缀格式：每个 NALU 前有 4 字节（通常是 4 字节）的大端长度字段。WebCodecs 的decode()接口对数据格式有一定容错，但我实测下来，统一转成 Annex-B 格式是最稳的，各浏览器表现一致。
转换函数很简单：
function sampleToAnnexB(sample, lengthSize = 4) { const chunks = []; const data = new Uint8Array(sample); let offset = 0; while (offset < data.length) { let naluLength = 0; for (let i = 0; i < lengthSize; i++) { naluLength = (naluLength << 8) | data[offset + i]; } offset += lengthSize; if (naluLength <= 0 || offset + naluLength > data.length) { break; } chunks.push(new Uint8Array([0, 0, 0, 1])); chunks.push(data.subarray(offset, offset + naluLength)); offset += naluLength; } const total = chunks.reduce((acc, c) => acc + c.length, 0); const out = new Uint8Array(total); let pos = 0; for (const c of chunks) { out.set(c, pos); pos += c.length; } return out; }关键点在于长度前缀的实际字节数必须从hvcC的lengthSizeMinusOne字段读取，而不是写死 4。有些封装工具会把长度字段设成 2 字节，写死 4 的结果就是整个 sample 解析错位，表现通常是前几帧能解出来，后面大面积花屏。
3.3 第三步：解码器配置与 decode 循环
解码器的初始化代码看起来不复杂：
const decoder = new VideoDecoder({ output: (frame) => { // 这里拿到的 frame 是解码后的视频帧，交给渲染层 renderVideoFrame(frame); }, error: (e) => { console.error('VideoDecoder error:', e.message); }, }); decoder.configure({ codec: 'hev1.1.6.L93.90', description: extradata, codedWidth: width, codedHeight: height, hardwareAcceleration: 'no-preference', });有几个细节需要特别说明。
codec字符串的格式。H265 的 codec 字符串形如hev1.<profile>.<compat>.<level>。最省事的做法是直接从 MP4 文件视频轨道的 metadata 里读取，封装库里通常会给出codecs属性，比如常见的hev1.1.6.L93.90。如果拿不到，可以从 hvcC 中解析 profile 和 level 来生成，但不同封装的写法存在差异，不如源数据可靠。
hardwareAcceleration这个字段。默认就是'no-preference'，让浏览器自行决定用硬解还是软解。如果文章标题要求的“软解码”是指强制 CPU 解码，可以尝试传'prefer-software'，但我实测发现并非所有浏览器、所有版本都支持这个值，反而会触发配置失败。所以建议保持默认，把“是否软解”交给浏览器底层去调度。真正的纯软插帧场景，还是走 WASM 方案更可控。
解码循环的核心是构造EncodedVideoChunk：
function feedSample(sample, pts, isKeyFrame) { const annexb = sampleToAnnexB(sample.data, sample.lengthSize); const chunk = new EncodedVideoChunk({ type: isKeyFrame ? 'key' : 'delta', timestamp: pts, // 微秒，注意不是毫秒 data: annexb, }); decoder.decode(chunk); }timestamp的单位是微秒（microseconds），不是毫秒。把毫秒直接乘 1000 转成微秒。MP4 里的时间戳一般基于 timescale，比如timescale是 90000，那么一帧的 PTS 可能是 3003，换算成微秒就是 3003 * 1000000 / 90000。这里经常有人算错导致音画不同步。
3.4 第四步：渲染 VideoFrame
解码器 output 回调拿到的VideoFrame是一个可绘制的图像帧。最简单的渲染方式是画到 2D Canvas 上：
function renderVideoFrame(frame) { const displayWidth = frame.displayWidth; const displayHeight = frame.displayHeight; if (canvas.width !== displayWidth || canvas.height !== displayHeight) { canvas.width = displayWidth; canvas.height = displayHeight; } const ctx = canvas.getContext('2d'); ctx.drawImage(frame, 0, 0, displayWidth, displayHeight); frame.close(); // 千万别忘 }frame.close()这句话是血泪教训。WebCodecs 的 VideoFrame 是 GPU/系统内存资源，不是普通 JS 对象。不手动 close，解码器输出队列会持续堆积，进程内存和 GPU 显存都会不断增长，播放十来分钟就可能崩掉。
如果追求性能，可以用 WebGL 上传纹理再上屏，减少 CPU 侧的一次 drawImage 拷贝。但对大多数播放器场景，Canvas 2D 的 drawImage 已经足够，优先保证逻辑正确。
3.5 一个可以跑的完整代码骨架
把上面的步骤串成一个简化版的播放器核心逻辑：
class H265Player { constructor(canvas) { this.canvas = canvas; this.ctx = canvas.getContext('2d'); this.decoder = new VideoDecoder({ output: (frame) => this.render(frame), error: (e) => console.error('decode error', e), }); } prepare(codecString, hvcC, width, height, lengthSize) { const { description } = buildDescriptionFromHvcC(hvcC); this.decoder.configure({ codec: codecString, description, codedWidth: width, codedHeight: height, }); this.lengthSize = lengthSize; } pushSample(sampleData, pts, isKey) { const annexb = sampleToAnnexB(sampleData, this.lengthSize); this.decoder.decode(new EncodedVideoChunk({ type: isKey ? 'key' : 'delta', timestamp: pts, data: annexb, })); } render(frame) { this.ctx.drawImage(frame, 0, 0, frame.displayWidth, frame.displayHeight); frame.close(); } }这段代码省略了 MP4 demux 的部分。实际项目中，我建议用现成的 MP4 解析封装库拿 sample 和 metadata，不要自己逐字节解析 stbl 系列盒子。解析库虽然也会遇到各种不规范的 MP4 文件，但比从零开始踩坑要快得多。
4. 性能优化：软解码不是洪水猛兽
4.1 worker 线程是第一优先级
软解码最容易犯的错是把VideoDecoder和解码后的渲染全都放在主线程。解码本身会占用 CPU，如果主线程还在同步处理 DOM 事件、布局、绘制，页面就会肉眼可见地卡顿。
正确的做法是单独开一个 Worker，在 Worker 里创建VideoDecoder，解码完成后把VideoFrame通过postMessage转回主线程渲染。VideoFrame是 Transferable 对象，传输过程不会拷贝图像数据，代价极低：
// worker.js self.onmessage = (e) => { const { type, chunkData, pts, codecString, hvcC, width, height } = e.data; if (type === 'configure') { // 初始化 decoder，同样在 worker 内创建 decoder = new VideoDecoder({ output: (frame) => { self.postMessage({ type: 'frame', frame }, [frame]); }, error: ... }); decoder.configure(...); } // decode chunk ... }; // 主线程 worker.onmessage = (e) => { if (e.data.type === 'frame') { renderVideoFrame(e.data.frame); // 注意：frame 已经被 transfer 过来了，渲染完依然要 close } };这里有个细节：VideoFrame一旦被 transfer，它在 Worker 里就已经是 detached 状态，Worker 里不能再 close 它。主线程渲染完后负责 close。别两边都 close，会抛异常。
4.2 动态解码队列控制
VideoDecoder有一个decodeQueueSize属性，表示当前排队等待解码的 chunk 数量。如果不控制，播放器在遇到网络抖动或者 CPU 满载时，解码队列会越积越多，延迟越来越大，最终内存也会涨上来。
一个实用的策略是在喂帧前检查队列长度：
if (decoder.decodeQueueSize > 3) { // 队列已经积压，丢弃当前非关键帧 if (!isKey) { return; } }关键帧绝对不能丢，否则后面的帧全部解不出来。非关键帧丢了，解码器最多遇到一个短暂的花屏，下一帧关键帧到了自然恢复。对实时监控类场景，跳帧的价值远大于排队等待导致的高延迟。
4.3 降低分辨率以外的小技巧
桌面平台上我做过的压力测试大致数据如下（以八核桌面 CPU 为参考，具体数值因机器差异很大）：
| 分辨率 | 帧率 | 软解码 CPU 占用 | 实际体验 |
|---|---|---|---|
| 720P | 30fps | 20% - 35% | 流畅 |
| 1080P | 30fps | 30% - 50% | 基本流畅 |
| 1080P | 60fps | 50% - 70% | 偏吃力 |
| 4K | 30fps | 80% - 100% | 不推荐软解 |
所以 1080P 是软解码的实际舒适区。想要在 4K 上继续用软解，有几个可用的优化方向：
把 canvas 的绘制尺寸固定住，不要跟随视频原始分辨率。播放器显示区域如果是 720P，就可以先把视频解码到原始分辨率，再在 Canvas 上做一次缩放绘制。缩放由 GPU 完成，开销远低于解码本身。
批量渲染代替逐帧渲染。如果解码帧率高于屏幕刷新率（比如 60fps 视频在 30Hz 的节能屏上），可以在渲染层做一个简单的丢帧：只在requestAnimationFrame回调里绘制最新一帧，中间帧直接丢弃并 close。这样能省下约一半的绘制开销。
把decodeQueueSize控制在一个较低水平也有助于降低内存峰值。解码器内部的参考帧缓存是动态分配的，队列越深，占用的内存越多。
5. 高频问题的排查记录
5.1 configure 初始化失败的排查
这是遇到最多的问题，VideoDecoder.configure()直接抛NotSupportedError，原因通常是这几个：
| 现象 | 大概率原因 | 处理方式 |
|---|---|---|
| 报错又说不清细节 | codec 字符串不合法 | 从 MP4 metadata 的 codecs 字段拿，别手拼 |
| codec 字符串看着没问题 | description 缺失或格式错误 | 确认 hvcC 解析出来的 VPS/SPS/PPS 完整，start code 拼接顺序正确 |
| 1080P 的源可以，4K 报错 | 分辨率超出解码器能力 | 换 WASM 方案兜底，或者提示用户硬解 |
我遇到过一个诡异案例：同一个 MP4 文件，用 A 封装库拿到的 codec 字符串能解，用 B 库拿到的是hvc1.1.6.L93.90末尾少了.90，怎么 configure 都失败。后来发现是封装库版本差异导致的字符串格式不完整。解决的思路是——无论如何不要手写 codec 字符串，优先从源数据读取；如果源的 codecs 字段本身缺失，再用 hvcC 解析兜底。
5.2 花屏的定位思路
花屏大部分时候不是解码器的问题，而是喂进去的数据错了。
先看 NALU 边界。MP4 的 sample 转 Annex-B 时，长度前缀解析错一位，结果就是解码器把半个 NALU 甚至两个 NALU 的碎片当成一帧。定位方法也很粗暴：在sampleToAnnexB之后打印每个 NALU 的nal_unit_type，对照正常码流应该是 VPS/SPS/PPS 只在描述里出现，sample 里主要是 IDR（19/20）和 TRAIL（1）这一类。如果看到 NALU 类型忽大忽小、明显不在合理范围，基本就是长度解析错了。
再看参数集。如果首帧关键帧之前缺少必要的 VPS/SPS/PPS，解码器会直接报错或不输出任何帧。如果 VPS/SPS/PPS 存在但顺序不对，某些浏览器会默默接受，但画面的参考帧结构错乱，表现就是播放几秒后才花屏。这种问题排查起来最耗时，建议一开始就把 description 的二进制 dump 出来，对照 hvcC 盒子的字段确认每段 NALU 的完整性。
5.3 卡顿与内存泄漏
软解码的卡顿第一嫌疑人是主线程解码。用 Chrome Performance 面板录制一段播放，看到主线程有大量紫色（脚本）和黄色（渲染）任务，就说明解码和渲染抢线程了。解决办法已经在前面说过：Worker + Transferable VideoFrame。
内存泄漏的排查入口是VideoFrame.close()调用次数。可以在output回调里做一个计数器，同时观察任务管理器里标签页的内存趋势。如果内存持续上升而帧率稳定，90% 是 VideoFrame 没有 close。我见过一种少见的写法：为了“优化性能”，把 VideoFrame 存到数组里留作后用，既不渲染也不 close，结果几分钟内存就爆了。VideoFrame 的生命周期必须由开发者显式管理，这个没有捷径。
还有一个隐藏很深的坑：createImageBitmap(frame)转换出来的 ImageBitmap 也要手动close()。如果你用 ImageBitmap 做渲染而不是直接 drawImage(frame)，记得同步管理它的生命周期，否则同样泄漏。
5.4 音频视频不同步
严格说这不完全是 H265 解码的问题，但软解码播放器经常遇到。因为软解码的帧输出是异步的，如果按“解出一帧画一帧”的节奏来，没有和音频时钟对齐，声音和画面就会逐渐脱节。
我在实际项目中采用的方式是：把解码出来的 VideoFrame 放进一个带 PTS 的队列，在渲染线程里根据音频播放进度audioContext.currentTime计算一个目标 PTS，找到队列中最接近的那一帧来绘制，并丢弃已经过期的帧。这样即使解码速度波动，画面也能始终贴着音频走。
结尾：一点实际体会
在做这个 H265 软解码模块之前，我对 WebCodecs 的认知停留在“一个简单的 API”，真正落地后才发现，难点从来不在 API 本身，而在 API 两侧的功课：前端的容器解析是否正确，后端的帧数据格式是否完整。VPS/SPS/PPS 的完整性和顺序、sample 的 NALU 边界、时间戳的单位和来源，这三个问题解决好了，H265 软解码就已经成功了八成。
最后再分享一个小技巧：开发阶段不要把VideoDecoder的error回调只写console.error，建议在里面带上当前帧的 PTS、NALU type 序列前若干字节的 hex dump。遇到现场问题的时候，这些信息能帮你少走很多弯路。我自己就靠这个日志定位过好几例“第三方封装库输出的 sample 里混入了半个 NALU”的疑难杂症。
