video-use：从播放到压缩的Web视频开发hooks方案

做视频功能这几年我最大的感受就是真正难的不是调通某一个API而是把播放、录制、截图、上传、压缩这一整套链路串起来的时候那些边界情况、性能问题、兼容性坑会一个接一个冒出来。前阵子我把自己的通用方案整理成了一个叫 video-use 的工具集与其说是开源一个库不如说是把这些年踩过的坑沉淀成一套可以直接抄作业的解决方案。这篇文章就来聊聊这个工具集背后的设计思路、核心模块的实现细节以及我在实际项目中反复踩过的那些坑。1. 为什么需要 video-use视频功能开发的核心痛点先说一个比较扎心的现状视频功能在Web端的复杂度往往被严重低估了。很多团队评估工作量的时候习惯性把“播放一个视频”等同于“写一个video标签”但等真正开发起来才发现光是播放器的状态管理就够写一堆逻辑更别提录制、截图、上传这些更重的场景。我最早做视频功能是在一个在线教育项目里需求听起来很简单老师上传视频、学生在线观看、支持倍速播放和进度记忆。但实际开发中遇到的第一个问题就是浏览器的原生video元素能力太分散了。播放、暂停、进度更新、音量变化、倍速切换这些事件各自独立状态分散在不同地方。业务代码里往往需要同时维护 currentTime、duration、paused、playbackRate、volume 这么多状态任何一个状态更新都要手动同步到UI稍不留神就会出现进度条跳动、播放按钮状态错乱这类低级bug。这还不是最麻烦的。真正复杂的是视频资源的管理。用户在弱网环境下打开页面视频加载超时了要不要重试播放过程中网络断了怎么自动恢复用户切换到后台再回来视频是接着播还是重新加载这些问题如果全部散落在业务代码里每一个都是定时炸弹。1.1 你以为的简单场景实际全是状态管理我拿一个最常见的“列表页点击播放”场景举例。页面上有几十个视频卡片用户点哪个就播哪个。听起来简单对吧但你要处理的事情包括点击卡片后要创建一个播放器实例同时关掉上一个播放器初始化是异步的用户快速切换时可能会出现多个实例并存视频是否能够自动播放要区分PC和移动端的不同策略播放过程中的错误需要捕获并且要能自动重试组件销毁时播放器实例必须彻底释放否则内存泄漏这些逻辑如果每个页面都写一遍代码会膨胀到没法维护。而且每个团队的实现方式还不一样有的用类封装有的用事件总线有的直接在组件里写。这就是为什么我后来决定做一个 hooks 风格的视频工具集——把状态和逻辑全部收敛到可复用的组合式函数里业务代码只需要关心 UI 层。1.2 从 VueUse 得到的启发hooks 是最适合视频场景的抽象方式熟悉 VueUse 的人应该知道它把浏览器的各种能力封装成了一组组合式函数拖拽、滚动、网络状态、剪贴板全部都可以通过 use 开头的方式直接引入。我当时的想法是为什么不把视频相关的操作也做成这样hooks 的抽象方式和视频操作天然契合原因有三点视频操作本身就是高度状态化的hooks 可以把状态和操作状态的方法绑定在一起不同场景对视频功能的需求是组合式的比如有的只需要播放有的需要播放加截图有的需要录制加截取片段hooks 天然支持按需组合视频的生命周期和组件生命周期紧密相关hooks 可以在组件销毁时自动做清理所以 video-use 就是一套以 hooks 为核心设计理念的视频工具集把播放控制、视频录制、截图、上传、压缩这些常见需求全部收敛成可按需引入的组合式函数。这样业务代码可以做到只关注自己真正用到的能力而不是把一个重型播放器整体引进来。2. video-use 的核心模块设计拆解整个工具集我按场景拆成了几个互相独立又可以组合的模块分别是播放控制、录制、截图、上传和文件处理。这套设计有一个基本原则每个模块都可以单独使用模块之间不产生隐式依赖用户用到哪些就引哪些。2.1 播放控制模块把状态管理从业务代码中剥离播放控制是整个工具集里最核心的模块。它的设计目标很简单业务代码不维护任何播放状态所有状态从 hook 里取所有操作通过调用方法完成。这个模块内部要处理的事情包括基础状态管理、事件代理和自动清理。基础状态指的是 currentTime、duration、paused、playbackRate、volume、muted 这些全部做成响应式引用。事件代理指的是监听 timeupdate、loadedmetadata、ended、waiting 这些原生事件并同步状态。自动清理指的是组件卸载时移除事件监听并释放播放器引用。这部分的实现难点在于事件同步的时机。timeupdate 事件一般每 250ms 触发一次如果每次都触发 Vue 的响应式更新页面可能会有明显的卡顿。我的方案是把 currentTime 的更新频率做降频处理用 requestAnimationFrame 包一层。说到这里RFA 和 timeupdate 的配合方式需要解释一下原生 timeupdate 本身频率是稳定的但 RFA 的调度和浏览器的绘制节奏是对齐的你可以让 RFA 内部去读取 video 元素的最新 currentTime而不用每帧都等 timeupdate 事件。2.2 录制与截图模块浏览器的媒体能力封装录制和截图这两个能力底层用的都是 MediaRecorder 和 Canvas但封装之后用户根本不需要关心这些底层的细节。录制模块我设计了几个方法start、pause、resume、stop还有一个可选的 timeSlice 参数。这里有个容易被忽略的坑MediaRecorder 的 start 方法如果传了 timeslice就会按时间片持续触发 dataavailable 事件如果不传只在 stop 时触发一次。如果你要做实时预览或者分段录制就必须传 timeSlice如果只是录完一次性上传不传反而更安全因为不会有数据交错的问题。截图模块的实现思路是用 Canvas 把当前视频帧绘制出来然后转成 Blob。这个模块比较麻烦的是跨域问题。video 元素如果设置了 crossOriginanonymous当视频源来自跨域服务器时服务器必须返回正确的 CORS 头否则 Canvas 会被污染调用 toDataURL 时直接报 SecurityError。这个问题我在实际项目里遇到太多次了后面会专门说怎么处理。2.3 上传与压缩补齐视频处理的最后一公里光有录制和截图还不够录出来的视频文件往往几十 MB 甚至上百 MB直接上传不仅慢还容易失败。所以 video-use 里专门设计了压缩模块内部封装了 FFmpeg 的 WebAssembly 方案。选择 FFmpeg.wasm 而不是纯 Canvas 处理的原因是 Canvas 对视频编码的支持太弱了。Canvas 截图导出的是图片做视频转码基本帮不上忙。FFmpeg.wasm 虽然体积大、加载慢但是功能完整支持转码、裁剪、抽帧、拼接这些高级操作。实际项目中我建议做成懒加载用户真正触发压缩时才去 CDN 拉取 wasm 文件而不是页面初始化时就加载。压缩模块这里有一个清晰的核心参数匹配关系视频码率决定体积太低会糊分辨率决定画面尺寸太高手机上转码慢。我的经验是 720p 分辨率 1.5Mbps 码率是一个通用平衡点但如果你知道视频会大幅裁切可以适当降低分辨率。上传模块则兼容了分片上传和断点续传。分片上传的原理不需要很复杂把文件切成 5MB 一个的块并发 3 个请求上传全部完成后通知服务端合并。断点续传的关键是给每个分片算一个 hash 值上传前先问服务端哪些分片已经传过了只传缺失的部分。3. 从零接入 video-use核心场景实操讲完设计思路来点实际的。下面演示几个核心场景的接入方式从最简单的播放控制到录制上传全链路每个场景都有完整代码。3.1 场景一视频播放页的标准接入姿势我以 Vue 3 的组合式 API 为例。安装 video-use 之后在组件里引入 useVideo 这个 hook。script setup import { ref } from vue import { useVideo } from video-use const videoRef ref(null) const { paused, currentTime, duration, playbackRate, togglePlay, seekTo, setRate } useVideo(videoRef) /script template div classplayer-wrap video refvideoRef src/videos/demo.mp4 controls preloadmetadata crossoriginanonymous / div classcontrols button clicktogglePlay{{ paused ? 播放 : 暂停 }}/button span{{ Math.round(currentTime) }}s / {{ Math.round(duration) }}s/span button clickseekTo(30)跳转到30s/button select v-modelplaybackRate changesetRate(Number(playbackRate)) option value0.50.5x/option option value11x/option option value1.51.5x/option option value22x/option /select /div /div /template注意几个细节。video 元素的 ref 一定要传给 useVideohook 内部会通过这个 ref 拿到真实的 DOM 元素。preloadmetadata 是推荐的只加载视频元数据不预加载正片内容省流量。crossoriginanonymous 是给后续截图功能留的后手如果视频源支持跨域加上这个属性不会出错。这个场景里有一个我特意做的设计初始状态全为 false 或 0。因为 video 元素还没有加载元数据duration 会是 NaN所有依赖 duration 的 UI 逻辑都要加 v-if 或者判断 isNaN。如果你在业务里发现播放页各种信息不显示先排查是不是 metadata 还没加载完。3.2 场景二录制麦克风加摄像头并实时预览录制的接入方式相对复杂一些因为涉及权限请求和 MediaRecorder 状态管理。script setup import { ref, onBeforeUnmount } from vue import { useRecorder } from video-use const localStream ref(null) const { isRecording, startRecorder, pauseRecorder, resumeRecorder, stopRecorder, getRecordedBlob, error } useRecorder() async function startCapture() { try { // video-use 内部会帮你处理 getUserMedia 的权限申请 await startRecorder({ audio: true, video: { width: 1280, height: 720, facingMode: user }, mimeType: video/webm;codecsh264, timeslice: 1000 }) } catch (err) { // 权限被拒绝、设备不支持指定的 mimeType 都会走到这里 console.error(录制启动失败:, err) } } async function saveRecording() { const blob await getRecordedBlob() if (blob) { // 这里拿到的是 Blob直接交给上传模块即可 uploadVideo(blob) } } onBeforeUnmount(() { stopRecorder() }) /script一个很重要的经验分享mimeType 不要写死成 video/webm不同浏览器的支持情况差异很大。Chrome 支持 video/webm;codecsh264Firefox 的编码器支持情况又不一样Safari 直接走的是 video/mp4 分支。我在工具集内部做了兼容检测但如果业务里手动传入一定要先用 MediaRecorder.isTypeSupported 校验一遍。另外一个容易踩的坑是 timeslice。上面说了如果你传入 timeslicedataavailable 事件会按时间片触发工具集会帮你把多个分片合并成最终的 Blob。但如果你不传则数据会在 stop 时一次性触发。做实时预览或者需要录制过程中就拿到数据做处理的建议传 timeslice只是录完再上传的不传更干净。还有一点关于音频回声如果录制场景同时需要本地预览和远端通话本地预览不能用 video 标签直接播放因为声卡回路会把远端的声音再录进去。我踩过一次这个坑之后录制预览一律用静音的方式播放本地流。3.3 场景三视频截图保存为本地文件截图功能的封装逻辑对使用者来说是透明的你只需要提供 video 元素引用调用 capture 方法就行。import { useVideoSnapshot } from video-use const { captureFrame, snapshotBlob, isSnapshotting } useVideoSnapshot() async function takeSnapshot() { const blob await captureFrame({ format: image/png, scale: 1.0 }) if (!blob) return const url URL.createObjectURL(blob) const a document.createElement(a) a.href url a.download snapshot-${Date.now()}.png a.click() URL.revokeObjectURL(url) }这个场景的关键问题是跨域。如果 video 元素的 src 来自 CDN 且 CDN 没有返回 Access-Control-Allow-Origin: * 或者你的站点域名截图操作会直接报错。解决方法有两个一是确保 video 设置了 crossoriginanonymous 且服务端配合二是代理视频流到同源地址。前者省事后者更可控。我在工具里把这种错误做成了特殊错误码 SNAPSHOT_SECURITY_ERROR业务里可以根据这个错误码提示用户而不是给出一句看不懂的英文报错。3.4 场景四本地视频压缩与分片上传一条龙最后一个场景是完整的链路从选择文件到压缩再到上传。import { useVideoCompressor } from video-use import { useUploader } from video-use const { compressVideo, compressionProgress, compressedBlob } useVideoCompressor() const { uploadWithResume, uploadProgress, uploadStatus } useUploader() async function handleFile(file) { // 1. 压缩把大文件压缩到可接受的体积 const result await compressVideo(file, { targetSize: 720p, bitrate: 1.5, // Mbps removeAudio: false, onProgress: (percent) console.log(压缩进度:, percent) }) // 2. 分片上传带断点续传能力 await uploadWithResume(result.blob, { fileName: compressed_${Date.now()}.mp4, chunkSize: 5 * 1024 * 1024, // 5MB分片 concurrency: 3, // 并发数 onProgress: (percent) console.log(上传进度:, percent), getUploadedChunks: async () [], uploadChunk: async (chunk, meta) { /* 上传单个分片 */ } }) }FFmpeg.wasm 的压缩逻辑实际处理流程是要先把文件写入内存文件系统然后执行命令再把输出文件读出来。这个过程的时间取决于视频时长和设备性能。我建议加载阶段做 loading 提示在压缩阶段做进度提示。要说的是压缩和上传最好分开执行不要一边压缩一边上传因为 FFmpeg.wasm 打包运行时的内存开销很高同时并发上传会拖垮页面性能。压缩完了再上传整体的体验反而更流畅。4. 性能优化与性能取舍这可能是最重要的一个章节功能跑通只是第一步真正让 video-use 在真实项目中站住脚的是性能上的打磨。这一章的内容全是我在实际项目中用线上事故换来的。4.1 内存泄漏为什么关掉播放器之后页面越来越卡播放器引起的卡顿绝大多数不是主线程计算密集而是内存泄漏导致的频繁 GC。典型的泄漏点有三个播放器实例不释放video 元素还挂在 DOM 上src 还指向远程视频流事件监听不移除比如 window 上的 resize 监听、visibilitychange 监听Blob URL 不回收截图或录制生成的 URL.createObjectURL 一直没有 revokevideo-use 的做法是在 hook 的 onCleanup 里统一做这三件事。事件监听全部记录在内部 Set 里统一 remove。Blob URL 统一追踪在合适的时机自动 revoke。使用的时候要注意如果你手动在组件里又加了监听也要自己负责移除。一个比较隐蔽的泄漏场景useVideo 如果只绑定了一个组件里的 video 元素当组件销毁时hook 内部的清理逻辑会触发。但如果同一个视频元素被多个组件共用清理时机就要格外小心不能一个组件卸载就停止所有事件监听。这种情况建议每个组件各自创建独立的 video 元素不共享。4.2 弱网场景下的播放体验弱网是播放器躲不开的关卡。video-use 提供了网络状态感知和自动恢复能力。实现方式是通过监测 video 元素的 error 事件和 readyState 状态。在实际项目里我推荐的配置是加载超时时间设为 8s超过就触发重试最多重试 3 次每次间隔 2s、4s、8s 递增播放中断时显示一个浮层提供“重试”按钮同时后台自动尝试恢复这里有一个技术细节检测断网不能只靠 navigator.onLine这个 API 在移动端经常不准。可靠的方式是把 video 的 src 设成空再恢复或者直接监听 video 元素的 stalled、waiting、error 事件组合起来判断。4.3 移动端自动播放策略的妥协方案很多刚接触视频开发的同学会在这上面浪费好几天页面打开视频不播就是黑屏或者只有第一帧。这是因为移动端 Safari 和部分 Chrome 版本要求视频必须静音才能自动播放。这个策略没法绕过只能妥协。video-use 的处理方式是提供一个 showMuted 配置。如果你的业务需要自动播放就把 showMuted 设为 true视频会静音自动播放UI 上显示一个静音按钮让用户自己开声音。另外要在 video 标签上加 playsinline 属性否则 iOS 上视频会强制全屏播放。4.4 WebCodecs 方案和 FFmpeg.wasm 的取舍在压缩模块的设计上我同时研究了 WebCodecs 方案。WebCodecs 是浏览器原生提供的编码解码 API性能远超 FFmpeg.wasm但最大的问题是兼容性还不好Safari 一直到 15 才部分支持。此外 WebCodecs 的 API 设计偏底层封装成本高短期内不适合做通用方案。如果未来兼容性改善视频处理的方向一定会转向 WebCodecs WASM 混合的架构用 WebCodecs 做音视频编解码用 WASM 处理封装格式和滤镜。目前 video-use 的策略是 FFmpeg.wasm 打底预留 WebCodecs 的适配层接口后续可以平滑切换。5. 常见问题与排查技巧实录这个章节是我从真实工单和社区反馈里整理出来的高频问题可以直接当做一个速查表用。5.1 截图报 SecurityError现象是调用 toDataURL 抛出 SecurityError。按以下顺序排查确认 video 元素已经设置 crossoriginanonymous看浏览器 NetWork 面板视频资源的响应头是否包含 Access-Control-Allow-Origin如果使用的是第三方视频源确认对方是否开启跨域没开就换代理方案确认视频不是本地 file:// 协议打开的页面本地文件场景不需要跨域头但也不能截其他域的5.2 录制出来的文件是空的这种一般是拿到一个 0 字节的文件或者录制正常结束但 Blob 为空。通常有两个原因一是录制过程中 dataavailable 事件没有触发最常见的是 mimeType 在当前浏览器不受支持二是 stop 之后立刻读 BlobMediaRecorder 的状态还没有完全切换到 inactive。我的建议是 stop 之后怎么等监听 statechange等 state 变成 inactive 之后再取数据。但有人问不就是在 onstop 里拿吗如果你是在 stop 之外监听 dataavailable 事件收集分片此处说的是另一个时序问题实际应该先把分片收集好再用 onstop 回调读取。5.3 上传进度卡住不动上传进度卡住优先检查后端接口是不是支持 OPTIONS 预检请求。分片上传会带着 Content-Type: application/octet-stream 之类的头触发 CORS 预检。预检失败的表现就是第一个分片就报错或者进度条卡在 0%。另外后端接收分片的接口一定要返回进度相关的响应否则前端只能靠 onUploadProgress 盲猜。5.4 压缩时浏览器标签页崩溃这个症状很典型打开压缩页面跑了一会儿整个标签页直接没了。Compressor 崩溃的最主要原因就是 wasm 内存膨胀。FFmpeg.wasm 需要一块预分配的 ArrayBuffer如果视频分辨率很高这个 buffer 不够用就会往上涨最终触发浏览器的内存保护机制。缓解手段是压缩之前先检查视频的分辨率和时长超过阈值就直接提示用户“此视频过大建议先修剪再压缩”而不是硬扛。另一个手段是降低并发上传数压缩过程中给主线程留足够的空间。还有一个思路是把压缩任务拆分成小片段处理但实现复杂度高暂时没有默认支持。5.5 Safari 上视频无法播放Safari 上视频黑屏或无法播放优先检查三件事video 元素是否缺少 playsinlineiOS Safari 不设置这个属性会强制进入全屏播放模式src 的格式是不是 HLSm3u8Safari 原生支持 HLS但如果你把 HLS 地址直接塞给 video 也不做任何处理还是要确保 video 支持这种封装格式服务端是否支持 Range 请求Safari 的视频播放非常依赖 Range 支持不支持的话拖动进度条会失败6. 我的一些后续规划与个人感悟video-use 目前最大的短板在于录制模块对 Safari 的适配以及 WebCodecs 融合的路线还没有完全跑通。后续的规划主要集中在两个方向一是把编码器内核抽象成可插拔的架构让用户自由切换 FFmpeg.wasm、WebCodecs 或者原生浏览器编码二是增加更多分场景的预设比如教育场景的录课模式、电商场景的商品视频处理等。另外我还想给新手一个建议不要一上来就追求把 video-use 的功能全部用上。视频功能最忌讳的就是过度封装。如果你只是做一个播放页老老实实只引播放控制模块就够了录制、压缩、上传这些模块引入一个用不到一个打包体积会受影响维护负担也更大。最后分享一个我个人的习惯写视频功能之前先花半小时把目标录像设备的参数确认清楚。摄像头的分辨率和帧率、麦克风的采样率、录制环境的光线、网络上行带宽这些参数直接决定了你的代码里要配置哪些兼容分支。很多问题不是代码写错而是参数匹配不上导致的。把视频功能当成一个和硬件深度耦合的软件工程来做坑自然就少了一大半。