1. 接手 Qt 音视频工程时,八成会先被库路径绊一跤
接手一个 Qt 音视频工程,最容易被忽略的不是解码逻辑,而是代码开发工具里那几行路径拼装。工程在 32 位机器上编译得好好的,换到 64 位环境,qmake 一跑就报 cannot find -lavformat;或者头文件明明找到了,链接阶段却提示库的机器类型不匹配。这类问题往 FFmpeg 本身找往往白费功夫,根子在 .pro 文件没把版本、位数、系统三件事拆开判断。下面这套写法围绕 qmake 的条件分支展开,把 FFmpeg 2 到 6 的库目录、32/64 位子目录、Windows/Linux/macOS/Android 四类系统用 DEFINES 和 QT_ARCH 分开选,适合正在维护多版本 FFmpeg 工程的 Qt 开发者和需要同时出多平台包的构建负责人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. FFmpeg 目录的版本与位数矩阵:先搞清楚手上有哪些库
在动 .pro 之前,得先承认一件事:FFmpeg 的预编译包不是每个版本都长得一样。很多人写路径时凭印象填 winlib,结果本地目录里只有 winlib64,qmake 不会替你猜,它只会把不存在的路径原样塞进编译命令,然后在链接阶段甩一个找不到库的错误。所以第一步不是写代码,而是把目录矩阵摊开看清楚。
2.1 五个版本的目录里到底有什么
把 FFmpeg 2 到 6 的包并排看,差异非常直观:
| 版本 | include | Windows 32 位 | Windows 64 位 | Linux 32 位 | Linux 64 位 | macOS |
|---|---|---|---|---|---|---|
| ffmpeg2 | 有 | winlib | 无 | linuxlib | 无 | maclib |
| ffmpeg3 | 有 | winlib | winlib64 | linuxlib | linuxlib64 | maclib64 |
| ffmpeg4 | 有 | winlib | winlib64 | linuxlib | linuxlib64 | maclib64 |
| ffmpeg5 | 有 | 无 | winlib64 | 无 | linuxlib64 | maclib64 |
| ffmpeg6 | 有 | 无 | winlib64 | 无 | linuxlib64 | maclib64 |
这张表里有三个信号值得注意。第一,include 目录每个版本都有,头文件本身不区分位数,区分位数的是库目录,所以头文件路径只要跟对版本,不会因为 32/64 位出错。第二,ffmpeg2 只给了 32 位库,winlib 和 linuxlib 都没有对应的 64 后缀目录,mac 侧也只有 maclib 而不是 maclib64。第三,ffmpeg5 和 ffmpeg6 直接砍掉了 32 位目录,只保留 winlib64、linuxlib64、maclib64。
这意味着同一份 .pro 不可能用一套固定路径通吃所有版本。你在 ffmpeg4 上写死 winlib64,换到 ffmpeg2 就必然找不到目录;反过来在 ffmpeg2 上写死 winlib,换到 ffmpeg6 同样翻车。路径必须由版本号和位数两个变量共同决定。
2.2 32 位退场对工程意味着什么
从目录变化能看出一个明确的趋势:ffmpeg5 之后不再提供 32 位预编译库。材料里那句“如果要支持 xp 只能用 ffmpeg2/ffmpeg3”就是这条趋势的直接后果——老系统需要 32 位,而 32 位库停在 ffmpeg4 之前。如果你的工程还要出 32 位安装包,版本选择就被锁死在 ffmpeg2、ffmpeg3、ffmpeg4 这三档,不能因为 ffmpeg6 解码器新就无脑升级。
实操上,这会影响 .pro 里的默认版本策略。把默认值设成 ffmpeg4 是一个折中:它同时有 32 位和 64 位目录,Windows、Linux、macOS 三端都能覆盖,不会一上来就把 32 位构建路径堵死。等确认只出 64 位包,再通过 DEFINES 显式切到 ffmpeg5 或 ffmpeg6。这个默认值不是随便定的,它要保证“什么都不传”时工程仍然能编过。
2.3 在本地把目录核对一遍
写条件判断之前,先花一分钟确认本地库目录和上表是否一致。路径拼错是后面所有链接错误的源头,而这类错误在 qmake 阶段不会报,只会在链接阶段以 cannot find -lxxx 的形式出现,排查时容易误判成库没编译。
bash复制# 在存放 FFmpeg 预编译包的根目录执行
# 逐个版本列出子目录,核对 32/64 位目录是否存在
for v in ffmpeg2 ffmpeg3 ffmpeg4 ffmpeg5 ffmpeg6; do
echo "== $v =="
ls -1 "$v" 2>/dev/null || echo "目录不存在"
done
这段脚本没有复杂逻辑,ls -1 每行输出一个子目录名,2>/dev/null 把不存在的版本安静跳过,避免刷一屏报错。核对时重点看两件事:目标版本下有没有你准备引用的 winlib64 或 linuxlib64,以及 include 是否和库目录同级。材料里的目录结构是 ffmpegN/include 加 ffmpegN/winlib64 这种平级布局,.pro 里的 $$PWD/$$strPath/include 正是按这个层级写的;如果你的包解压后多套了一层版本号目录,$$PWD 的基准就要跟着调,否则头文件路径会整体偏移一级。
另外,代码里出现的 androidlib 和 androidlib64 在目录清单里并没有列出来。这不代表写错了,而是 Android 的库目录命名要按你实际拿到的包核对,不能照着 Windows 的习惯想当然。核对这一步做完,后面的分支才有意义。
3. 代码开发工具里的第一道开关:用 DEFINES 把 FFmpeg 版本钉死
版本判断放在 .pro 最前面,因为它决定了后面所有路径的前缀。这里用 DEFINES 而不是注释切换,理由很实际:注释切换靠人记得改回来,多人协作时经常出现“本地能编、流水线不能编”;DEFINES 可以在 qmake 命令行追加,CI 脚本不用碰源文件就能换版本。
3.1 默认版本的兜底写法
qmake 没有 else if 那种短路语法,要实现“一个版本都没定义时才给默认值”,只能用嵌套的 !contains:
qmake复制# 四个 !contains 嵌套:五个版本一个都没定义时,才落到默认的 ffmpeg4
# 之所以默认 ffmpeg4,是因为它同时提供 32 位和 64 位目录
!contains(DEFINES, ffmpeg2) {
!contains(DEFINES, ffmpeg3) {
!contains(DEFINES, ffmpeg4) {
!contains(DEFINES, ffmpeg5) {
!contains(DEFINES, ffmpeg6) {
DEFINES += ffmpeg4
}}}}}
这段代码的执行逻辑是从外到内逐层判断:只要任意一层发现对应版本已定义,整个嵌套块就不会执行到最里层,DEFINES += ffmpeg4 也就不会生效。五个 !contains 对应五个版本,缺一不可;少写一层,那个版本就不会被纳入“已定义”的排除范围,默认值可能被错误追加。
大括号的数量要和嵌套层数严格对应,五个 !contains 配五个左括号,结尾五个右括号。qmake 对括号不匹配的报错信息很不友好,经常只提示某一行语法错误,实际根因在几十行之外。血泪经验是:改这段时先把括号数一遍,再跑 qmake。
DEFINES += ffmpeg4 里的 ffmpeg4 是一个编译宏,不是变量名。它会被传进编译器,同时也能被后面的 contains(DEFINES, ffmpeg4) 读到。这种“写进去再读出来”的用法是 qmake 条件判断的常见套路,理解这一点,后面的版本映射就不难读。
3.2 版本号映射到目录名
默认值确定后,要把宏映射成实际的目录前缀。这里用一条从新到旧的 else 链:
qmake复制# 把 DEFINES 里的版本宏翻译成目录前缀 strPath
contains(DEFINES, ffmpeg6) {
strPath = ffmpeg6
} else {
contains(DEFINES, ffmpeg5) {
strPath = ffmpeg5
} else {
contains(DEFINES, ffmpeg4) {
strPath = ffmpeg4
} else {
contains(DEFINES, ffmpeg3) {
strPath = ffmpeg3
} else {
strPath = ffmpeg2
}}}}
判断顺序是从 ffmpeg6 往 ffmpeg2 走,最后那个 else 不再判断,直接兜底成 ffmpeg2。这个顺序不能随意打乱:如果先判断 ffmpeg2,那么同时定义了 ffmpeg2 和 ffmpeg6 的情况下,strPath 会被赋成 ffmpeg2,后面的 ffmpeg6 分支永远进不去。虽然正常工程不该同时定义两个版本,但流水线上误传参数的情况并不少见,顺序上从新到旧能让高版本优先,至少不会静默退到老版本。
这段代码的价值在于把“版本宏”和“目录名”解耦。宏名是 ffmpeg6,目录名也是 ffmpeg6,看起来重复,但两者职责不同:宏是给编译器和条件判断用的标识,目录名是拼路径用的字符串。哪天目录命名规则变了,只改 strPath 的赋值,不用动 DEFINES 那一层。
还有一个边界要提前想到:如果有人在 qmake 命令行传了 DEFINES+=ffmpeg7,这段代码不会报错,strPath 会落到最后的 else 变成 ffmpeg2,然后去一个不存在的目录找库。这种“未知版本被静默降级”的行为很隐蔽,后面验证章节会用 error() 把它挡在 qmake 阶段。
4. 代码开发工具里的第二道开关:平台与位数决定库目录
版本前缀确定后,还差库目录这一层。同样是 ffmpeg4,Windows 64 位要 winlib64,Linux 64 位要 linuxlib64,macOS 要 maclib64,三者的目录名完全不同。这一层靠系统判断和 QT_ARCH 组合完成。
4.1 四类系统分支的书写顺序
qmake复制# Windows:按 QT_ARCH 区分 32/64 位
win32 {
contains(QT_ARCH, x86_64) {
strLib = winlib64
} else {
strLib = winlib
}}
# unix 覆盖 Linux、macOS、Android,先给一个通用默认值
unix {
contains(QT_ARCH, x86_64) {
strLib = linuxlib64
} else {
strLib = linuxlib
}}
# macOS 目前都是 64 位,直接覆盖 unix 分支的结果
macx {
strLib = maclib64
}
# Android 按 ABI 名区分
android {
contains(QT_ARCH, arm64-v8a) {
strLib = androidlib64
} else {
strLib = androidlib
}}
这段代码的关键不在单个分支,而在赋值顺序。qmake 是顺序执行的,后出现的赋值会覆盖前面的结果。unix 在 qmake 里覆盖 Linux、macOS、Android 等多个平台,所以 macx 必须写在 unix 之后,才能把 linuxlib64 覆盖成 maclib64;android 同理,写在 unix 后面才能生效。如果把 macx 挪到 unix 前面,macOS 构建会一路走到 linuxlib64 目录,然后在链接阶段报找不到库——这个错误看起来像库缺失,实际是分支顺序写反了。
win32 放在最前面是因为它和 unix 互斥,顺序影响不大,但保持“先 Windows、再通用 unix、后特例 macx/android”的书写习惯,读代码时能一眼看出覆盖关系。
4.2 QT_ARCH 判断位数
QT_ARCH 是 qmake 自带的变量,值来自当前 kit 的编译器架构。Windows 和 Linux 下 64 位一般是 x86_64,所以 contains(QT_ARCH, x86_64) 成立时选带 64 后缀的目录,否则回落到 32 位目录。Android 的命名不一样,64 位是 arm64-v8a,32 位是 armeabi-v7a,所以 Android 分支里判断的是 arm64-v8a。
这里有一个容易忽略的点:contains 是子串匹配,不是全等匹配。QT_ARCH 的实际值里如果包含 x86_64 字样就能命中,这在多数情况下没问题,但如果某个 kit 的架构名恰好把 x86_64 作为更长字符串的一部分,也可能误命中。工程里如果出现架构判断“看起来对但选错目录”的情况,先打印 QT_ARCH 的实际值,比盯着 .pro 猜要快。
另外,QT_ARCH 反映的是 Qt kit 的架构,不是 FFmpeg 库的架构。两者必须一致:kit 是 64 位,引用的库也必须是 64 位。混用会在链接阶段报机器类型不匹配,错误信息里通常带 file format not recognized 或 incompatible 字样。这个约束不是 .pro 能自动纠正的,只能靠目录选择正确来保证。
4.3 INCLUDEPATH 和 LIBS 收口
前面两步算出了 strPath 和 strLib,最后两行把它们拼成实际路径:
qmake复制# 头文件:版本目录下的 include,与位数无关
INCLUDEPATH += $$PWD/$$strPath/include
# 库文件:版本目录 + 位数子目录,六个库按依赖顺序排列
LIBS += -L$$PWD/$$strPath/$$strLib/ \
-lavformat -lavcodec -lavfilter -lswscale -lavutil -lswresample
$$PWD 是当前 .pro 文件所在目录,用它做基准能保证工程整体移动位置后路径仍然有效。INCLUDEPATH 只拼到 include,因为头文件不区分位数;LIBS 拼到 $$strLib,因为库文件分 32/64 位。这两行的目录层级必须和 2.1 节的矩阵对上,少一层或多一层都会导致找不到文件。
-L 指定库搜索目录,-l 指定库名,-lavformat 对应 libavformat。六个库的排列顺序不是随意的:avformat 依赖 avcodec,avcodec 又依赖 avutil,在部分链接器上,被依赖的库要放在依赖它的库后面,否则会出现符号未定义。材料里给的顺序是 avformat → avcodec → avfilter → swscale → avutil → swresample,照这个顺序写最稳;如果只用到其中几个,删掉不用的库比调整顺序安全。
路径末尾的斜杠也值得留意。-L$$PWD/$$strPath/$$strLib/ 带尾斜杠,拼出来的搜索目录不会因为缺少分隔符而粘连。这类细节在 Windows 上尤其明显,路径分隔符混用会让 qmake 生成出奇怪的编译命令。
5. 避坑排查:版本、位数、系统对不上时的五类现场
条件分支写完后,真正的问题往往在运行时才暴露。下面五类现场都是从目录矩阵和分支逻辑里能推出来的,遇到时按“现象 → 原因 → 解决”的顺序对一遍,比漫无目的地改路径快得多。
5.1 链接器报 cannot find -lavformat
现象:qmake 执行成功,编译也过了,链接阶段报 cannot find -lavformat,换一个库名可能报 -lavcodec,但错误格式一致。
原因:LIBS 里的 -L 目录不存在,或者目录存在但没有对应的库文件。最常见的触发是版本和位数组合出了矩阵里没有的格子,比如选了 ffmpeg2 却在 64 位 kit 下构建,strLib 被算成 winlib64 或 linuxlib64,而 ffmpeg2 根本没有这两个目录。
解决:先确认目标版本加目标位数在矩阵里有没有对应目录。ffmpeg2 只有 32 位,要出 64 位包就得换 ffmpeg3 或 ffmpeg4;ffmpeg5、ffmpeg6 只有 64 位,要出 32 位包只能退回 ffmpeg4 及更早版本。确认组合存在后,再检查 $$PWD 指向的目录层级是否和实际解压结构一致。
5.2 头文件找到了,库的位数却对不上
现象:编译阶段正常,include 里的头文件都能找到,链接阶段报机器类型不匹配,或者程序能链接但运行到调用 FFmpeg 时崩溃。
原因:INCLUDEPATH 用的是 $$strPath/include,LIBS 用的是 $$strPath/$$strLib,两者基于同一个 strPath,但 strLib 的位数判断和实际 kit 不一致。典型场景是手动改了 strLib 的赋值却没同步 QT_ARCH 判断,或者在一个 64 位 kit 里引用了 32 位库目录。
解决:把 QT_ARCH 的实际值打印出来,对照 strLib 的赋值分支。头文件和库必须来自同一个版本,位数必须和 kit 一致。头文件不区分位数这一点容易让人放松警惕,以为编译过了就没事,实际上链接阶段才校验库的架构。
5.3 默认版本被悄悄改成 ffmpeg4
现象:工程里明明只放了 ffmpeg6 的库,qmake 跑完却去 ffmpeg4 目录找文件,报目录不存在。
原因:!contains 嵌套的默认值逻辑在“一个版本都没定义”时生效,DEFINES += ffmpeg4 被追加。如果 .pro 里没有显式写 DEFINES += ffmpeg6,也没有在 qmake 命令行传版本,默认值就会接管。
解决:在 .pro 顶部显式声明版本,或者构建脚本里统一传 DEFINES+=ffmpeg6。默认值的作用是保证“什么都不传也能编”,不是替你做版本选择。工程里只保留一个版本的库时,显式声明比依赖默认值可靠。
5.4 macOS 构建跑去 linuxlib64 找库
现象:macOS 上 qmake 生成的链接命令里出现 linuxlib64,链接报找不到库,改成本地存在的 maclib64 后正常。
原因:unix 分支覆盖 macOS,macx 分支必须写在 unix 之后才能覆盖 strLib。如果 macx 写在前面,或者被误删,macOS 就会沿用 unix 赋的 linuxlib64。
解决:检查 .pro 里 win32、unix、macx、android 四个块的先后顺序,macx 和 android 都要排在 unix 后面。这个顺序问题是纯文本层面的,和库本身无关,但报错信息指向库缺失,容易带偏排查方向。
5.5 Android 的 QT_ARCH 名字写错导致落到 32 位目录
现象:Android 64 位构建时 strLib 被算成 androidlib,链接报 32 位库不兼容,或者直接找不到 androidlib64。
原因:contains(QT_ARCH, arm64-v8a) 的判断依赖 QT_ARCH 的实际值。如果 kit 的架构名不是 arm64-v8a 这个写法,判断不成立,就会走 else 落到 androidlib。另外,目录清单里没有列出 Android 的库子目录,androidlib 和 androidlib64 的实际命名要以拿到的包为准。
解决:先打印 QT_ARCH 确认实际值,再核对本地 Android 库目录的真实名字。两者对上之后,分支判断才有意义。Android 的 ABI 命名和桌面端差异较大,不能套用 x86_64 的判断习惯。
6. 让配置自己说话:验证路径真的选对了
条件分支写完后,最怕的是“看起来对、实际选错”。qmake 不会主动告诉你 strPath 和 strLib 最终是什么值,得自己让它打印出来。最直接的办法是在 .pro 末尾加一行 message():
qmake复制# 在 INCLUDEPATH 和 LIBS 之后打印,确认最终选中的目录
message("FFmpeg 版本目录: $$strPath")
message("FFmpeg 库子目录: $$strLib")
message("头文件路径: $$PWD/$$strPath/include")
message() 的输出会出现在 qmake 的执行日志里,每次跑 qmake 都能看到。版本切换、平台切换后先看一眼这三行,比等链接报错再回头猜要省时间。
第二层验证是看生成的 Makefile。qmake 跑完后,构建目录里会有 Makefile,搜 INCLUDEPATH 和 LIBS 能看到实际拼出来的路径。这一步能发现 message() 看不出的问题,比如路径里多了一层目录、尾斜杠粘连、变量展开后和预期不符。我一般会在换 kit 或换 FFmpeg 版本后固定做一次这个检查,尤其在做多平台出包时,三个平台的 Makefile 各看一遍,能提前发现分支顺序写反这类问题。
第三层是在 .pro 里加断言,把不支持的组合挡在 qmake 阶段:
qmake复制# ffmpeg2 只有 32 位库,64 位 kit 下直接报错,避免链接阶段才暴露
contains(DEFINES, ffmpeg2) {
contains(QT_ARCH, x86_64) {
error("ffmpeg2 不提供 64 位库,请改用 ffmpeg3/ffmpeg4 或自行编译")
}}
error() 会让 qmake 立即停止并输出指定信息。比起让错误拖到链接阶段变成 cannot find -lavformat,在 qmake 阶段报“版本和位数不匹配”要直观得多。断言不需要写全所有组合,把已知不存在的格子挡住就够了,比如 ffmpeg2 配 64 位、ffmpeg5/6 配 32 位。
这套配置我从一开始的到处写死路径,改成现在先核对矩阵、再分两层判断、最后加断言,最大的变化不是代码变长,而是出错位置前移了。以前一个路径错误要等到链接甚至运行时才暴露,现在 qmake 一跑就能看到选中的目录。从那以后我每次新增 FFmpeg 版本,都强制先把目录矩阵补进表格、再改 strPath 和 strLib 的分支、最后跑一遍 message() 确认,三步缺一步都容易留下隐患。希望帮到你。
