从源码构建 FFmpeg：INSTALL.md 安装流程完全解析（configure、make 与 install 细节）

2026-09-03 15:35:50作者：齐添朝

本文以 FFmpeg 仓库的 INSTALL.md 为核心，完整拆解“获取源码 → 合并 source plugin → configure 配置 → make 编译 → make install 安装”这条官方安装链路，并结合 Makefile、configure、doc/build_system.txt 等仓库内实现，解释每一步背后的机制（如 out-of-tree 构建如何被识别、安装目录如何指定、DESTDIR 的用途），帮助你在任意 Linux/类 Unix 环境下正确地从源码编译并安装当前版本（见 RELEASE，为 8.0.git 开发树）的 FFmpeg。

1. 安装流程总览：三步走

INSTALL.md 给出的官方流程非常精简，共四步（编号 0–3）：

步骤	命令	作用
0	`tools/merge-all-source-plugins`	（可选）将源码级插件（source plugin）合并进当前树
1	`./configure`	生成构建配置；`configure --help` 查看全部选项
2	`make`	编译所有库与可执行程序，要求 GNU Make 3.81 及以上
3	`make install`	安装编译出的二进制与库

这套流程的前提是：已克隆 FFmpeg 源码树，且系统具备 C 编译器、GNU Make 等基础工具链。下文按此顺序逐步展开，并说明每一步在构建系统中到底做了什么。

2. 第 0 步：合并 source plugins（可选）

INSTALL.md 的第一步原文是：

If you like to include source plugins, merge them before configure. for example run tools/merge-all-source-plugins

所谓 source plugin，是指以独立 git 仓库形式维护、通过分支合并方式“贴入” FFmpeg 树的组件。当前仓库中由 tools/source-plugins.txt 登记清单，目前登记的是 libpostproc（GPL，Michael Niedermayer 维护），指向其独立仓库的 libpostproc 分支。

tools/merge-all-source-plugins 脚本的核心逻辑（可直接阅读其源码）：

读取 source-plugins.txt 中每行的“仓库地址 + 分支名”，逐一执行 git pull --no-rebase --log --stat --commit --no-edit 完成合并；
执行前会检查工作区是否干净（git diff --exit-code），有未提交修改时直接报错退出；
任一插件合并失败时执行 git reset --hard 回滚，然后继续处理其余插件，并在末尾汇总输出 Succeeded merging: / Failed merging: 列表；
脚本内保留了按版本号锁定插件分支的机制（sourceplugin-<refspec>-<version>），用于避免插件 ABI 与主干 HEAD 不匹配。

需要注意的是：这一步是可选的，且合并操作会改动你的工作区（拉入外部提交）。如果你的构建环境是干净的只读检出、或不使用 libpostproc，可以跳过此步直接执行 configure。

3. 第 1 步：configure 生成配置

3.1 基本用法

在源码树根目录执行 ./configure 即可生成构建配置。所有可选项通过 configure --help 查看，例如当前仓库中该输出包含：

帮助类选项：--list-decoders、--list-encoders、--list-hwaccels、--list-muxers、--list-filters、--list-bsfs 等，可直接列出全部可用的解码器/编码器/硬件加速/滤镜等组件；
安装路径选项：--prefix（默认 /usr/local）、--bindir（默认 PREFIX/bin）、--libdir、--shlibdir、--incdir、--pkgconfigdir（默认 LIBDIR/pkgconfig）、--mandir、--docdir 等；
许可选项：--enable-gpl、--enable-version3（默认均为 no，即默认构建受 LGPL 约束，见仓库根目录的 COPYING.LGPLv3、COPYING.GPLv2 等文件）；
编译选项：--enable-shared（默认 no，即默认构建静态库）、--extra-cflags、--cross-prefix（交叉编译工具链前缀）等。

configure 的探测日志默认写入 ffbuild/config.log（--logfile=FILE 可改），出现不确定行为时这是第一手排查材料。

3.2 Out-of-tree（树外）构建

INSTALL.md 特别指出：configure 可以从不同于 FFmpeg 源码目录的位置启动，从而把构建产物放在源码树之外（out of tree）。做法是用绝对路径调用 configure，例如：

/ffmpegdir/ffmpeg/configure

这一点在 configure 中有对应的实现证据：脚本在启动时依次判断

