ffmpeg-wasm 完整安装指南（Ubuntu 24.04）

海兰2026-08-10 9:17

从零搭建 ffmpeg-wasm 开发环境，将 FFmpeg 编译为 WebAssembly，在 Node.js 中享受原生级的媒体处理能力。

📖 前言： ffmpeg-wasm

FFmpeg 是业界最强的多媒体处理工具，但传统的 C 编译版本依赖系统底层库，移植困难。ffmpeg-wasm 项目利用 Emscripten 将 FFmpeg 编译成 WebAssembly（WASM），使其可以在 Node.js 环境中直接运行，无需额外安装系统级 FFmpeg。

  • 轻量 ：最终 WASM 文件仅约 8.5 MB，却支持数十种音视频编解码器。
  • 跨平台：WASM 是字节码，可在任何支持 Node.js 的系统上运行。
  • 可编程：提供 TypeScript API，既可当作命令行工具，也可嵌入你的应用。
  • 许可证友好：使用 LGPL-2.1-or-later 许可，不包含 GPL 或非自由组件。

下面将在 Ubuntu 24.04 上完成全部构建。

🗺️ 整体工作流程

下图展示了从系统准备到最终使用的完整流程，方便你掌握全局：
#mermaid-svg-PxIoUUDM9aZlfBaz{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-PxIoUUDM9aZlfBaz .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-PxIoUUDM9aZlfBaz .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-PxIoUUDM9aZlfBaz .error-icon{fill:#552222;}#mermaid-svg-PxIoUUDM9aZlfBaz .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-PxIoUUDM9aZlfBaz .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-PxIoUUDM9aZlfBaz .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-PxIoUUDM9aZlfBaz .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-PxIoUUDM9aZlfBaz .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-PxIoUUDM9aZlfBaz .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-PxIoUUDM9aZlfBaz .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-PxIoUUDM9aZlfBaz .marker{fill:#333333;stroke:#333333;}#mermaid-svg-PxIoUUDM9aZlfBaz .marker.cross{stroke:#333333;}#mermaid-svg-PxIoUUDM9aZlfBaz svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-PxIoUUDM9aZlfBaz p{margin:0;}#mermaid-svg-PxIoUUDM9aZlfBaz .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-PxIoUUDM9aZlfBaz .cluster-label text{fill:#333;}#mermaid-svg-PxIoUUDM9aZlfBaz .cluster-label span{color:#333;}#mermaid-svg-PxIoUUDM9aZlfBaz .cluster-label span p{background-color:transparent;}#mermaid-svg-PxIoUUDM9aZlfBaz .label text,#mermaid-svg-PxIoUUDM9aZlfBaz span{fill:#333;color:#333;}#mermaid-svg-PxIoUUDM9aZlfBaz .node rect,#mermaid-svg-PxIoUUDM9aZlfBaz .node circle,#mermaid-svg-PxIoUUDM9aZlfBaz .node ellipse,#mermaid-svg-PxIoUUDM9aZlfBaz .node polygon,#mermaid-svg-PxIoUUDM9aZlfBaz .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-PxIoUUDM9aZlfBaz .rough-node .label text,#mermaid-svg-PxIoUUDM9aZlfBaz .node .label text,#mermaid-svg-PxIoUUDM9aZlfBaz .image-shape .label,#mermaid-svg-PxIoUUDM9aZlfBaz .icon-shape .label{text-anchor:middle;}#mermaid-svg-PxIoUUDM9aZlfBaz .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-PxIoUUDM9aZlfBaz .rough-node .label,#mermaid-svg-PxIoUUDM9aZlfBaz .node .label,#mermaid-svg-PxIoUUDM9aZlfBaz .image-shape .label,#mermaid-svg-PxIoUUDM9aZlfBaz .icon-shape .label{text-align:center;}#mermaid-svg-PxIoUUDM9aZlfBaz .node.clickable{cursor:pointer;}#mermaid-svg-PxIoUUDM9aZlfBaz .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-PxIoUUDM9aZlfBaz .arrowheadPath{fill:#333333;}#mermaid-svg-PxIoUUDM9aZlfBaz .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-PxIoUUDM9aZlfBaz .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-PxIoUUDM9aZlfBaz .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-PxIoUUDM9aZlfBaz .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-PxIoUUDM9aZlfBaz .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-PxIoUUDM9aZlfBaz .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-PxIoUUDM9aZlfBaz .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-PxIoUUDM9aZlfBaz .cluster text{fill:#333;}#mermaid-svg-PxIoUUDM9aZlfBaz .cluster span{color:#333;}#mermaid-svg-PxIoUUDM9aZlfBaz div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-PxIoUUDM9aZlfBaz .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-PxIoUUDM9aZlfBaz rect.text{fill:none;stroke-width:0;}#mermaid-svg-PxIoUUDM9aZlfBaz .icon-shape,#mermaid-svg-PxIoUUDM9aZlfBaz .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-PxIoUUDM9aZlfBaz .icon-shape p,#mermaid-svg-PxIoUUDM9aZlfBaz .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-PxIoUUDM9aZlfBaz .icon-shape .label rect,#mermaid-svg-PxIoUUDM9aZlfBaz .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-PxIoUUDM9aZlfBaz .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-PxIoUUDM9aZlfBaz .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-PxIoUUDM9aZlfBaz :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 🖥️ 系统准备
📦 安装 Node.js 24+
🔧 安装 Emscripten SDK
📂 克隆 ffmpeg-wasm 仓库
📥 安装项目依赖（pnpm install）
🔨 执行构建（pnpm build）
✅ 验证构建产物
🧪 运行测试（pnpm verify）
⌨️ CLI 使用 或 📐 API 集成

