本文详解解决 Uncaught ReferenceError: createFFmpeg is not defined 错误的完整方案，涵盖脚本引入顺序、核心 API 初始化方式、异步加载流程及常见避坑要点。
本文详解解决 `uncaught referenceerror: createffmpeg is not defined` 错误的完整方案，涵盖脚本引入顺序、核心 api 初始化方式、异步加载流程及常见避坑要点。
在 Web 前端中使用 FFmpeg.wasm（即纯 WebAssembly 版本的 FFmpeg）时，常见的错误如 Uncaught ReferenceError: createFFmpeg is not defined 并非代码逻辑问题，而是库未正确加载或调用时机不当所致。根本原因在于：@ffmpeg/ffmpeg 包本身不直接导出全局函数 createFFmpeg；它需要配合 @ffmpeg/core（核心 WASM 模块）协同工作，且必须通过 ES 模块方式动态导入，而非传统 <script></script> 标签直引。
✅ 正确做法是：使用 ES 模块语法动态导入 @ffmpeg/ffmpeg，并确保 @ffmpeg/core 已被正确加载。以下是可立即运行的完整示例：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>FFmpeg.wasm 浏览器端视频处理</title>
<!-- 注意：此处不直接引入 CDN script，改用模块化导入 -->
</head>
<body>
<h1>FFmpeg.wasm 示例：提取帧并保存为 PNG</h1>
<video id="video" controls width="640"></video>
<button onclick="runFFmpeg()">运行 FFmpeg 处理</button>
<div id="log"></div>
<script type="module">
// ✅ 正确导入方式：使用动态 import() 加载最新稳定版
const { createFFmpeg, fetchFile } = await import('https://cdn.jsdelivr.net/npm/@ffmpeg/ffmpeg@0.12.6/dist/ffmpeg.min.js');
const { core } = await import('https://cdn.jsdelivr.net/npm/@ffmpeg/core@0.12.6/dist/ffmpeg-core.min.js');
// 初始化 FFmpeg 实例（必须在 import 后调用）
const ffmpeg = createFFmpeg({
log: true,
core: core, // 显式传入 core，避免自动加载失败
// 可选：指定 wasm worker 路径（若需自托管）
// corePath: '/path/to/ffmpeg-core.wasm',
});
async function runFFmpeg() {
document.getElementById('log').textContent = '正在加载 FFmpeg...';
try {
await ffmpeg.load(); // ⚠️ 必须 await load() 完成后才能调用 run()
document.getElementById('log').textContent = 'FFmpeg 加载成功，开始处理...';
// 示例：读取本地视频文件（实际项目中建议用 input[type=file]）
const videoData = await fetchFile('input.mp4'); // 需确保该文件已部署在同源服务器下
ffmpeg.FS('writeFile', 'input.mp4', videoData);
// 执行命令：提取第 1 秒的关键帧为 PNG
await ffmpeg.run('-i', 'input.mp4', '-ss', '00:00:01', '-vframes', '1', 'output.png');
// 读取输出文件并展示
const data = ffmpeg.FS('readFile', 'output.png');
const blob = new Blob([data.buffer], { type: 'image/png' });
const url = URL.createObjectURL(blob);
document.getElementById('video').src = url;
document.getElementById('log').textContent = '✅ 处理完成！PNG 已生成并显示。';
} catch (err) {
console.error('FFmpeg 执行失败:', err);
document.getElementById('log').textContent = `❌ 错误: ${err.message}`;
}
}
</script>
</body>
</html>? 关键注意事项：
- ❌ 错误写法：
<script src="https://cdn.jsdelivr.net/npm/@ffmpeg/ffmpeg"></script>→ 此 CDN 地址不支持全局变量注入，createFFmpeg不会挂载到window； - ✅ 正确路径：必须使用
type="module"+await import()动态加载，这是官方唯一推荐方式； - ?
@ffmpeg/core是必需依赖，不可省略，否则load()将抛出core not found类似错误； - ⏱️
ffmpeg.load()是异步重操作（需下载 WASM、初始化内存等），所有ffmpeg.run()或FS操作必须在其await完成之后执行； - ? 浏览器安全限制：
fetchFile('input.mp4')需确保资源位于同源（或启用 CORS），本地file://协议下将失败，建议用live-server或Vite等本地服务调试。
? 总结：该错误本质是开发范式误解——FFmpeg.wasm 是一个现代 ESM 优先的库，拒绝“全局污染式”使用。拥抱模块化、理解加载生命周期、严格遵循官方文档的初始化流程，是规避此类 ReferenceError 的根本之道。
