构建系统

ffmpeg.wasm 的构建系统是一个多层流水线，旨在编译复杂的 C/C++ FFmpeg 代码库及其众多第三方编解码器库以生成 WebAssembly。它利用 Docker 确保环境一致性，使用 Emscripten 进行转译，并通过 Makefile 驱动的工作流来管理构建变体（单线程 vs. 多线程）。

构建系统架构

该构建系统在多媒体需求的“自然语言空间”（如“编码 H.264"）与特定库构建器和 Emscripten 标志的“代码实体空间”之间架起桥梁。

核心编译流水线

构建系统架构图

基于 Docker 的编译

该系统采用多阶段 Docker 构建以确保可重现的环境。流程从 emsdk 基础镜像开始，在编译 FFmpeg 本身之前先构建依赖库树。

构建阶段与依赖项

构建过程为每个库组织了特定的"builder"阶段，确保对某个编解码器的更新仅需部分重建 Docker 缓存。

emsdk-base：设置全局环境变量，如 INSTALL_DIR=/opt 和 FFMPEG_VERSION=n5.1.4
Codec Builders：针对 x264-builder、opus-builder 和 zimg-builder 等库的独立阶段
ffmpeg-builder：配置带有特定标志的 FFmpeg（例如 --enable-libx264、--enable-libopus），以链接前一阶段构建的库
ffmpeg-wasm-builder：最终阶段，通过 build/ffmpeg-wasm.sh 调用 emcc 以生成 .wasm 和 .js 胶水代码

有关多阶段逻辑和 Emscripten 标志的详细信息，请参阅 Docker 构建流程。

Makefile 与构建变体

Makefile 作为开发者的主要接口，抽象了复杂的 docker buildx 命令。它管理两个主要维度：环境（dev vs. prd）和线程（st vs. mt）。

目标	命令	关键标志	用途
Production ST	`make prd`	`-O3 -msimd128`	优化的单线程构建
Production MT	`make prd-mt`	`-sUSE_PTHREADS -pthread`	优化的多线程构建
Development ST	`make dev`	`--profiling`	带分析符号的构建

build/ffmpeg-wasm.sh 脚本会根据这些变体动态调整 Emscripten 设置。例如，MT 构建使用 -sPTHREAD_POOL_SIZE=32，而 ST 构建则启用 -sALLOW_MEMORY_GROWTH。

依赖管理

该项目管理两种类型的依赖项：编译为 Wasm 的 C/C++ 库以及 monorepo 内的 JavaScript 包。

C/C++ 库

库被锁定到特定版本（例如 X265_BRANCH=3.4），并使用 build/ 目录中的专用 shell 脚本进行构建。这些脚本通常使用 emconfigure 和 emmake 来适配标准 C 构建系统（Autotools/CMake）以适应 WebAssembly。

Monorepo 工作区

JavaScript 端使用 npm workspaces 来管理 @ffmpeg/ffmpeg、@ffmpeg/util 和 @ffmpeg/core 等包。一个名为 download-assets.js 的工具脚本通常用于获取预构建的二进制文件以进行本地开发，从而避免冗长的 Docker 编译过程。

有关版本锁定和工作区组织的详细信息，请参阅依赖管理。

CI/CD 流水线

构建系统完全通过 GitHub Actions 自动化。流水线处理：

并行核心构建：使用 Docker Buildx 同时构建 ST 和 MT 核心。
自动化测试：在无头浏览器环境中运行测试套件。
资产导出：将编译后的 .wasm 和 .js 文件从 Docker scratch 阶段移动到包目录

有关 CI 工作流程和测试策略的详细信息，请参阅 CI/CD 流水线。