整个构建过程大约需要 15~30 分钟 （视网络与 CPU 性能而定），请确保网络通畅，并预留至少 2 GB 磁盘空间。

📊 关键依赖与版本一览

使用 erDiagram 形式展示核心组件的版本要求：
#mermaid-svg-4y9i06eX6cplodIj{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-4y9i06eX6cplodIj .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-4y9i06eX6cplodIj .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-4y9i06eX6cplodIj .error-icon{fill:#552222;}#mermaid-svg-4y9i06eX6cplodIj .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-4y9i06eX6cplodIj .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-4y9i06eX6cplodIj .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-4y9i06eX6cplodIj .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-4y9i06eX6cplodIj .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-4y9i06eX6cplodIj .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-4y9i06eX6cplodIj .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-4y9i06eX6cplodIj .marker{fill:#333333;stroke:#333333;}#mermaid-svg-4y9i06eX6cplodIj .marker.cross{stroke:#333333;}#mermaid-svg-4y9i06eX6cplodIj svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-4y9i06eX6cplodIj p{margin:0;}#mermaid-svg-4y9i06eX6cplodIj .entityBox{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-4y9i06eX6cplodIj .relationshipLabelBox{fill:hsl(80, 100%, 96.2745098039%);opacity:0.7;background-color:hsl(80, 100%, 96.2745098039%);}#mermaid-svg-4y9i06eX6cplodIj .relationshipLabelBox rect{opacity:0.5;}#mermaid-svg-4y9i06eX6cplodIj .labelBkg{background-color:rgba(248.6666666666, 255, 235.9999999999, 0.5);}#mermaid-svg-4y9i06eX6cplodIj .edgeLabel .label{fill:#9370DB;font-size:14px;}#mermaid-svg-4y9i06eX6cplodIj .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-4y9i06eX6cplodIj .edge-pattern-dashed{stroke-dasharray:8,8;}#mermaid-svg-4y9i06eX6cplodIj .node rect,#mermaid-svg-4y9i06eX6cplodIj .node circle,#mermaid-svg-4y9i06eX6cplodIj .node ellipse,#mermaid-svg-4y9i06eX6cplodIj .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-4y9i06eX6cplodIj .relationshipLine{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-4y9i06eX6cplodIj .marker{fill:none!important;stroke:#333333!important;stroke-width:1;}#mermaid-svg-4y9i06eX6cplodIj .edgeLabel{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-4y9i06eX6cplodIj .edgeLabel .label rect{fill:rgba(232,232,232, 0.8);}#mermaid-svg-4y9i06eX6cplodIj .edgeLabel .label text{fill:#333;}#mermaid-svg-4y9i06eX6cplodIj :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} FFMPEG
string
version
n8.1.2
LIBVPX
string
version
v1.16.0
NODE
string
version
24+
#mermaid-svg-rSM6RbvgY50zG69f{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-rSM6RbvgY50zG69f .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-rSM6RbvgY50zG69f .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-rSM6RbvgY50zG69f .error-icon{fill:#552222;}#mermaid-svg-rSM6RbvgY50zG69f .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-rSM6RbvgY50zG69f .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-rSM6RbvgY50zG69f .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-rSM6RbvgY50zG69f .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-rSM6RbvgY50zG69f .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-rSM6RbvgY50zG69f .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-rSM6RbvgY50zG69f .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-rSM6RbvgY50zG69f .marker{fill:#333333;stroke:#333333;}#mermaid-svg-rSM6RbvgY50zG69f .marker.cross{stroke:#333333;}#mermaid-svg-rSM6RbvgY50zG69f svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-rSM6RbvgY50zG69f p{margin:0;}#mermaid-svg-rSM6RbvgY50zG69f .entityBox{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-rSM6RbvgY50zG69f .relationshipLabelBox{fill:hsl(80, 100%, 96.2745098039%);opacity:0.7;background-color:hsl(80, 100%, 96.2745098039%);}#mermaid-svg-rSM6RbvgY50zG69f .relationshipLabelBox rect{opacity:0.5;}#mermaid-svg-rSM6RbvgY50zG69f .labelBkg{background-color:rgba(248.6666666666, 255, 235.9999999999, 0.5);}#mermaid-svg-rSM6RbvgY50zG69f .edgeLabel .label{fill:#9370DB;font-size:14px;}#mermaid-svg-rSM6RbvgY50zG69f .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-rSM6RbvgY50zG69f .edge-pattern-dashed{stroke-dasharray:8,8;}#mermaid-svg-rSM6RbvgY50zG69f .node rect,#mermaid-svg-rSM6RbvgY50zG69f .node circle,#mermaid-svg-rSM6RbvgY50zG69f .node ellipse,#mermaid-svg-rSM6RbvgY50zG69f .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-rSM6RbvgY50zG69f .relationshipLine{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-rSM6RbvgY50zG69f .marker{fill:none!important;stroke:#333333!important;stroke-width:1;}#mermaid-svg-rSM6RbvgY50zG69f .edgeLabel{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-rSM6RbvgY50zG69f .edgeLabel .label rect{fill:rgba(232,232,232, 0.8);}#mermaid-svg-rSM6RbvgY50zG69f .edgeLabel .label text{fill:#333;}#mermaid-svg-rSM6RbvgY50zG69f :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} EMSCRIPTEN
string
version
latest (3.1.x)
BUILD-TOOLS
string
gcc
13.x
string
make
4.x
string
nasm
2.16.x

