简介：这份资源围绕 ffmpeg.js 展开，面向希望在前端直接完成音视频处理的前端开发者与多媒体应用实践者，解决传统转码必须依赖后端服务、部署链路冗长的问题。借助其封装好的 API，只需少量代码即可在浏览器中加载并调用 FFmpeg，完成视频转码、格式转换等任务，适合在线剪辑、格式转换工具、教学演示等场景。压缩包共 122 个文件，约 3.44MB，以 61 个 png 截图、27 个 js 脚本、8 个 md 说明文档、6 个 html 示例页为主，另含少量 yml 配置、json 数据及 avi、wav、ogg 等音视频素材，兼顾源码阅读与直接运行验证。目前已有 6402 人学习下载，说明其在同类前端音视频方案中具备一定参考价值。资源内含转码示例、网络摄像头调用、图片转视频、concat 拼接等演示页面，读者可据此理解 worker 加载、文件写入、转码与读取的完整调用流程，并对照文档快速搭建本地实验环境，掌握纯前端音视频处理的关键思路与排错方法。
1. 浏览器里跑 FFmpeg：一个不依赖后端服务的音视频处理方案
你有没有遇到过这种场景：用户上传一段视频，你只想截取前 10 秒或者转成 GIF，结果后端排队、上传下载来回折腾，光等待就够喝一壶。ffmpeg.js 这个项目解决的正是这个痛点——它把 FFmpeg 编译成 WebAssembly，让浏览器直接完成转码、裁剪、抽帧、格式转换，全程不需要任何后端服务参与。适合谁？做在线视频编辑器的前端、需要本地处理音视频又不想搭转码集群的团队，以及想研究 WASM 工程化落地的开发者。下面我按「能干什么 → 怎么跑 → 怎么改」的顺序，把这份源码拆开讲。
2. 技术选型与目录结构：WASM 是怎么把 FFmpeg 搬进浏览器的
2.1 为什么是 WebAssembly 而不是纯 JS
FFmpeg 是 C 语言写的大型多媒体框架，代码量以百万行计，直接翻译成 JavaScript 既不现实也没性能。这个项目的核心思路是用 Emscripten 把 FFmpeg 的 C 源码编译成.wasm二进制，再配一层 JS 胶水代码负责内存分配、文件系统挂载和函数调用。浏览器加载 wasm 后，相当于在沙箱里跑了一个精简版的 FFmpeg 命令行。
常见做法是只编译需要的编解码器（比如 H.264、AAC、MP3），把体积压到几 MB 级别，否则全量编译出来的 wasm 动辄几十 MB，首屏加载直接翻车。项目里通常会有多个构建产物，对应不同的功能裁剪，选哪个取决于你要处理的格式。
2.2 目录结构长什么样
拿到源码后，先别急着跑，把目录扫一遍心里有数。典型的工程结构大致如下：
ffmpeg.js/ ├── src/ │ ├── ffmpeg.js # 主入口，封装 Worker 与 wasm 加载 │ ├── worker.js # Web Worker 内执行 FFmpeg 命令 │ └── utils.js # 文件读写、内存管理辅助 ├── dist/ │ ├── ffmpeg-core.wasm # 编译产物 │ └── ffmpeg-core.js # Emscripten 胶水层 ├── examples/ │ └── index.html # 浏览器端调用示例 ├── package.json └── build/ # Emscripten 编译脚本src/ffmpeg.js是对外暴露的 API 层，worker.js是真正干活的地方。为什么要拆 Worker？因为 FFmpeg 是同步阻塞的，放在主线程会把页面卡死，用户点个按钮整个界面就僵住，体验极差。用 Worker 把计算挪到后台线程，主线程还能继续响应交互。
2.3 核心 API 的调用链路
对外暴露的接口通常长这样，我按常见实现还原一下调用方式：
import { createFFmpeg, fetchFile } from './src/ffmpeg.js'; // 创建实例，log 为 true 时可以在控制台看到 FFmpeg 的原始输出 const ffmpeg = createFFmpeg({ log: true }); async function transcode(file) { // 1. 加载 wasm，首次调用会下载并实例化 await ffmpeg.load(); // 2. 把浏览器 File 对象写入虚拟文件系统 ffmpeg.FS('writeFile', 'input.mp4', await fetchFile(file)); // 3. 执行 FFmpeg 命令，参数与命令行一致 await ffmpeg.run('-i', 'input.mp4', '-t', '10', 'output.gif'); // 4. 从虚拟文件系统读回结果 const data = ffmpeg.FS('readFile', 'output.gif'); return new Blob([data.buffer], { type: 'image/gif' }); }这段代码的关键在FS这个方法。Emscripten 在 wasm 内部模拟了一个内存文件系统，writeFile把浏览器里的文件塞进去，run执行命令，readFile再把产物取出来。参数说明：-i指定输入，-t 10表示只处理前 10 秒，output.gif是输出文件名。命令格式和你在终端里敲的 FFmpeg 完全一致，学习成本几乎为零。
提示：
fetchFile是项目提供的辅助函数，负责把 File/Blob/URL 统一转成 Uint8Array，省去手动读 ArrayBuffer 的麻烦。
3. 跑起来：从零到第一个转码结果的完整步骤
3.1 环境准备与依赖安装
先把项目拉到本地，确认 Node 版本不要太老（建议 16 以上），然后装依赖：
# 进入项目目录 cd ffmpeg.js # 安装依赖，如果 package.json 里有 dev 脚本会一并装好 npm install # 启动本地静态服务，examples 目录里有现成的调用页面 npx serve examples为什么用静态服务而不是直接双击 HTML？因为 wasm 的加载受同源策略和 MIME 类型限制，file://协议下浏览器会拒绝实例化，这是新手最容易踩的坑。用serve或http-server起一个本地端口，访问http://localhost:3000就能看到示例页面。
3.2 加载 wasm 与首次调用
页面打开后，打开控制台观察加载过程。首次调用ffmpeg.load()时会去拉ffmpeg-core.wasm，体积视构建配置而定。加载完成后，控制台会打印 FFmpeg 的版本信息，看到类似FFmpeg version ...的输出就说明 wasm 已经跑起来了。
如果卡在加载阶段，先看 Network 面板里 wasm 文件是否 200，再看控制台有没有WebAssembly.instantiate相关报错。常见原因是路径配错——createFFmpeg支持传入corePath参数指定 wasm 的位置：
const ffmpeg = createFFmpeg({ log: true, corePath: '/dist/ffmpeg-core.js' // 指向胶水层，它会自动找同目录的 wasm });corePath指向的是 Emscripten 生成的 JS 胶水文件，wasm 会在同目录下自动定位。部署到 CDN 时把这个路径改成绝对地址即可。
3.3 一个完整的裁剪 + 转码示例
下面这段是我在示例基础上改的，把上传的视频裁成 5 秒并转成 webm，可以直接抄：
const input = document.querySelector('#file'); const ffmpeg = createFFmpeg({ log: true }); input.addEventListener('change', async (e) => { const file = e.target.files[0]; if (!ffmpeg.isLoaded()) await ffmpeg.load(); ffmpeg.FS('writeFile', 'src.mp4', await fetchFile(file)); // -ss 起点，-t 时长，-c:v 指定编码器 await ffmpeg.run( '-ss', '0', '-t', '5', '-i', 'src.mp4', '-c:v', 'libvpx', '-b:v', '1M', 'out.webm' ); const data = ffmpeg.FS('readFile', 'out.webm'); const url = URL.createObjectURL(new Blob([data.buffer], { type: 'video/webm' })); document.querySelector('video').src = url; });参数逐个说：-ss 0从第 0 秒开始，-t 5只取 5 秒，-c:v libvpx指定 VP8 编码器输出 webm，-b:v 1M限制码率 1Mbps 控制体积。注意-ss放在-i前面是快速定位，放在后面是精确裁剪，处理大文件时前者快很多。
3.4 验证结果与性能观察
转码完成后，把out.webm的 Blob URL 挂到<video>上播放，能正常播放就说明链路通了。性能方面，浏览器内转码比原生 FFmpeg 慢是正常的，wasm 有解释执行开销，加上单线程 Worker 没有多核并行。处理几十秒的短视频问题不大，长视频建议分片处理或者干脆放后端。
注意：不同浏览器对 wasm 的内存上限不同，处理大文件时可能触发
Out of memory。可以在createFFmpeg时通过mainName和内存参数调整，但根本上还是控制输入体积。
4. 核心模块拆解：Worker 通信与虚拟文件系统
4.1 主线程与 Worker 的消息协议
ffmpeg.js的主入口本质是一个消息代理。主线程调用run时，把命令参数序列化后postMessage给 Worker，Worker 执行完再把结果回传。简化后的通信逻辑如下：
// 主线程侧 worker.postMessage({ type: 'run', args: ['-i', 'in.mp4', 'out.gif'] }); worker.onmessage = ({ data }) => { if (data.type === 'log') { console.log('[ffmpeg]', data.message); // 转发 FFmpeg 日志 } else if (data.type === 'done') { resolve(data.result); // 执行完成 } };// Worker 侧 self.onmessage = async ({ data }) => { if (data.type === 'run') { // 劫持 stdout/stderr，把日志实时回传主线程 Module.print = (msg) => self.postMessage({ type: 'log', message: msg }); Module.exec(...data.args); // 调用 wasm 导出的入口 self.postMessage({ type: 'done' }); } };这套协议的关键在于日志转发。FFmpeg 执行时会往 stdout/stderr 打大量信息，如果不劫持，用户在页面上看不到任何进度，体验就像黑匣子。通过重写Module.print，把每条日志postMessage回主线程，前端就能做进度条或者实时输出。
4.2 虚拟文件系统的读写细节
Emscripten 的FS接口是内存文件系统的操作入口，常用方法就三个：writeFile、readFile、unlink。写入时传入的是Uint8Array，读取返回的也是Uint8Array，转 Blob 时注意用data.buffer而不是data本身，否则 Blob 构造会报类型错误。
处理完记得清理，否则多次调用会撑爆内存：
try { ffmpeg.FS('writeFile', 'tmp.mp4', await fetchFile(file)); await ffmpeg.run('-i', 'tmp.mp4', 'out.mp3'); const data = ffmpeg.FS('readFile', 'out.mp3'); return new Blob([data.buffer], { type: 'audio/mp3' }); } finally { // 无论成功失败都删掉临时文件 ffmpeg.FS('unlink', 'tmp.mp4'); }unlink只删文件不释放 wasm 堆内存，长时间运行的应用建议定期重建实例，或者用ffmpeg.exit()彻底销毁再重新load。
4.3 命令参数的映射规则
run接收的是可变参数，内部会拼成 FFmpeg 的 argv 数组。这里有个细节：参数里不能带空格分隔的字符串，必须一个参数一个元素。比如'-vf scale=320:240'要拆成'-vf', 'scale=320:240'，否则 wasm 侧解析会出错。我见过有人直接传一整条命令字符串，结果 FFmpeg 报Unrecognized option，排查半天才发现是参数没拆开。
5. 避坑与常见问题：那些让我加班到深夜的坑
5.1 wasm 加载 404 或 MIME 错误
现象：控制台报Failed to fetch dynamically imported module或WebAssembly.CompileError。原因通常是静态服务器没配 wasm 的 MIME 类型，或者corePath路径不对。解决：确认服务器返回application/wasm，路径用绝对地址，别用相对路径在子路由下翻车。
5.2 主线程卡死、页面无响应
现象：点击转码后整个页面冻结，连按钮都点不动。原因：把ffmpeg.run放在了主线程执行，同步阻塞了事件循环。解决：确保用的是项目自带的 Worker 封装，别自己图省事直接在主线程调 wasm。
5.3 大文件触发内存溢出
现象：处理超过几十 MB 的视频时报Cannot enlarge memory arrays。原因：wasm 默认堆内存有限，Emscripten 的ALLOW_MEMORY_GROWTH没开或者上限设小了。解决：换用开启了内存增长的构建产物，或者在前端做分片，把长视频切成小段分别处理再合并。
5.4 输出文件为空或格式不对
现象：readFile拿到的数据长度为 0，或者播放器打不开。原因：命令参数写错导致 FFmpeg 实际没产出文件，比如输出扩展名和编码器不匹配。解决：打开log: true看完整输出，确认最后有muxing overhead之类的成功日志，再检查输出文件名后缀。
5.5 多次调用后越来越慢
现象：连续转码几次后，每次耗时明显增加。原因：虚拟文件系统里的临时文件没清理，wasm 堆只增不减。解决：每次run结束在finally里unlink所有临时文件，必要时重建实例。
6. 二次开发：裁剪构建体积与封装业务组件
6.1 按需裁剪编解码器
默认构建往往带了一堆用不上的编码器，体积大得吓人。二次开发第一步就是改build/下的 Emscripten 编译脚本，用--enable-encoder和--disable-everything精确控制。比如只做视频转 GIF，就只保留 GIF 编码和对应解码器：
# 编译脚本片段，只开必要组件 emconfigure ./configure \ --disable-everything \ --enable-decoder=h264 \ --enable-encoder=gif \ --enable-demuxer=mov \ --enable-muxer=gif \ --disable-programs \ --disable-doc--disable-everything先把所有组件关掉，再逐个--enable打开需要的。这样编出来的 wasm 能从几十 MB 降到几 MB，首屏加载时间肉眼可见地缩短。改完记得跑一遍示例验证，别裁过头把要用的格式也关了。
6.2 封装成可复用的业务 Hook
在 React 或 Vue 项目里，我一般会把 ffmpeg 实例封装成一个 Hook，统一管理加载状态和错误处理：
function useFFmpeg() { const ref = useRef(null); const [ready, setReady] = useState(false); useEffect(() => { const ffmpeg = createFFmpeg({ log: false, corePath: '/wasm/ffmpeg-core.js' }); ffmpeg.load().then(() => { ref.current = ffmpeg; setReady(true); }); return () => ffmpeg.exit && ffmpeg.exit(); // 卸载时销毁 }, []); const exec = useCallback(async (args, outputName) => { if (!ready) throw new Error('ffmpeg not ready'); await ref.current.run(...args); const data = ref.current.FS('readFile', outputName); ref.current.FS('unlink', outputName); return new Blob([data.buffer]); }, [ready]); return { ready, exec }; }这样业务组件只管调exec，不用关心 wasm 生命周期。useEffect的清理函数里调exit很关键，否则单页应用路由切换后旧实例还占着内存。
6.3 验证改造效果的方法
改完之后怎么确认没改坏？我的习惯是准备一组固定测试用例：一段 10 秒 mp4、一张 png、一个 mp3，分别跑裁剪、转 GIF、抽音频三条命令，对比输出文件的时长和大小。再打开log: true看有没有 warning。这套流程走下来，基本能拦住大部分回归问题。
| 改造点 | 验证方式 | 预期结果 |
|---|---|---|
| 裁剪编解码器 | 跑三条固定命令 | 全部成功，体积下降 |
| Hook 封装 | 路由切换后重复调用 | 无内存泄漏，第二次仍可用 |
| corePath 改 CDN | 清缓存强刷 | wasm 正常加载 |
从那以后我每次改构建脚本，都强制走一遍这三条用例再提交，血泪经验换来的习惯。希望帮到你。
本文还有配套的精品资源，点击获取
