安装

本页面提供了在 Web 应用程序中安装和配置 ffmpeg.wasm 的技术说明。ffmpeg.wasm 是 FFmpeg 的 WebAssembly 移植版本，可在浏览器内直接实现高性能的视频和音频处理。

包架构

ffmpeg.wasm 生态系统被组织为一个包含多个专用包的 monorepo。安装至少需要主 API 和工具包。

代码实体映射

下图将高级系统组件映射到相应的 NPM 包和内部入口点。

安装方法

包管理器

通过 npm 或 yarn 安装核心库和工具。这些包提供了与 WebAssembly 二进制文件交互所需的 JavaScript 胶水代码和 TypeScript 定义。

# Using npm
npm install @ffmpeg/ffmpeg @ffmpeg/util
  
# Using yarn
yarn add @ffmpeg/ffmpeg @ffmpeg/util

CDN 限制和要求

使用 <script> 标签直接从 CDN（例如 jsdelivr）导入 @ffmpeg/ffmpeg 通常 不受支持，因为该库在内部会启动一个 Web Worker。浏览器对 Workers 实施同源策略，这意味着 worker 脚本通常必须与主应用程序来自同一源，或者配置特定的 CORS 标头。

对于生产环境，建议将以下资源托管在您自己的服务器上：

@ffmpeg/ffmpeg (主 API)
@ffmpeg/core 或 @ffmpeg/core-mt (WASM 和 Worker 文件)

分发格式

这些包提供多种分发格式以支持不同的构建管道和运行时环境。

格式	`@ffmpeg/ffmpeg` 中的路径	用途
ESM	`./dist/esm/index.js`	现代打包工具 (Vite, Webpack 5)
UMD	`./dist/umd/ffmpeg.js`	遗留支持或直接浏览器使用
Worker	`./dist/esm/worker.js`	内部 worker 逻辑
Types	`./dist/esm/index.d.ts`	TypeScript 开发

安全要求 (COOP/COEP)

由于 ffmpeg.wasm（特别是多线程版本）使用了 SharedArrayBuffer，浏览器需要一个“跨域隔离”状态。这是通过在托管您应用的服务器上设置特定 HTTP 标头来实现的。

所需标头

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

如果没有这些标头，SharedArrayBuffer 将为 undefined，并且多线程核心将无法初始化。

加载 WebAssembly 核心

与标准库不同，ffmpeg.wasm 不捆绑沉重的 WebAssembly 二进制文件（约 30MB）。这些必须在运行时通过 ffmpeg.load() 方法加载。您必须提供 baseURL 或核心文件的具体 URL。

BaseURL 选择：ESM vs UMD

当从 CDN 或本地目录加载核心时，文件结构必须与分发类型匹配。

实现示例 (多线程)

在现代框架中，使用来自 @ffmpeg/util 的 toBlobURL 来获取核心资源。当资源托管在不同域（如 CDN）上时，这通常用于绕过 CORS 问题。

const baseURL = 'https://cdn.jsdelivr.net/npm/@ffmpeg/core-mt@0.12.10/dist/esm';
const ffmpeg = new FFmpeg();
  
await ffmpeg.load({
 coreURL: await toBlobURL(`${baseURL}/ffmpeg-core.js`, 'text/javascript'),
 wasmURL: await toBlobURL(`${baseURL}/ffmpeg-core.wasm`, 'application/wasm'),
 workerURL: await toBlobURL(`${baseURL}/ffmpeg-core.worker.js`, 'text/javascript'),
});

环境约束

仅限浏览器：ffmpeg.wasm 专为浏览器环境设计。Node.js 支持已在 0.12.x+ 版本中停止。
Node.js 版本：对于开发工具（打包、测试），需要 Node.js >=18.x。
内存：确保浏览器有足够的内存；WebAssembly 目前有 2GB 限制。