提示 ：构建时可通过环境变量 FFMPEG_VERSION、LAME_REF、LIBVPX_REF 覆盖默认版本，但推荐使用官方指定版本以保证兼容性。

🐧 第一部分：系统准备

在 Ubuntu 24.04 上安装基础构建工具链，这些是后续编译所必需的。

1️⃣ 更新系统包

首先确保系统包索引和已装软件都是最新的：

bash 复制代码 
sudo apt update && sudo apt upgrade -y

2️⃣ 安装编译工具链、Git、Python 及 pkg-config

Emscripten 和 FFmpeg 构建需要完整的 C/C++ 编译环境、Git（下载源码）、Python 3（Emscripten 内部使用）以及 pkg-config（用于查找库）。

bash 复制代码 
sudo apt install -y build-essential cmake git curl wget unzip python3 python3-pip pkg-config
  • build-essential：提供 gcc、g++、make 等核心编译工具。
  • cmake：某些外部库（如 libvpx）使用 CMake 构建。
  • python3：Emscripten 的工具脚本依赖 Python。
  • pkg-config：帮助 FFmpeg 配置时找到已安装的库。

3️⃣ 安装汇编器（nasm + yasm）

LAME（MP3 编码器）的编译需要汇编器优化音质。如果缺失，LAME 构建会失败。

bash 复制代码 
sudo apt install -y nasm yasm

4️⃣ 安装 Autotools

LAME 使用 Autotools（autoconf、automake、libtool）作为构建系统，必须提前安装。

bash 复制代码 
sudo apt install -y autoconf automake libtool

5️⃣ 验证基础工具

