保姆级教程:Windows 从零编译 FFmpeg 全流程,绕开 MSYS2,附 5 个真实踩坑与 20MB 产物实测
本文所有命令与报错均在本机实测复现,结论有日志与产物为证。
配套仓库:本文全部代码与脚本均在 github.com/clpz299/av-lab,对应模块
modules/L1-01-env;克隆后按文中步骤即可复现。
准备清单
动手前请先备齐以下素材与环境。
素材获取方式
- FFmpeg 源码:
https://ffmpeg.org/releases/ffmpeg-7.1.tar.xz(本文实测版本); - x264 源码:
https://code.videolan.org/videolan/x264.git; - 测试素材无需下载:
testsrc/sine由-f lavfi实时合成,任何 ffmpeg 都能自产。
环境
- 工具链:
.avtoolchain/w64devkit(gcc 16.2.0 / make / busybox sh / xz / tar),av-lab/tools/bootstrap.ps1一键准备; - Windows 完整构建:MSYS2(
pacman -S base-devel mingw-w64-x86_64-toolchain mingw-w64-x86_64-nasm git)或 WSL。
一、开篇结论
本文解决什么问题:很多教程把"编译 FFmpeg"等同于"先装 MSYS2",但没人说清为什么、以及不装会怎样。本文把这层窗户纸捅破——FFmpeg 的 configure 是一段 POSIX shell 脚本,它在启动时会做一次 操作系统探测,而探测结果决定了它认不认你这台机器。
读完你能得到什么:
- 搞清 Windows 上编译 FFmpeg 的真正卡点(不是缺编译器,而是
configure不认识的 OS 标识); - 掌握两条可落地路径:官方推荐的 MSYS2/WSL,以及本文实测的 w64devkit + MinGW-w64 极简路径;
- 亲手造出一个能用的
ffmpeg.exe(实测 20.3 MB,ffmpeg version 7.1),并用它跑通 L1-01 的验收实验:生成带音轨的测试视频 → 转 GIF → ffprobe 校验; - 拿到一份真实踩坑清单:
Unknown OS 'windows_nt'、误删源码ffbuild/、nasm缺失、zlib缺失导致 GIF 两遍法失败。
二、背景与目标
2.1 为什么音视频工程师绕不开"自己编译 FFmpeg"
直接用官网/BtbN 的预编译包不是更省事吗?日常剪转视频确实够用。但一旦进入工程开发,预编译包会立刻暴露短板:
| 场景 | 预编译包 | 自己编译 |
|---|---|---|
需要 libx264/libx265、fdk-aac 等外部编码器 |
取决于打包者给你编了什么 | 想要什么编什么 |
| 需要和自有 SDK 静态链接(单一 exe / 无 dll 依赖) | 提供的是动态库,部署麻烦 | --enable-static 一把梭 |
| 需要裁剪体积(嵌入式 / 移动端) | 动辄上百 MB,砍不掉 | --disable-* 精准瘦身 |
| 需要打开某些实验性组件 / 打本地 patch | 不可控 | 完全可控 |
| 排查"某个功能为什么没生效" | 只能猜 | 能看到 configure 的每一项判定 |
| 授权合规(LGPL / GPL) | 被动接受 | 主动选择 |
一句话:预编译包是"结果",自己编译是"能力"。第一篇文章就从这条能力线起步。
2.2 本文的验证目标
| 目标 | 判定标准 |
|---|---|
| G1 编译出可用 ffmpeg | 能执行 ffmpeg -version 并打印 ffmpeg version 7.1 |
| G2 完成一次真实转换 | 用自编译的 ffmpeg 生成 testsrc + sine 测试视频,并转成 GIF |
| G3 产物可被校验 | ffprobe 能读出两个产物的封装/编码/分辨率/时长 |
| G4 脚本可交付 | 提供 build_ffmpeg.sh / build_ffmpeg.bat(MSYS2/WSL 路径)并做契约自检 |
三、环境与前置
| 项 | 值(本机实测) |
|---|---|
| OS | Windows 10 (x64, 19044) |
| 编译工具链 | w64devkit 2.11.0 内置 gcc 16.2.0 / GNU make / busybox sh / xz / tar |
| FFmpeg 源码 | ffmpeg-7.1.tar.xz(官方 release,11,011,364 字节) |
| 代码仓库 | av-lab/(模块:modules/L1-01-env),计划 tag:L1-01 |
| 网络 | 需要(下载 FFmpeg / x264 源码);下载速度约 16 KB/s,本次源码下载耗时约 11 分钟 |
| 本机缺失项 | MSYS2(无)、nasm(无)、yasm(无)、zlib(无) |
| WSL | wsl.exe 存在,但未安装任何 Linux 发行版 |
提示:本机已备好一套便携工具链
.avtoolchain/(w64devkit + cmake + ffmpeg),av-lab/tools/bootstrap.ps1可一键准备,读者无需手工配置编译器。
四、原理图解
4.1 依赖关系图:FFmpeg 不是孤岛