当前目录下存在 configure → source_path=.（树内构建）；
当前目录下存在 src/configure → source_path=./src（典型的树外布局：在构建目录里建了 src 子目录指向源码）；
否则以 configure 自身所在目录作为源码路径，并做两项保护性检查：
- 源码路径包含空白字符时直接报错退出（“Out of tree builds are impossible with whitespace in source path.”）；
- 源码目录中已存在 config.h 时报错（防止在别的构建目录残留了配置产物）。

确认源码路径后，树外构建会在构建目录中生成对源码树的引用（configure 后段有 test -e Makefile || echo "include $source_path/Makefile" > Makefile 的逻辑，见 configure），随后所有 C 变量（SRC_PATH 等）写入 ffbuild/config.mak，供 Makefile 通过 include ffbuild/config.mak 消费；Makefile 顶部的 vpath %.c $(SRC_PATH) 等一系列 vpath 规则正是让 make 能在树外目录里找到源码文件。

因此树外构建的实用形态是：在任意工作目录里执行 绝对路径/ffmpeg/configure，之后在该目录直接 make，源码树保持干净，便于对同一份源码维护“默认配置”“调试配置”“静态/共享两套配置”等多个并行构建目录。

3.3 重配置（reconfigure）

修改配置无需删除构建目录：构建目录中执行 make config，会按 configure 时记录的参数（FFMPEG_CONFIGURATION）重新运行一次 configure。doc/build_system.txt 对此的描述是 “Reconfigure the project with the current configuration.”，对应实现见 Makefile 的 config 目标（$(SRC_PATH)/configure $(value FFMPEG_CONFIGURATION)）。

4. 第 2 步：make 编译

4.1 版本要求与并行编译

INSTALL.md 明确要求 GNU Make 3.81 或更高版本。并行编译使用标准语法：

make -j$(nproc)

doc/build_system.txt 补充了几条对源码开发者很有用的 make 约定：

make V=1：关闭默认的精简输出模式，屏幕上显示 make 实际发出的完整命令及其输出，排查编译问题时的首选开关；
make GEN=1：重新生成缺失或不一致的引用文件；
make -t <target>：只“touch”本应构建的产物，减少改头文件后的重编规模；
make -k：遇错继续，适合跑回归测试时尽量构建完剩余目标。

4.2 默认目标与常用 make 目标

Makefile 中 all 是默认目标（注释明确写了 “first so all becomes default target”），构建全部库与可执行程序。常用目标一览（来源 doc/build_system.txt 与 Makefile）：

目标	作用
`all`	默认目标，构建所有库（libavutil/libavcodec/libavformat/libavfilter/libavdevice/libswresample/libswscale）与 ffmpeg/ffprobe/ffplay 等程序
`alltools`	构建 `tools/` 目录下的全部工具（ffprobe 之外的诊断工具如 `ffeval`、`fourcc2pixfmt`、`trasher` 等）
`examples`	构建 `doc/examples` 下的全部示例程序
`config`	按当前已记录配置重新运行 configure
`install`	安装头文件、库与程序（见下节）
`fate`	运行 FATE 回归测试套件，要求 FFmpeg 已安装（`make install` 之后）
`fate-list` / `fate-list-failing`	列出全部 / 上次失败的回归测试目标
`fate-clear-reports`	清理旧的测试报告
`checkheaders`	检查头文件依赖
`tools/target_dec_<decoder>_fuzzer`	构建指定解码器的 fuzz 工具
`tools/target_bsf_<filter>_fuzzer`	构建指定 bitstream filter 的 fuzz 工具

构建完成后，可直接用 ffprobe -version、ffmpeg -version 检查产物版本（当前开发树在 Changelog 的 version <next> 段记录了诸如 AAC 编码器大幅改进、APV Vulkan 编码器、vf_fruc_vulkan 等条目）。

5. 第 3 步：make install

5.1 安装内容与路径

make install 安装“你构建出的全部二进制与库”。从 Makefile 可见顶层规则为 install: install-libs install-headers（另含数据文件安装），其下按库分拆为 install-libs-yes、各库的 install-lib<name>-shared/static/headers/pkgconfig 子目标（见 ffbuild/library.mak）。默认安装前缀为 /usr/local，可用 configure 的 --prefix 及各 --*dir 选项调整，安装产物因此包含：