运行以下命令，确认所有工具安装正确：

bash 复制代码 
gcc --version && make --version && nasm --version && python3 --version

预期输出类似：

  • gcc (Ubuntu 13.2.0)
  • GNU Make 4.3
  • NASM version 2.16.01
  • Python 3.12.3

✅ Ubuntu 24.04 自带 Python 3.12，完全满足 Emscripten 要求。

📦 第二部分：安装 Node.js 24+

ffmpeg-wasm 在运行和构建时都严格依赖 Node.js 24 或更高版本 ，因为底层使用了现代 JavaScript 特性（如 Buffer 的 WASM 内存操作）。

1️⃣ 通过 NodeSource 添加官方仓库

bash 复制代码 
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

2️⃣ 安装 Node.js 和 npm

bash 复制代码 
sudo apt install -y nodejs

3️⃣ 验证版本

bash 复制代码 
node --version   # 应显示 v24.x.x 或更高
npm --version    # 通常为 10.x.x

如果版本低于 24，请检查 NodeSource 仓库是否正确添加。

4️⃣ 安装 pnpm（项目指定的包管理器）

ffmpeg-wasm 使用 pnpm 管理依赖，比 npm 更快且节省磁盘空间。

bash 复制代码 
sudo npm install -g pnpm

验证安装：

bash 复制代码 
pnpm --version   # 应为 9.x 或更高

📌 pnpm 项目锁定了 pnpm，使用其他包管理器可能导致依赖版本不匹配，建议严格遵循。

🔧 第三部分：安装 Emscripten SDK

Emscripten 是一个 LLVM/Clang 编译器工具链，能将 C/C++ 代码编译为 WebAssembly。我们需要它的 emcc、em++、emar、emranlib 等工具。

1️⃣ 克隆 Emscripten SDK 仓库

将仓库放在家目录下，方便管理：

bash 复制代码 
cd ~
git clone https://github.com/emscripten-core/emsdk.git

2️⃣ 进入目录并安装最新版本

bash 复制代码 
cd ~/emsdk
./emsdk install latest

⏳ 这一步会下载约 1 GB 的工具链和依赖（包括内部 Node.js 和 Python），请耐心等待。

3️⃣ 激活 Emscripten

bash 复制代码 
./emsdk activate latest

4️⃣ 将 Emscripten 加入当前会话 PATH

bash 复制代码 
source ~/emsdk/emsdk_env.sh

5️⃣ 永久生效（写入 ~/.bashrc）

避免每次打开终端都要手动 source：

bash 复制代码 
echo 'source ~/emsdk/emsdk_env.sh' >> ~/.bashrc
source ~/.bashrc

6️⃣ 验证所有工具可用

bash 复制代码 
emcc --version && em++ --version && emar --version && emranlib --version

预期输出会显示 Emscripten 版本及 clang 信息。四个命令都不可缺失，否则构建会中断。

💡 如果提示 command not found，请重新执行 source ~/emsdk/emsdk_env.sh。

🔨 第四部分：克隆与构建

一切准备就绪，开始编译 ffmpeg-wasm 核心。

1️⃣ 克隆项目仓库

bash 复制代码 
cd ~
git clone https://github.com/openclaw/ffmpeg-wasm.git
cd ffmpeg-wasm

2️⃣ 安装项目依赖

使用 pnpm 安装所有 Node.js 依赖：

bash 复制代码 
pnpm install

3️⃣ 执行完整构建