两个必须记住的结论:
configure本身是 shell 脚本 → 它是整条链路的"总闸",没有 POSIX shell,后面全都无从谈起;libx264等是可选依赖 → 但缺了它,--enable-libx264就会报libx264 not found;反过来,nasm/zlib缺了只会降级,不会直接失败(这也是坑的一部分,见第六节)。
4.2 configure 启动时到底干了什么

这张图就是本文的核心。第三步 uname 的返回值,直接决定你后面能不能走通。
4.3 Windows 常见环境对照
| 环境 | uname -s 返回 |
能否通过 OS 探测 | 说明 |
|---|---|---|---|
| cmd / PowerShell | 无 uname |
❌ 根本跑不起来 | 没有 POSIX shell |
| w64devkit 的 busybox sh | Windows_NT → 小写 windows_nt |
❌ Unknown OS | 本机实测的翻车现场(见坑 1) |
| Git-Bash | MINGW64_NT-10.0-19044 |
✅ | 本机实测返回值;但 Git-Bash 默认不含 gcc/make,仍需外部 MinGW 工具链 |
| MSYS2(MINGW64 终端) | MINGW64_NT-10.0-xxxx |
✅ | 官方推荐,脚本默认路径 |
| WSL / Linux | Linux |
✅ | 最省心 |
注意表格第三列与第四列的区别:OS 探测过了只代表
configure肯往下走,能不能编完还取决于有没有 C 编译器与 make。
五、动手实验
5.1 方案 A:官方推荐路径(MSYS2 / WSL + x264)
这是配套脚本 build_ffmpeg.sh 固化的路线,也是产出功能完整 ffmpeg(含 libx264)的推荐做法。
# ① Windows 上安装 MSYS2 后,在 "MSYS2 MINGW64" 终端装工具链
pacman -S --needed base-devel mingw-w64-x86_64-toolchain mingw-w64-x86_64-nasm git
# ② 运行构建脚本:先编 x264 静态库,再 configure + make + install 到 ~/ffmpeg-build
bash srcbuild/build_ffmpeg.sh --prefix "$HOME/ffmpeg-build" --jobs 8
脚本里几条关键行(读懂这几行,就懂了 FFmpeg 的裁剪逻辑):
# 前置检查:缺 gcc/make/pkg-config/git 直接退出
for t in gcc make pkg-config git; do
command -v "$t" >/dev/null 2>&1 || {
echo "缺少必需工具: $t" >&2; exit 3; }
done
# nasm 缺失 -> 自动降级关闭 x86 汇编优化(对应踩坑 1)
if [ "$WITH_NASM" = "1" ] && command -v nasm >/dev/null 2>&1; then
log "nasm: $(nasm -v | head -n1)"
else
NASM_FLAG="--disable-x86asm"
fi
# configure:静态链接 + 裁剪 + 外链 libx264
PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig" ./configure \
--prefix="$PREFIX" --enable-gpl --enable-libx264 \
--enable-static --disable-shared --enable-pic \
--pkg-config-flags="--static" \
--extra-cflags="-I$PREFIX/include" --extra-ldflags="-L$PREFIX/lib" \
--disable-doc --disable-debug --disable-ffplay --disable-autodetect \
$NASM_FLAG
关键选项速查:
| 选项 | 作用 | 不加会怎样 |
|---|---|---|
--enable-gpl |
允许 GPL 组件(x264 是 GPL) | 配 x264 会报协议冲突 |
--enable-libx264 |
启用 H.264 外部编码器 | 无 H.264 软编(只有 mpeg4) |
--enable-static --disable-shared |
只出静态库 | 产物依赖一堆 dll |
--pkg-config-flags=--static |
让 pkg-config 返回静态链接参数 | 链接时找不到 x264 的传递依赖 |
--disable-autodetect |
不自动探测系统库 | 结果随机器环境漂移,不可复现 |
--disable-ffplay |
不编播放器(省 SDL 依赖) | 缺 SDL 时编译报错 |
--disable-doc |
不生成文档 | 拖慢构建 |
Windows 用户也可直接运行 build_ffmpeg.bat,它会自动定位
C:\msys64\usr\bin\bash.exe并转交 sh 脚本;找不到 MSYS2 时会给出pacman安装指引。
5.2 方案 B:本机实测路径(w64devkit + MinGW-w64)
这是我这次真正跑通的路径,也是本文最有价值的部分。本机没有 MSYS2,但有一套 w64devkit(MinGW-w64 + busybox sh)。它能不能编?我们直接试。
第 1 步:下载并解压源码
# 下载官方 release(约 10.5 MB)
curl.exe -fL https://ffmpeg.org/releases/ffmpeg-7.1.tar.xz -o ffmpeg-7.1.tar.xz
# 用 w64devkit 自带的 xz/tar 解压
xz.exe -d ffmpeg-7.1.tar.xz
tar.exe -xf ffmpeg-7.1.tar
预期输出:当前目录出现 ffmpeg-7.1/ 源码树。
第 2 步:先按"朴素"方式跑 configure —— 会翻车(这是故意保留的现场)
# 把 w64devkit/bin 加入 PATH,然后用它的 sh 跑 configure
./configure --disable-everything --disable-x86asm --disable-doc
预期输出(实测报错,注意最后一行):
OS='Windows_NT'
host_os='windows_nt'
target_os_default='windows_nt'
Unknown OS 'windows_nt'.
configure 直接以退出码 1 中断。它把 busybox uname -s 返回的 Windows_NT 小写成 windows_nt,而这个标识不在 FFmpeg 的已知 OS 列表里(它是按 mingw64_nt-* / msys_nt-* 这类前缀去匹配的)。
第 3 步:显式指定目标 OS,绕开探测
# 关键就是 --target-os=mingw32:不让它自己去猜
./configure --target-os=mingw32 \
--disable-x86asm --disable-doc --disable-ffplay --disable-debug --disable-network
预期输出:configure 跑完并打印一大堆 Enabled ... 列表,退出码 0。本机实测开启了 lavfi/dshow/gdigrab 等输入设备、默认编解码器与滤镜。
第 4 步:编译
make -j8
预期输出(结尾几行):LD ffmpeg_g.exe → STRIP ffmpeg.exe → LD ffprobe_g.exe → STRIP ffprobe.exe。本机实测产出:
ffmpeg.exe 20.3 MB
ffmpeg_g.exe 22.7 MB # 带调试符号,体积更大
ffprobe.exe 20.2 MB
ffprobe_g.exe 22.5 MB
说明:方案 B 刻意不链接任何外部库(无 x264 / 无 zlib / 无网络协议),目的是用最小变量证明"能编出可跑的程序"。要功能完整的 ffmpeg,请走方案 A。
5.3 验证 + L1-01 验收实验
验证 1:版本
.\ffmpeg.exe -version
实测输出(前三行):
ffmpeg version 7.1 Copyright (c) 2000-2024 the FFmpeg developers
built with gcc 16.2.0 (GCC)
configuration: --target-os=mingw32 --disable-x86asm --disable-doc --disable-ffplay --disable-debug --disable-network
configuration: 这一行就是你这次编译的"体检报告",它如实记录了每一个开关——这也是自己编译最大的好处:所见即所得。
验证 2:生成测试视频并用自编译的 ffmpeg 转 GIF
# ① testsrc(测试图案)+ sine(440Hz 正弦音)合成 2 秒带音轨 MP4
./ffmpeg.exe -y \
-f lavfi -i testsrc=size=320x240:rate=10 \
-f lavfi -i sine=frequency=440:sample_rate=44100 \
-t 2 -c:v mpeg4 -q:v 5 -c:a aac -shortest src_built.mp4
# ② 转 GIF:单命令 split -> palettegen -> paletteuse(不落地中间 PNG,原因见踩坑 4)
./ffmpeg.exe -y -i src_built.mp4 \
-lavfi "fps=10,scale=320:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
out_built.gif
预期输出:两次命令分别打印 frame= 20 ... Lsize= ... 且退出码为 0。
验证 3:用 ffprobe 校验
./ffprobe.exe -v error -show_entries format=format_name,duration \
-show_entries stream=codec_name,width,height -of default=nw=1 src_built.mp4
./ffprobe.exe -v error -show_entries format=format_name,duration \
-show_entries stream=codec_name,width,height -of default=nw=1 out_built.gif
实测输出:
-- src_built.mp4 --
codec_name=mpeg4
width=320
height=240
codec_name=aac
format_name=mov,mp4,m4a,3gp,3g2,mj2
duration=2.000000
-- out_built.gif --
codec_name=gif
width=320
height=240
format_name=gif
duration=2.000000
G2 / G3 达标:视频流 mpeg4、音轨 aac、时长 2.000000s、分辨率 320×240,GIF 亦被正确识别。
六、踩坑复盘
这是本文的核心。以下 5 个坑全部来自本次真实操作日志。
坑 1:Unknown OS 'windows_nt' —— "Windows 上编译必须装 MSYS2"的真相
现象:在原生 Windows 下用 w64devkit 的 sh 执行 ./configure,秒退:
target_os_default='windows_nt'
Unknown OS 'windows_nt'.
排查过程:
- 先怀疑 shell 不对 → 换
./configure --help,能正常打印帮助。说明 shell 没问题,configure至少能跑起来; - 看
ffbuild/config.log,锁定host_os='windows_nt'; - 手动执行
uname -s得到Windows_NT,uname -m得到x86_64,uname -o得到MS/Windows。
根因:FFmpeg 用 uname -s 的结果(转小写后)匹配已知 OS 表。busybox 的 uname 返回通用值 Windows_NT,而 FFmpeg 期望的是 MSYS2/MinGW 环境特有的 MINGW64_NT-10.0 / MSYS_NT-10.0。标识对不上,直接判死刑。
解决:给 configure 一个明确的答案——--target-os=mingw32。它就不再依赖 uname 去猜,而是按你指定的目标平台生成构建配置。实测立即可编译。
结论修正:网上"Windows 必须用 MSYS2"的说法过于绝对。准确的表述是:Windows 上需要一个 POSIX shell,且 configure 的 OS 探测必须能给出一致结果。有 MSYS2 是最省事的路;没有 MSYS2 时,只要显式声明 --target-os,MinGW-w64 工具链同样能干活。
坑 2:手滑 rm -rf ffbuild,把源码自带的构建脚本删了
现象:第二次配置时按习惯先 rm -rf ffbuild 清缓存,结果 make 报:
Makefile:43: ffbuild/common.mak: No such file or directory
make: *** No rule to make target 'ffbuild/common.mak'. Stop.
根因:很多人以为 ffbuild/ 全是 configure 生成的缓存,其实它同时包含源码自带的 common.mak / library.mak 等构建脚本。删它 = 把 make 的地基拆了。
解决:重新 tar xf ffmpeg-7.1.tar 解压干净源码。要清配置缓存,删 ffbuild/config.mak、ffbuild/config.log 即可,别删整个目录。
坑 3:缺 nasm → 汇编优化没启用,连色彩转换都变慢
现象:configure 时没提示致命错误,但转 GIF 的日志里刷屏:
[swscaler @ ...] No accelerated colorspace conversion found from yuv420p to bgra.
根因:本机没有 nasm,脚本自动降级加了 --disable-x86asm。于是 SIMD 汇编优化全部关闭,libswscale 只能走纯 C 路径,色彩空间转换变慢并打出这条告警。它不报错、也不影响正确性,只影响性能——这正是它危险的地方:容易在开发机小样本上"跑得通",一上生产就露馅。
解决:装 nasm(MSYS2:pacman -S mingw-w64-x86_64-nasm)后重新配置;或明确接受性能损失(嵌入式场景常见)。
坑 4:缺 zlib → PNG 编码器没了,GIF"两遍法"直接失败
现象:经典 GIF 两遍法第一步就挂:
Automatic encoder selection failed Default encoder for format image2 (codec png) is probably disabled.
Error opening output file palette.png
Error opening output files: Encoder not found
根因:GIF 两遍法会先把调色板写成一张 PNG(palettegen → palette.png),而 PNG 编码依赖 zlib。本机工具链没有 zlib → png 编码器在 configure 阶段就被禁用了 → 输出端找不到编码器。
解决:改用单命令管道,让调色板只存在于内存中,不落地 PNG:
-lavfi "fps=10,scale=320:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse"
s0 送给 palettegen 生成调色板 [p],s1 与 [p] 一起交给 paletteuse 合成 GIF——全程无中间文件。实测一次通过。
坑 5(无害噪音):满屏 @printf: not found
现象:make 日志里每个编译行前都插一句:
sh: line 0: @printf: not found
根因:FFmpeg 的 Makefile 用 @printf "CC ..." 来做彩色输出,@ 是"不回显本行"的约定,需要 make 帮它剥掉。本机这套 make 没剥,@printf 被原样丢给 sh,于是 sh 找不到叫 @printf 的命令。
结论:纯噪音,不影响编译——后面的 gcc -c -o xxx.o 照常执行。遇到它不用慌。
七、成果展示
7.1 编译产物
| 产物 | 大小 | 说明 |
|---|---|---|
ffmpeg.exe |
20.3 MB (21,270,528 B) | strip 后的主程序 |
ffprobe.exe |
20.2 MB | 媒体信息探测 |
ffmpeg_g.exe / ffprobe_g.exe |
22.7 / 22.5 MB | 带调试符号版本 |
ffmpeg -version 回显的 configuration 行:
configuration: --target-os=mingw32 --disable-x86asm --disable-doc --disable-ffplay --disable-debug --disable-network
7.2 L1-01 验收实验产物
| 文件 | 大小 | ffprobe 结论 |
|---|---|---|
src_built.mp4 |
54,009 B | format=mov,mp4,m4a,3gp,3g2,mj2;视频 mpeg4 320×240;音频 aac;duration=2.000000 |
out_built.gif |
103,071 B | format=gif;gif 320×240;duration=2.000000 |
关键点:这两个文件是由"我们从源码编译出来的 ffmpeg.exe"亲手生成的,不是用现成的预编译包——G1/G2/G3 全部闭环。
7.3 配套脚本的自动化验收(av-lab 工程内)
真正的 MSYS2/WSL 编译无法在本机 CI 里自动跑(要装 MSYS2 + 联网),因此工程把它们拆成两层:
| 层 | 内容 | 是否自动化 |
|---|---|---|
| 契约与语法层 | 校验 build_ffmpeg.sh/.bat 是否含关键选项、bash -n 语法检查、探测本机编译前提(gcc/nasm/MSYS2…) |
✅ 进 ctest(L1-01.srcbuild_check) |
| 真实编译层 | 真正的 configure + make |
❌ 需 MSYS2/WSL,走本文手工步骤 |
srcbuild_check 实测输出(18 项契约全通过 + 语法检查通过):
checks: 18 passed: 18 failed: 0 bashSyntaxChecked: true
environment: gcc ✓ / make ✓ / git ✓ / curl ✓ / bash(Git) ✓ / nasm ✗ / yasm ✗ / msys2 ✗ / wsl ✓
全量回归(ctest,共 19 个用例)实测:
100% tests passed out of 19
Total Test time (real) = 45.89 sec
其中与本文直接相关的 4 条:
L1-01.hello_env .......... Passed
L1-01.env_check .......... Passed
L1-01.convert ............ Passed # 生成 test.mp4 / test.gif 并 ffprobe 校验
L1-01.srcbuild_check ..... Passed # 脚本契约 + bash -n + 环境探测