程序：ffmpeg、ffplay、ffprobe 等（bindir，默认 PREFIX/bin）；
库：静态库与/或共享库（取决于 --enable-shared，默认静态）；
头文件（PREFIX/include）与 pkg-config 文件（LIBDIR/pkgconfig），供下游项目通过 pkg-config 发现 FFmpeg；
man 页（--mandir）与文档（--docdir），文档构建依赖 texinfo 工具链，configure 会自动探测 makeinfo 并决定是否启用 HTML 文档（探测逻辑见 configure）。

make uninstall 为对应清理目标。

5.2 DESTDIR：打包与交叉环境安装的“影子根”

doc/build_system.txt 专门说明了一个 INSTALL.md 未提及但打包场景常用的变量：

DESTDIR — Destination directory for the install targets, useful to prepare packages or install FFmpeg in cross-environments.

即 make DESTDIR=/path/to/stage install 会先把所有产物安装进影子目录 /path/to/stage/usr/local/...，再由打包工具（rpm/deb 等）将其归档。这是发行版打包 FFmpeg 时的标准做法，与 --prefix 正交：DESTDIR 只是安装时的前缀叠加，不改变库内部记录的安装路径。

6. 注意事项（NOTICE）：非系统依赖默认关闭

INSTALL.md 的 NOTICE 部分强调：

Non system dependencies (e.g. libx264, libvpx) are disabled by default.

含义是：除 libc 等系统级依赖外，所有第三方编码库/外部库默认都不启用，必须在 configure 时显式开启，例如 --enable-libx264、--enable-libvpx（配合对应 --pkg-config-flags/库路径）。一个“默认 configure + make”得到的构建只依赖系统工具链，可编译性最好；而任何涉及外部编码器、硬件平台库的构建都需要显式声明。若 configure 输出了告警但希望构建严格通过，可加 --fatal-warnings 将告警提升为错误（见 configure --help）。

7. 面向打包维护者（Package Maintainers）：两次构建策略

INSTALL.md 最后给出的一条针对发行版打包者的建议值得单独强调：

It is recommended to build FFmpeg twice, first with minimal external dependencies so that 3rd party packages, which depend on FFmpeg's libavutil/libavfilter/libavcodec/libavformat can then be built. And last build FFmpeg with full dependencies (which may in turn depend on some of these 3rd party packages). This avoids circular dependencies during build.

即采用两阶段构建：

第一遍：最小外部依赖构建 FFmpeg（只启用系统级依赖），此时 libavutil/libavfilter/libavcodec/libavformat 已可作为系统库存在；
在此基线上构建依赖这些库的第三方软件包；
第二遍：启用全部外部依赖重新构建 FFmpeg——此时它反过来也可能依赖第一步安装的那些第三方库。

这样构建顺序天然形成无环依赖：FFmpeg(最小) → 第三方包 → FFmpeg(完整)。配合 DESTDIR 分阶段暂存（见 5.2 节），即可在 rpmbuild/debhelper 等打包流程中落地。

8. 快速操作清单

把以上步骤收敛成可直接执行的命令序列：

# （可选）合并 source plugins，需工作区干净
tools/merge-all-source-plugins tools/source-plugins.txt

# 1. 配置（默认静态库、LGPL、prefix=/usr/local；按需添加 --enable-gpl/--enable-libx264 等）
./configure --prefix=/opt/ffmpeg

# 树外构建示例（在任意工作目录执行）
/path/to/ffmpeg/configure --prefix=/opt/ffmpeg

# 2. 编译（GNU Make >= 3.81；V=1 打开完整命令回显）
make -j$(nproc)          # 排错时可加 V=1

# 3. 安装（打包场景可加 DESTDIR 影子目录）
make install
# make DESTDIR=/staging install

# 安装后运行回归测试套件
make fate

9. 小结

FFmpeg 的官方安装路径就是 INSTALL.md 中的“configure → make → make install”三步，辅以可选的 source plugin 合并（tools/merge-all-source-plugins）。理解 configure 的源码路径探测逻辑（树外构建与空白路径/残留 config.h 的防护）、Makefile 的目标体系（all/config/install/fate 等）、以及 doc/build_system.txt 中 V/DESTDIR/GEN 三个 make 变量的作用，可以让你在同一份源码上灵活维护多种构建配置，并为发行版打包（两阶段构建 + DESTDIR 暂存）打下正确基础。默认构建只依赖系统工具链、第三方库默认关闭这两条约束，是理解任何“为什么我的构建里少了某个编码器”问题的起点。