pnpm build 会依次执行以下阶段：
#mermaid-svg-vYyL8TEX8vm9BrJH{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-vYyL8TEX8vm9BrJH .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-vYyL8TEX8vm9BrJH .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-vYyL8TEX8vm9BrJH .error-icon{fill:#552222;}#mermaid-svg-vYyL8TEX8vm9BrJH .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-vYyL8TEX8vm9BrJH .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-vYyL8TEX8vm9BrJH .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-vYyL8TEX8vm9BrJH .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-vYyL8TEX8vm9BrJH .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-vYyL8TEX8vm9BrJH .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-vYyL8TEX8vm9BrJH .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-vYyL8TEX8vm9BrJH .marker{fill:#333333;stroke:#333333;}#mermaid-svg-vYyL8TEX8vm9BrJH .marker.cross{stroke:#333333;}#mermaid-svg-vYyL8TEX8vm9BrJH svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-vYyL8TEX8vm9BrJH p{margin:0;}#mermaid-svg-vYyL8TEX8vm9BrJH .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-vYyL8TEX8vm9BrJH .cluster-label text{fill:#333;}#mermaid-svg-vYyL8TEX8vm9BrJH .cluster-label span{color:#333;}#mermaid-svg-vYyL8TEX8vm9BrJH .cluster-label span p{background-color:transparent;}#mermaid-svg-vYyL8TEX8vm9BrJH .label text,#mermaid-svg-vYyL8TEX8vm9BrJH span{fill:#333;color:#333;}#mermaid-svg-vYyL8TEX8vm9BrJH .node rect,#mermaid-svg-vYyL8TEX8vm9BrJH .node circle,#mermaid-svg-vYyL8TEX8vm9BrJH .node ellipse,#mermaid-svg-vYyL8TEX8vm9BrJH .node polygon,#mermaid-svg-vYyL8TEX8vm9BrJH .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-vYyL8TEX8vm9BrJH .rough-node .label text,#mermaid-svg-vYyL8TEX8vm9BrJH .node .label text,#mermaid-svg-vYyL8TEX8vm9BrJH .image-shape .label,#mermaid-svg-vYyL8TEX8vm9BrJH .icon-shape .label{text-anchor:middle;}#mermaid-svg-vYyL8TEX8vm9BrJH .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-vYyL8TEX8vm9BrJH .rough-node .label,#mermaid-svg-vYyL8TEX8vm9BrJH .node .label,#mermaid-svg-vYyL8TEX8vm9BrJH .image-shape .label,#mermaid-svg-vYyL8TEX8vm9BrJH .icon-shape .label{text-align:center;}#mermaid-svg-vYyL8TEX8vm9BrJH .node.clickable{cursor:pointer;}#mermaid-svg-vYyL8TEX8vm9BrJH .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-vYyL8TEX8vm9BrJH .arrowheadPath{fill:#333333;}#mermaid-svg-vYyL8TEX8vm9BrJH .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-vYyL8TEX8vm9BrJH .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-vYyL8TEX8vm9BrJH .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-vYyL8TEX8vm9BrJH .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-vYyL8TEX8vm9BrJH .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-vYyL8TEX8vm9BrJH .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-vYyL8TEX8vm9BrJH .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-vYyL8TEX8vm9BrJH .cluster text{fill:#333;}#mermaid-svg-vYyL8TEX8vm9BrJH .cluster span{color:#333;}#mermaid-svg-vYyL8TEX8vm9BrJH div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-vYyL8TEX8vm9BrJH .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-vYyL8TEX8vm9BrJH rect.text{fill:none;stroke-width:0;}#mermaid-svg-vYyL8TEX8vm9BrJH .icon-shape,#mermaid-svg-vYyL8TEX8vm9BrJH .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-vYyL8TEX8vm9BrJH .icon-shape p,#mermaid-svg-vYyL8TEX8vm9BrJH .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-vYyL8TEX8vm9BrJH .icon-shape .label rect,#mermaid-svg-vYyL8TEX8vm9BrJH .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-vYyL8TEX8vm9BrJH .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-vYyL8TEX8vm9BrJH .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-vYyL8TEX8vm9BrJH :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 输出到 dist/
ffmpeg.wasm
ffprobe.wasm
相关 JavaScript 胶水代码
编译 FFmpeg
配置 FFmpeg 为 wasm 目标
emcc 编译生成 .wasm 和 .js
编译外部库
编译 LAME 静态库
编译 libvpx 静态库
下载源码到 .cache/
FFmpeg n8.1.2
LAME 2badea...
libvpx v1.16.0

运行构建命令：

bash 复制代码 
pnpm build

构建过程中会：

  • 下载约 500 MB 的源码压缩包到 .cache/（后续重复构建会复用）。
  • 分别编译 LAME 和 libvpx 为静态库（.a 文件）。
  • 使用 Emscripten 将 FFmpeg 和 FFprobe 编译为 WASM 模块。
  • 将生成的 ffmpeg.wasm、ffprobe.wasm 以及 JavaScript 胶水代码放入 dist/ 目录。

