CI/CD 流水线

本文档描述了 ffmpeg.wasm 项目的持续集成和持续部署 (CI/CD) 流水线。该 CI/CD 流水线自动化构建、测试和部署流程，以确保代码质量和功能。本页面专注于构建核心 WebAssembly 模块并针对它们运行测试的自动化工作流的实现细节。

概述

ffmpeg.wasm 的 CI/CD 流水线使用 GitHub Actions 实现。它在向 main 分支推送以及针对 main 分支的拉取请求时自动触发。该流水线旨在构建 FFmpeg WebAssembly 核心模块的单线程和多线程版本，并使用无头浏览器环境运行全面的测试。

流水线结构

CI/CD 流水线由三个按顺序运行的主要任务组成，它们之间存在依赖关系：

构建任务与缓存策略

构建任务利用 Docker Buildx 和 GitHub Actions 缓存来优化基于 Emscripten 的 WebAssembly 模块的编译时间。

Docker Buildx 缓存

build-core 和 build-core-mt 均利用 docker/setup-buildx-action 以启用高级缓存功能。流水线使用本地缓存后端：

• 缓存键: 基于 Dockerfile、Makefile 以及 build/ 目录的内容生成
• 构建参数: EXTRA_ARGS 变量将 --cache-from 和 --cache-to 标志传递给 make 命令
• 模式: 使用 mode=max 以确保所有中间层都被缓存，这对于 x264 或 x265 等 FFmpeg 依赖项的长时间编译至关重要。

工件管理

编译完成后，生成的二进制文件（JavaScript 胶水代码和 WASM 文件）将作为 GitHub 工件上传：

• ffmpeg-core: 来自 packages/core/dist/* 的文件
• ffmpeg-core-mt: 来自 packages/core-mt/dist/* 的文件

测试基础设施

tests 任务在真实浏览器环境中执行测试套件，以确保 WebAssembly 兼容性和正确的线程行为。

测试服务器与安全标头

FFmpeg.wasm（尤其是多线程版本）需要特定的安全标头以启用 SharedArrayBuffer。CI 流水线使用 npm run serve 启动本地服务器并注入这些标头：

// headers used by the test server
{
 "Cross-Origin-Opener-Policy": "same-origin",
 "Cross-Origin-Embedder-Policy": "require-corp"
}

这些标头与跨域隔离的生产环境要求相匹配

浏览器环境验证

在运行完整测试套件之前，流水线会动态生成一个 verify-browser.html 文件。此脚本检查：

1. typeof SharedArrayBuffer !== 'undefined'
2. window.crossOriginIsolated === true

如果未满足这些条件，则环境被视为不适合多线程测试并抛出错误

测试执行流程

测试使用 mocha-headless-chrome 执行，并带有特定的 Chrome 标志以启用 WebAssembly 所需的实验性功能。

核心测试套件实现

tests/ffmpeg-core.test.js 文件包含用于验证低级 Emscripten 导出的逻辑。它测试 createFFmpegCore 工厂函数和返回的 core 对象：

• 执行: 验证 core.exec("-h") 返回 0（成功）
• 转码: 执行从 video.mp4 到 video.avi 的基本转码，并验证输出文件存在于虚拟文件系统 (core.FS.readFile) 中
• 钩子: 通过在执行期间捕获输出来验证 setLogger 和 setProgress 回调
• 超时: 确保 setTimeout 能正确中断长时间运行的任务

流水线命令摘要

下表将 CI 步骤映射到其底层实现：