项目结构

本文档详细说明了 ffmpeg.wasm 项目的组织结构，解释了 monorepo 架构、包关系以及构建系统的组织方式。

Monorepo 概述

ffmpeg.wasm 项目采用 npm workspaces 组织为 monorepo，这促进了多个相关包之间的协同开发。这种架构实现了共享配置、简化的依赖管理以及整个项目更易于测试。

项目结构

根目录 package.json 中的 monorepo 配置定义了两个主要的 workspace 模式：packages/* 用于库代码，apps/* 用于演示和文档。

包组织

packages/ 目录包含构成 ffmpeg.wasm 生态系统的核心 npm 包。每个包都在 @ffmpeg 命名空间下单独发布。

核心包关系

下图将系统名称与其具体的包定义及内部依赖联系起来。

项目结构

包角色与实现细节

包	入口点 (Main)	角色	关键导出 / 文件
`@ffmpeg/ffmpeg`	`./dist/umd/ffmpeg.js`	主 JavaScript API 封装。	`FFmpeg` 类，`./worker`
`@ffmpeg/util`	`./dist/cjs/index.js`	浏览器端文件处理辅助工具。	`fetchFile`, `toBlobURL`
`@ffmpeg/types`	`types`	共享 TypeScript 定义。	`ffmpeg.d.ts`
`@ffmpeg/core`	`./dist/umd/ffmpeg-core.js`	单线程 WebAssembly 构建。	`ffmpeg-core.wasm`
`@ffmpeg/core-mt`	`./dist/umd/ffmpeg-core.js`	多线程 WebAssembly 构建。	`ffmpeg-core.worker.js`

应用组织

apps/ 目录包含各种框架下的示例实现。这些示例既作为集成测试，也作为开发者指南。

框架集成映射

项目结构

angular-app: 展示与 Angular 17+ 的集成，利用 rxjs 和 zone.js
website: 基于 Docusaurus 的文档站点，托管实时 playground。
vanilla-app: 针对没有构建工具的纯 JavaScript 环境的参考实现。

构建与测试执行

Monorepo 使用根目录 package.json 中的集中式脚本在 workspace 之间编排构建和测试。

执行流程

项目结构

关键构建脚本

build: 在所有包 workspace 中运行构建脚本
serve: 在 3000 端口启动本地服务器，并设置 SharedArrayBuffer 所需的请求头 (Cross-Origin-Embedder-Policy: require-corp 和 Cross-Origin-Opener-Policy: same-origin)
test:browser:core:mt: 专门针对多线程核心测试套件，使用启用了 SharedArrayBuffer 功能标志的 Headless Chrome

结论

ffmpeg.wasm monorepo 的结构旨在提供清晰的分离：WASM 核心 (@ffmpeg/core, @ffmpeg/core-mt)、JS 编排层 (@ffmpeg/ffmpeg) 和 工具辅助 (@ffmpeg/util)。通过使用 npm workspaces，项目确保核心包中的更改能立即反映并在特定框架的应用中进行测试。