⚠️ 资源消耗 ：此步骤需要至少 8 GB 内存 + 4 GB swap，否则可能触发 OOM（内存不足）。如果机器内存较小，请提前创建 swap（见故障排查部分）。

4️⃣ 验证构建产物

检查 dist/ 目录是否生成文件：

bash 复制代码 
ls -la dist/
du -sh dist/   # 应约为 8.5 MB

5️⃣ 运行验证测试

项目提供了完整的测试套件，用于确保所有功能正常（包括 FFprobe 文本/JSON 输出、MP4/MP3 转换、管道输入输出、PNG 提取等）：

bash 复制代码 
pnpm verify

如果一切顺利，你会看到 All verification tests passed。

📝 dist/ 被 .gitignore 忽略，因此每次构建都必须从源码重新生成，切勿手动修改其中的文件。

⌨️ 第五部分：CLI 使用

构建完成后，可以直接通过 Node.js 调用编译好的 CLI 入口，用法与原生 FFmpeg/FFprobe 几乎一致。

通用语法

bash 复制代码 
node lib/src/cli.js [FFmpeg 参数]
node lib/src/ffprobe-cli.js [FFprobe 参数]

示例 1：FFprobe 获取视频时长（秒）

bash 复制代码 
node lib/src/ffprobe-cli.js -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 input.mp4

示例 2：输出完整格式信息（JSON）

bash 复制代码 
node lib/src/ffprobe-cli.js -v error -show_format input.mp4

示例 3：从视频提取单声道 16kHz WAV 音频

bash 复制代码 
node lib/src/cli.js -hide_banner -loglevel error -i input.mp4 -vn -ac 1 -ar 16000 audio.wav
  • -vn：不输出视频流
  • -ac 1：单声道
  • -ar 16000：采样率 16kHz

示例 4：提取第一帧为 PNG

bash 复制代码 
node lib/src/cli.js -hide_banner -i input.mp4 -frames:v 1 frame.png

示例 5：截取前 5 秒视频（保留音视频，快速启动）

bash 复制代码 
node lib/src/cli.js -hide_banner -ss 0 -i input.mp4 -t 5 -map 0:v:0 -map 0:a? -c copy -movflags +faststart clip.mp4
  • -ss 0 -t 5：从第 0 秒开始截取 5 秒
  • -map 0:v:0 -map 0:a?：保留第一条视频流和所有音频流（若有）
  • -c copy：流复制，不重新编码（速度快）
  • -movflags +faststart：将 moov 原子移到文件开头，便于网络播放

💡 所有 CLI 命令均会自动禁用 -nostdin（除非你显式提供），避免意外阻塞。

📐 第六部分：TypeScript API

将 ffmpeg-wasm 集成到你的项目中，使用 JavaScript/TypeScript 进行编程化调用。

导入核心函数

typescript 复制代码 
import { execFfmpeg, runFfmpeg, runFfprobe } from '@steipete/ffmpeg-wasm-local';
  • runFfmpeg / runFfprobe：缓冲模式，适合处理小文件，返回 stdout/stderr 的 Buffer。
  • execFfmpeg：流式模式，适合大文件，直接输出到父进程的 stdio，仅返回退出码。

示例 1：FFprobe 查询时长（缓冲模式）

typescript 复制代码 
const probe = await runFfprobe([
  "-v", "error",
  "-show_entries", "format=duration",
  "-of", "default=noprint_wrappers=1:nokey=1",
  "input.mp4",
]);
if (probe.exitCode !== 0) {
  throw new Error(probe.stderrText);
}
console.log("Duration:", probe.stdoutText);  // 输出秒数

示例 2：FFmpeg 转换视频为 WAV（缓冲模式）

typescript 复制代码 
const wav = await runFfmpeg([
  "-hide_banner", "-loglevel", "error",
  "-i", "input.mp4",
  "-vn", "-ac", "1", "-ar", "16000",
  "-f", "wav", "-",   // 输出到 stdout
]);
// wav.stdoutBuffer 包含 WAV 文件的二进制数据

示例 3：流式转换（直接输出到文件）

typescript 复制代码 
const exitCode = await execFfmpeg([
  "-hide_banner",
  "-i", "input.mp4",
  "audio.mp3",
]);
console.log("转换完成，退出码：", exitCode);

下游工具集成

