设置开发环境
本文档提供了为 ffmpeg.wasm 设置开发环境的详细指南。内容涵盖构建 WebAssembly 核心的前置条件、管理本地资源以及配置用于跨域隔离的开发服务器。
系统要求
构建 WebAssembly 核心需要一个容器化环境来管理 Emscripten 工具链和库依赖项。
| 组件 | 要求 | 用途 |
|---|---|---|
| Docker | 23.0+ | 用于多阶段构建中使用的 buildx 支持 |
| Make | 最新版 | 用于执行 Makefile 中定义的构建目标 |
| Node.js | 18.x+ | 用于包管理和运行开发脚本 |
本地资源设置
为了避免在每次开发会话期间从 CDN 下载大型二进制文件，该项目提供了一个脚本来从 npm 注册表获取预构建的资源并存储到本地。
download-assets.js
脚本 scripts/download-assets.js 自动化检索 @ffmpeg/ffmpeg、@ffmpeg/util、@ffmpeg/core 和 @ffmpeg/core-mt 的 tarball 包。
- 版本跟踪: 该脚本锁定核心和实用程序包的具体版本以确保兼容性
- 解压: 它从
https://registry.npmjs.org下载.tgz文件并将它们解压到public/assets目录 - 本地使用: 下载后，这些资源可以在应用程序的
ffmpeg.load()配置中使用本地路径引用，而不是远程 URL。
构建 WebAssembly 核心
核心模块 (@ffmpeg/core 和 @ffmpeg/core-mt) 使用 Docker 和 Makefile 进行构建。构建过程支持不同的配置，包括开发（启用分析）和生产（启用优化）。
Makefile 目标
Makefile 定义了多个目标以简化 Docker 构建过程：
| 目标 | 描述 | 应用的标志 |
|---|---|---|
make dev | 单线程开发构建 | --profiling, --progress=plain |
make dev-mt | 多线程开发构建 | --profiling, -sUSE_PTHREADS, -pthread |
make prd | 单线程生产构建 | -O3, -msimd128 |
make prd-mt | 多线程生产构建 | -O3, -msimd128, -sUSE_PTHREADS, -pthread |
自定义构建以减小体积
开发者可以通过修改 Dockerfile 来排除不必要的库从而减小二进制文件大小。如贡献指南所述，这是一个四步过程：
- 移除库构建器: 删除
FROM emsdk-base AS <lib>-builder块 - 移除复制指令: 在
ffmpeg-base阶段删除COPY --from=<lib>-builder行 - 移除配置标志: 从
ffmpeg-builder阶段移除--enable-lib<lib>标志 - 移除链接器标志: 从
ffmpeg-wasm-builder阶段的FFMPEG_LIBS中移除库标志（例如-lwebp）
开发服务器配置
在使用多线程版本 (@ffmpeg/core-mt) 进行开发时，浏览器需要跨源隔离以启用 SharedArrayBuffer。
COOP/COEP 头信息
开发服务器（无论是使用 Vite、Express 还是其他工具）必须提供以下头信息：
Cross-Origin-Opener-Policy: same-originCross-Origin-Embedder-Policy: require-corp
Vite 配置示例
在使用 Vite 的项目中（如提供的 Vue 和 React 示例），这些头信息通常配置在 vite.config.ts 中。加载核心时，还必须提供 worker 和 wasm 文件的正确 URL：
组件关系图
下图将自然语言需求与开发设置中使用的特定代码实体连接起来。
包开发工作流
JavaScript 包 (@ffmpeg/ffmpeg 和 @ffmpeg/util)
对于开发 JavaScript 包装器，请在各自的目录中使用以下命令：
- 开发:
npm run dev(启动监听器) - 构建:
npm run build(将 TypeScript 转译为 JS) - 检查:
npm run lint
核心包 (@ffmpeg/core)
核心包的开发侧重于 C/C++ 依赖项和 Emscripten 胶水代码。
- 构建: 使用根目录中的
Makefile目标。 - 输出: 生成的二进制文件放置在
packages/core/dist或packages/core-mt/dist中