简介ffmpeg.js 是一个基于 JavaScript 的 FFmpeg 封装库面向前端开发者与音视频处理爱好者用于在浏览器端直接完成音视频转码、剪切、合成等操作无需部署任何后端服务。压缩包大小仅 3.44MB共 122 个文件其中 61 个 PNG 图片用于展示运行效果与界面27 个 JS 脚本为核心代码及示例另有 6 个 HTML 演示页面、8 个 Markdown 文档以及 AVI/WAV/OGG 等测试素材结构清晰便于查阅。该资源已有 6399 人学习下载适合希望快速上手浏览器端音视频处理的开发者。内含多个可运行示例并给出创建 Worker、写入文件、转码、读取输出的完整 API 调用流程结合 GIF 演示可直观理解实现原理直接复制代码即可改造集成到自己的项目中。1. 无需任何后端服务就调 FFmpegffmpeg.js 在浏览器里到底做了什么ffmpeg.js 这个叫法指的不是某个 npm 包而是一类方案把 FFmpeg 编成 WebAssembly再用 javascript 调用做到无需任何后端服务即可直接在浏览器中使用 FFmpeg。对做在线剪辑、格式转换、数据处理工具站的人来说这意味着用户选完文件就能在本地完成转码视频不用上传服务器不用排队整个功能可以塞进一个纯前端项目里。代价也很明显内存受限、性能打折、部分编码器缺失并非无所不能。适合的人群是想快速交付工具型页面的前端团队或者对隐私敏感、希望文件不出本机的产品。下面按我平时从调研到落地的顺序拆先讲清运行原理再给最小可跑代码然后是高频参数、内存边界、常见坑和一个进阶收尾。2. 为什么 C 写的 FFmpeg 能在浏览器跑WASM 编译链路与浏览器运行模型2.1 从 C 源码到 .wasmEmscripten 在中间做了什么FFmpeg 本身是 C 写的依赖 libc、POSIX 文件接口、pthread 线程库这些浏览器里根本不存在的底座。想在浏览器里直接 import 一个 FFmpeg 的 C 源码是不现实的所以真正的方案是走编译链路用 Emscripten 工具链把 C 源码编译成 WebAssembly并生成一份 JavaScript 胶水层。这份胶水层负责在网页里加载 .wasm 文件、分配线性内存、把 JS 函数调用转成 wasm 里的函数调用。常见做法是分两层用底层产物叫 ffmpeg/core里面是 ffmpeg-core.js 和 ffmpeg-core.wasm 这样的编译产物上层封装叫 ffmpeg/ffmpeg提供 createFFmpeg、run、FS 这类面向业务的接口。封装层做的事情本质上就是把一个命令行字符串拆成参数数组然后一步步调 wasm 导出的 C 函数。你在代码里写await ffmpeg.run(-i, input.mp4, ...)背后等价于在某个微型 shell 里拼出了完整命令。需要说明的是标题里的 ffmpeg.js 是个历史叫法最早的产物是 asm.js 格式如今维护更活跃、资料更全的是 ffmpeg.wasm也就是编译成 .wasm 的版本。两者思路一致但 API 和编译产物不同写代码时优先按后者来。工程上判断一个方案值不值得用就看它的编译产物是否还在更新、社区是否还在维护ffmpeg.wasm 方向目前仍然值得投入。2.2 内存里的文件系统MEMFS 为什么这么重要FFmpeg 的命令行习惯是“给文件路径”浏览器里没有真实磁盘Emscripten 就用 FS 层模拟了一个文件系统。默认情况下用的是 MEMFS所有通过 writeFile 写入的文件都直接存放在 wasm 的线性内存里不是落在浏览器磁盘上。这个设计决定了整个使用模型File 对象先被转成 Uint8Array写进 MEMFSffmpeg.run 执行时从这个内存文件系统里读取输入文件、写入输出文件最后你用 readFile 把结果取出来。整个过程没有任何网络请求所以才能做到无需任何后端服务即可直接在浏览器中使用 FFmpeg。但也正是这一步成了后面很多坑的根源。本地 FFmpeg 是磁盘 IO 加内存缓冲浏览器这里是纯内存操作输入文件占一份内存编码器执行时内部缓冲再占一份输出文件又占一份。文件稍大一点内存立刻见底。用的时候必须养成随手 unlink 的习惯因为 MEMFS 里的文件不会因为你跑完命令就自动消失不清理的话下一次任务会在一个越来越挤的“内存磁盘”里执行。2.3 为什么选 WASM 而不是 WebCodecs 或后端转码我经常被问到同一个问题浏览器明明有 WebCodecs能不能直接用它WebCodecs 是浏览器原生提供的音视频编解码 API性能确实强但它只管编解码不管封装格式、滤镜、音视频同步这些 FFmpeg 顺手就做完的事。你要拿 WebCodecs 实现一个“MP4 转 WebM”得自己处理容器解析、轨道拼接、编码器协商工程量完全不在一个量级。后端转码是另一个选择功能全、性能好、内存不受浏览器限制尤其适合处理大文件和高并发。但如果你的产品强调隐私、文件不出本机或者你根本没有服务器资源后端方案就直接出局。三者取舍大概是这样选型实现工作量能力覆盖典型场景后端 FFmpeg 队列中高完整 FFmpeg上传转码、批量处理、服务端导出WebCodecs 手写管线很高基础编解码实时特效、低延迟处理、播放器增强ffmpeg.js/wasm 方案低接近完整命令集纯前端工具站、隐私优先、离线可用现实里很多团队的做法是两者结合小文件用 ffmpeg.js 前端转大文件落到后端队列。这样既保住了“文件不出本机”的卖点也留了后路。选型结论很直接做纯前端工具用 WASM已经有后端且不在乎上传用后端追求极致实时性能研究 WebCodecs。不要因为某一个方案听着新鲜就盲目全上先跑通最小命令再决定投入深度。3. 最小可跑通示例本地起一个页面用 ffmpeg.js 把 MP4 转成 WebM3.1 安装与目录准备三个包各管什么下面代码基于 ffmpeg/ffmpeg 目前最常见的 0.12 系列封装新版本封装 API 若有变化以它自带示例为准。先用 npm 装依赖npm init -y npm install ffmpeg/ffmpeg ffmpeg/core ffmpeg/util mkdir -p public/ffmpeg cp node_modules/ffmpeg/core/dist/ffmpeg-core.js public/ffmpeg/ cp node_modules/ffmpeg/core/dist/ffmpeg-core.wasm public/ffmpeg/三个包的分工要清楚ffmpeg/ffmpeg 是封装层提供 createFFmpeg、run 这些接口ffmpeg/core 是真正的编译产物也就是 ffmpeg-core.wasm 本体ffmpeg/util 提供 fetchFile 等类型转换工具。把 core 文件复制到 public 目录是为了绕过打包器对 wasm 文件的各种特殊处理开发阶段最省事也避免了直接引 CDN 时被跨域策略拦住的麻烦。3.2 最小转码代码加载、写入、执行、读取、清理import { createFFmpeg, fetchFile } from ffmpeg/ffmpeg; const ffmpeg createFFmpeg({ corePath: /ffmpeg/ffmpeg-core.js, log: true, // 开发时打开能看到命令执行日志 }); export async function mp4ToWebM(file) { if (!ffmpeg.isLoaded()) { await ffmpeg.load(); // 拉取并实例化 wasm只发生在内存中 } // 1. File 对象转成 Uint8Array 并写入 MEMFS const inputData await fetchFile(file); ffmpeg.FS(writeFile, input.mp4, inputData); // 2. 执行转码命令参数与命令行写法一一对应 await ffmpeg.run( -i, input.mp4, -c:v, libvpx-vp9, // 视频用 VP9 编码器 -c:a, libopus, // 音频用 OpusWebM 的标准组合 output.webm ); // 3. 读取输出文件注意要做一次数据复制 const view ffmpeg.FS(readFile, output.webm); const output new Uint8Array(view.length); output.set(view); // 复制出来避免拿到 wasm 内存的视图 const blob new Blob([output], { type: video/webm }); // 4. 清理 MEMFS避免内存被占满 ffmpeg.FS(unlink, input.mp4); ffmpeg.FS(unlink, output.webm); return blob; }fetchFile 的作用是把浏览器里的 File 或 Blob 对象转成 Uint8Array这是写入 MEMFS 所必需的数据格式。FFS三个接口很直观writeFile 写入、readFile 读取、unlink 删除名字和 POSIX 文件操作一致。log 参数我建议开发期打开它会把 FFmpeg 完整命令行和输出打到控制台很多怪问题靠它就能定位。真正上线时记得关掉日志字符串在内存里积累也是开销。读文件那一步最容易翻车readFile 返回的 Uint8Array 指向 wasm 底层那块大内存直接拿它的 buffer 去 new Blob会把同块内存里不相干的数据也带进去产物会异常变大甚至打不开。所以必须先new Uint8Array(view.length)再set(view)做一次拷贝得到的才是干净数据。3.3 四条高频命令参数转码、裁剪、截帧、抽音频// 1. 转码成 H.264 MP4浏览器兼容性最好 await ffmpeg.run(-i, input.mp4, -c:v, libx264, -preset, fast, -crf, 23, -c:a, aac, output.mp4); // 2. 裁剪 10 秒到 20 秒不重编码 await ffmpeg.run(-ss, 00:00:10, -to, 00:00:20, -i, input.mp4, -c, copy, output.mp4); // 3. 截取第 5 秒的一帧图片 await ffmpeg.run(-i, input.mp4, -ss, 00:00:05, -frames:v, 1, frame.png); // 4. 抽取音频为 MP3 await ffmpeg.run(-i, input.mp4, -vn, -c:a, libmp3lame, -q:a, 2, output.mp3);参数顺序里有一个容易被忽略的细节-ss放在-i之前是快速定位基于关键帧直接跳转放在-i之后是精确定位需要解码到指定时间点。浏览器端处理的视频普遍不大我一般把-ss放在-i之后换取精确性。-c copy是流拷贝模式速度快得多但裁剪点未必落在关键帧上常见表现是导出视频开头几秒黑屏或者没有声音这是 FFmpeg 里出了名的玄学。想保险就让裁切点落在最近的关键帧上或者干脆重编码。编码器选择也要有预期H.264 用 libx264WebM 常用 libvpx-vp9MP3 抽音频用 libmp3lame。这些是预编译 core 里最常见的组合。想压体积就用-crf控制质量数值越小质量越高23 是 H.264 的常见默认值-preset fast是速度和体积的折中。换编码器时先确认 core 里有没有别默认啥都有第 5 章会专门讲怎么查。4. 文件读写、多线程与内存预算把浏览器当好一个终端4.1 三个 FS 接口和一条完整的 IO 链路如果你不想依赖 fetchFile完全可以用原生 API 自己走一遍完整链路这样更清楚每一步发生了什么// File - ArrayBuffer - Uint8Array - MEMFS const buffer await file.arrayBuffer(); ffmpeg.FS(writeFile, input.mp4, new Uint8Array(buffer)); // 执行 FFmpeg 命令 await ffmpeg.run(-i, input.mp4, -c:v, libx264, -c:a, aac, output.mp4); // 读取结果是 wasm 内存的视图必须复制 const view ffmpeg.FS(readFile, output.mp4); const output new Uint8Array(view.length); output.set(view); // 用完清理否则 MEMFS 会越来越满 ffmpeg.FS(unlink, input.mp4); ffmpeg.FS(unlink, output.mp4);writeFile 要求数据是 TypedArray直接传 File 或者 Blob 都会报错文件字节流的形状必须先在 JS 侧转好。readFile 返回的对象本质是一个视图它跟 wasm 线性内存共用底层 ArrayBuffer这一点非常关键如果你把它存进变量留到下一次 run 之后再读内容可能已经被后面的命令覆盖。所以每次取回结果后立刻复制到独立的 Uint8Array是最稳妥的习惯。unlink 这一步很多人会漏掉。因为它不影响 run 的成功失败只在长时间使用后体现为内存逐渐增大、页面越来越卡。我自己的习惯是每个任务写完紧跟两个 unlink 加一个 revokeObjectURL这几行代码就是整套方案的后悔药。4.2 多线程版本能快多少SharedArrayBuffer 与两个响应头单线程版实现简单、兼容性好但你看到 CPU 占用只有一核时心里肯定不痛快。要上多线程就走 core-mt 这类多线程编译产物它依赖浏览器的 SharedArrayBuffer而 SharedArrayBuffer 要求页面处于跨域隔离状态也就是响应头必须带两行东西location / { add_header Cross-Origin-Opener-Policy: same-origin; add_header Cross-Origin-Embedder-Policy: require-corp; }加上之后网站的顶层窗口和 iframe、跨域资源之间就被隔离开了。副作用也要说清楚开启 COEP 后页面里所有跨域子资源都必须支持 CORP 或 CORS否则加载会被直接拦掉最常见的现象就是“某个 CDN 上的 JS 突然报错”。如果你用 Vite 做本地开发dev server 也要配同名的响应头不然代码写完本地就起不来。性能方面多线程对重编码任务提升明显比如 H.264 转 H.264实测体感能快不少但每个线程都会额外申请内存四线程下内存压力成倍增加转大一点的文件反而比单线程更容易崩。像-c copy这种不重编码的轻量任务多线程几乎没提升还多了 Worker 通信开销。我的判断标准是重负载且输入文件不大上用多线程轻负载或文件已经很大老实留在单线程。提示响应头加上后浏览器必须重新打开页面才会生效DevTools 里刷新不够。4.3 内存预算WASM 上限与控制输入规模的三个策略WASM32 的线性内存理论最大 4GB但浏览器实际可用往往到不了这个值移动端更紧张。结合起来看一次转码的内存需求大约是输入文件体积的三倍输入一份、编码器工作缓冲一份、输出一份。所以 500MB 输入在浏览器里转码内存压力已经非常危险翻车是常态不是偶然。三个控制策略是我认为最务实的。第一进 FFmpeg 之前先压输入如果是 4K 素材先在页面侧用 canvas 或 CSS 缩到 1080p 再传进 wasm体积能降一个量级。第二严格控制并发一个页面同时只允许跑一个转码任务两个 ffmpeg 实例并行跑内存是叠加而不是共享小文件也会被拖垮。第三处理完立刻 unlink 并关掉 log从习惯层面把内存峰值降下来。还有一个常见的 trick遇到特别大的文件与其整段重编码不如先算好要保留的时间区间只对那一段做处理避免输入输出同时在内存里翻倍。5. 前端接 ffmpeg.js 必踩的 5 个坑现象、原因与解决5.1 SharedArrayBuffer 未定义多线程起不来现象是控制台直接报SharedArrayBuffer is not defined或者 Worker 一创建就失败页面白屏。原因是页面没有处于跨域隔离状态要么缺 COOP/COEP 响应头要么干脆是用 file:// 打开的。解决办法分两步本地开发给 dev server 加上上文的两个响应头生产环境确认网关或 Nginx 配置生效。不想折腾就直接换回单线程 core它对响应头零要求功能完全一致只是慢一些。5.2 ENOSPC / Cannot enlarge memoryMEMFS 写满或内存撑爆现象是转码跑到一半命令报错错误信息里出现 ENOSPC 或者Cannot enlarge memory arrays。ENOSPC 在本地语境里是磁盘满在 MEMFS 语境里就是内存文件系统写不下了。原因很直接输入文件占一块、输出文件占一块编码器中间缓冲再占一块wasm 线性内存涨到浏览器不给涨为止。解决思路不是盲目加大参数而是减小输入、关闭并发、及时清理再用 try/catch 兜住错误把已经产生的临时文件 unlink 掉再做下一次任务。5.3 下载文件损坏或 Blob 异常巨大现象是转码成功、Blob 也生成了但下载下来的视频打不开或者文件体积大得离谱。原因就是 readFile 返回的 Uint8Array 是 wasm 内存的视图直接new Blob([view.buffer])会把整个底层 ArrayBuffer 都带上。解决方法是做一次复制const view ffmpeg.FS(readFile, output.mp4); const clean new Uint8Array(view.length); clean.set(view); const blob new Blob([clean], { type: video/mp4 });这个坑隐蔽在于不报错只让产物文件有问题排查起来很费时间。记住一个原则从 FFmpeg 拿出来的数据一律当“借用内存”看待要么马上消费掉要么立刻复制。5.4 Unknown encoder 或 Invalid datacore 里没有对应能力现象是换个视频格式就报Unknown encoder或者输入文件直接提示Invalid data found when processing input。原因通常是预编译 core 只带了常用编码器和容器格式H.265、某些商业编码器、老式封装根本不在里面。解决的第一步是先查一下当前 core 到底支持什么跑两条命令就能列出来await ffmpeg.run(-encoders); await ffmpeg.run(-formats);日志输出里会列出可用的编码器和容器列表看有没有你需要的名字。没有就想别的办法转封装而不是重编码比如把 H.264 的 MKV 改成 MP4 可以用-c copy完成不依赖未知编码器或者只抽取需要的轨道加-map 0:v:0 -map 0:a:0跳过字幕轨、多余音轨很多Invalid data报错就是多轨封装造成的。5.5 core 加载慢或跨域被 COEP 拦现象是页面一直在加载或者控制台报资源被 CORP 策略拦截。原因一般是默认从 CDN 拉取 core 二进制体积不小再叠加 COEP 开启后对跨域资源的限制CDN 响应头不全就直接失败。解决方法是把 core 文件自托管到同源静态目录按第 3 章的复制方式放到 public 下再配好 gzip 压缩。这样页面和 wasm 同源COEP 的拦截面就小了很多。如果实在要用 CDN确保链接支持 CORP 头并给 script 标签补上 crossorigin 属性否则多线程场景会撞墙。6. 进阶Web Worker 常驻、串行队列与产物验证6.1 把 ffmpeg 挪进 Worker别在主线程硬扛ffmpeg.run 是持续的高 CPU 计算放在主线程跑上几秒页面滚动就卡用户第一反应是网站崩了。常见做法是常驻一个 Web Worker把 createFFmpeg 实例、文件写入、命令执行全放进去主线程只负责传文件收结果。消息协议可以很轻worker.onmessage async ({ data }) { if (data.type transcode) { const blob await mp4ToWebM(data.file); postMessage({ id: data.id, blob }); } };用 id 字段把回包跟请求对应起来后面加队列、加取消都方便。6.2 串行队列和任务清理多个任务同时进来时不要并发跑多个 ffmpeg 实例内存会叠加到爆。我会在 Worker 内部维护一个简单 promise 队列一个转码完成再取下一条过程中产生的结果 Blob 在页面消费完后立刻 revokeObjectURL。WASM 里的 FFmpeg 没有安全中断一个正在执行命令的接口所以取消按钮不如置灰来得实在真需要取消就让 Worker 整体重新 load 一次。6.3 产物验证的一个土办法转码完不验证直接下载出了问题用户才知道就晚了。我的土办法是用 Blob 生成临时地址塞进 video 元素读 metadata 确认容器和轨道没问题const url URL.createObjectURL(blob); const video document.createElement(video); video.preload metadata; video.src url; video.onloadedmetadata () { console.log(video.duration, video.videoWidth, video.videoHeight); URL.revokeObjectURL(url); }; video.onerror () alert(导出产物损坏);能读出时长和宽高基本说明容器被浏览器认可抽帧出来再肉眼扫一眼才敢发给用户。这两年用这套方案我最大的教训不是命令写不对而是把浏览器里跑 FFmpeg 想得太“本地化”。内存边界、数据复制、Worker 隔离这几个点提前想清楚后面就顺了。希望帮到你。本文还有配套的精品资源点击获取