如果你开发的工具需要调用 ffmpeg-wasm，可以通过环境变量指定入口路径：

bash 复制代码 
export FFMPEG_PATH="$PWD/lib/src/cli.js"
export FFPROBE_PATH="$PWD/lib/src/ffprobe-cli.js"
your-tool ...

📌 API 高级选项 ：runFfmpeg 等函数支持传递 distDir（自定义资产目录）、cwd（工作目录）、env（环境变量）、stdin（管道输入）、timeoutMs（超时毫秒数），灵活满足各种场景。

🚨 第七部分：故障排查

构建和使用中可能遇到的问题及解决方案。

❌ emcc: command not found

原因：Emscripten 环境未加载。

解决：

bash 复制代码 
source ~/emsdk/emsdk_env.sh

如果仍失败，检查 ~/emsdk 目录是否存在，并确认 emsdk_env.sh 已写入 ~/.bashrc。

❌ Node version too old

原因：Node.js 版本低于 24。

解决：通过 NodeSource 安装正确的版本：

bash 复制代码 
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version   # 确认 >= 24.0.0

❌ nasm/yasm not found

原因：汇编器未安装，LAME 构建失败。

解决：

bash 复制代码 
sudo apt install -y nasm yasm

然后重新运行 pnpm build。

❌ pnpm: command not found

原因：pnpm 未全局安装。

解决：

bash 复制代码 
sudo npm install -g pnpm

❌ 构建时内存不足（OOM）

现象 ：编译过程中 emcc 进程被杀死，报 Killed。

原因：Emscripten 编译大型 C++ 项目时需要大量内存（常超过 4 GB）。

解决：创建 swap 文件临时扩充内存：

bash 复制代码 
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

建议物理内存 + swap 至少 8 GB。

❌ 网络下载超时

现象：克隆 FFmpeg/LAME/libvpx 源码时连接中断。

解决：设置 Git 低速率超时阈值：

bash 复制代码 
export GIT_HTTP_LOW_SPEED_LIMIT=1000
export GIT_HTTP_LOW_SPEED_TIME=600

然后重新运行构建。

❌ 构建产物异常

解决：清理所有缓存后重新构建：

bash 复制代码 
rm -rf .cache dist node_modules
pnpm install
pnpm build

📌 CI/CD 建议 ：在持续集成环境中，务必从源码重新构建 WASM 资产，不要依赖提交的 dist/，以确保许可证合规和代码完整性。

🎉 结语

至此，已经完整走通了 ffmpeg-wasm 的安装与使用流程。现在可以：

  • 在 Node.js 脚本中调用熟悉的 FFmpeg 命令。
  • 将媒体处理能力嵌入你的 Web 应用（通过 Node.js 后端）。
  • 借助 TypeScript API 构建更复杂的自动化工作流。
相关推荐
程序员老陆4 小时前
FFmpeg libswresample 模块的关键函数swr_convert 到底在干嘛？
ffmpeg·音视频·格式转换·音频重采样
海兰4 小时前
云原生持续交付平台 Zadig 在 Ubuntu 24.04 上的部署及使用指南
linux·ubuntu·云原生
Anesthesia丶6 小时前
PromoxVE安装笔记
笔记·ubuntu·server·promox
常乐か19 小时前
VMware Workstation Pro 17 搭建 Ubuntu 24.04 完整指南
linux·运维·ubuntu
PGCCC1 天前
Ubuntu 安装 PostgreSQL 16 完整教程（2026）：从仓库配置到远程连接
linux·ubuntu·postgresql
常乐か1 天前
在 Ubuntu 24.04 中编译 Qt 5.15.2 项目完全指南
linux·qt·ubuntu
hello_fengfeng1 天前
fcitx4 和 fcitx5 输入法包冲突
ubuntu
我是小灰灰吖1 天前
Ubuntu 22.04 切换为 X11 会话以解决 QT 桌面程序兼容性问题
linux·qt·ubuntu
≮傷￡≯√1 天前
QT配置FFmpeg
开发语言·qt·ffmpeg
热门推荐
01GitHub 镜像站点02如何新建文件夹？ 电脑新建文件夹的4种方法03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）042026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路07Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费08历年考研数学一、数学二、数学三真题试卷及答案PDF092026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片1000 Debian字符界面如何支持中文