qmake 全面解析：从 .pro 到 Makefile，Qt 构建背后的总工程师

开头还是从我在开发群里看到的一个问题说起吧。有个人发了一段提问：“我往项目里加了一个新类，头文件和 cpp 都放进源码目录了，Qt Creator 重新构建了好几次，一直编译不到这个新文件，怎么回事？”底下人七嘴八舌：有人说是文件路径没写对，有人说是缓存，有人干脆让他把 build 目录整个删掉重新构建。这些回答不能说错，但都没戳到根子上——这个人多半是手动改了 .pro 文件里的 SOURCES 变量，然后直接点了构建，却没意识到 Qt Creator 构建的第一步其实是重新执行 qmake，只有 qmake 重新读取并解析了 .pro 文件，新加的自定义源码文件才会被写进 Makefile，编译器才看得见它。

这引出了很多人对 qmake 的普遍误解：写了一堆 .pro 语法，却完全不知道 qmake 到底在构建过程里扮演什么角色。这篇文章想把 qmake 讲透，它是 Qt 项目里名副其实的“总工程师”——不直接砌砖，但决定所有工序怎么排、各方怎么协作。理解了 qmake 的工作方式，所谓的“Qt 构建报错”“qmake 失效”“平台插件找不到”这类问题就不再是玄学，你能自己判断问题出在哪个环节。内容适合刚接触 Qt 的新手，也对用 Qt 做实际项目但一直没系统梳理过构建流程的人有帮助，当然如果你正在 qmake 和 CMake 之间反复横跳，这篇文章也能帮你把两者的边界看得更清楚。

1. qmake 到底在“管”什么：一个被误会的构建角色

很多人对 qmake 的第一印象是“一个写 .pro 文件的工具”，这个印象不能说错，但太表层了。qmake 本身并不做编译，也不做链接，它做的是另一件事：把项目描述文件（.pro）解析成构建系统真正能识别的 Makefile（或者 Visual Studio 工程文件）。真正执行编译的是 make/nmake/jom，真正把一堆 obj 文件和库揉成 exe 的是链接器。qmake 更像影视剧里那种施工总工程师——他不上脚手架，但脚手架怎么搭、混凝土什么时候浇、水电什么时候进场，全由他排。Qt 项目的构建链条里，qmake 就是排工序的那个人。

想验证这个说法非常简单。你打开一个用 qmake 管理的 Qt 工程，不用 Qt Creator，直接打开命令行工具，在工程目录下跑两条命令，效果和你在 IDE 里点“构建”按钮几乎一致：先执行 qmake（生成 Makefile），再执行 make（按 Makefile 里的工序调用编译器和链接器）。如果你随便找个 build 目录，打开里面生成的 Makefile 看一眼，会看到大量诸如 g++ -c main.cpp -o main.o 这样的具体命令，这些命令没有一条出现在你的 .pro 文件里，它们全是 qmake 根据 .pro 里的变量推导出来的。

1.1 从 .pro 到 Makefile 再到可执行文件

.qmake 处理 .pro 文件的过程，本质上是个“两阶段演绎”过程。第一阶段是规则展开，读取工程中 .pro 文件里面每个变量，比如 SOURCES、HEADERS、TEMPLATE、QT、CONFIG，然后结合它内置的几十条平台相关规则（Windows 和 Linux 的规则不一样，MSVC 和 MinGW 的规则也不一样），把这些描述性的配置展开成一个大而全的 Makefile。

为了让你对这套流程产生更直观的认识，我拿一个最简单的 qmake 工程来做演示。工程只有三个文件：main.cpp、mywidget.h、mywidget.cpp，再加一个 qmake.pro。正常思路是在终端里执行：

bash复制qmake qmake.pro
make

执行完 qmake 之后，目录下会多出一个 Makefile。make 在读这个 Makefile 时会自动把 main.cpp、mywidget.cpp 分别编译成 main.o 和 mywidget.o，然后用链接器把两个 .o 文件组合成最终的 app 可执行程序。

如果你只看 .pro 文件，你看到的只是一个非常简单的内容：

makefile复制QT += widgets
TARGET = demo
TEMPLATE = app
SOURCES += main.cpp mywidget.cpp
HEADERS += mywidget.h

但在这里面你看不到 -fPIC、-m64 之类的编译选项，看不到 Qt 头文件路径，也看不到要链接 Qt5Widgets、Qt5Gui 这些库的指引。这些“脏活”全部由 qmake 在生成 Makefile 时自动补齐。它知道你声明了 QT += widgets，于是把 Qt5Widgets 的 include 目录、lib 目录、链接库名全部写进 Makefile；它知道你用的是 gcc 还是 MSVC，于是自动追加平台相关的编译开关。

从这个意义上说，qmake 的核心价值不是“写工程文件”，而是“替不同平台生成正确的构建指令”。你在 Windows 上写 .pro 不用关心 Windows 下要链什么库，切到 Linux 上重新跑一次 qmake，它生成的 Makefile 会换成 Linux 需要的库名和路径。这就是跨平台构建的底层逻辑，也是为什么 qmake 后来会被用于生成 Visual Studio 的 .vcxproj 工程，本质上都是同一套工程描述在不同构建后端之间的翻译。

1.2 什么时候必须手动跑一次 qmake

前文提到的那个人发现新加的源码文件没有被编译，原因多半正是：他手动改了 .pro 文件，却没有让 qmake 重新生成 Makefile，所以 make 看到的还是旧文件清单。Qt Creator 一般会在你编辑 .pro 后自动触发 qmake，但如果你是在命令行下独自操作，或者打开了“手动构建”模式，就很容易踩这个坑。

有一个我至今印象很深的案例，某程序里源文件已经被小心翼翼放进目录，为了验证它是否参与构建，甚至故意在其中加入 #error build me。但构建结果却安静如常，完全看不到报错信息。折腾了半天，最后发现原因简单得近乎可笑：Makefile 还是旧的，根本没有包含这个新文件。所以后来我会习惯性地记住一个口诀：凡是改了 .pro 相关的东西，一定要重新执行 qmake；只改了 .cpp/.h 的内部实现，那直接 make 就够了。

这不是说每次都要慌慌张张去跑 qmake，而是说你要清楚构建系统的状态边界。在没有 IDE 辅助的纯命令行流程里，构建缓存与 Makefile 的“过期”状态就是最常见的隐形杀手。理解这个边界之后，很多“Qt 项目构建诡异失败”的问题基本能消除一半。

2. .pro 文件里的“图纸语言”：常用语法与背后的执行逻辑

很多 Qt 教程教 .pro 语法时，都是“一句话带过”，把 SOURCES、HEADERS、TEMPLATE 列一遍就完了。但 qmake 这门语言其实有它自己的执行逻辑，它本质上是按顺序逐行解释执行的脚本。理解这点，你才算真正掌握它。很多人只把它当文本配置文件用，所以一旦 .pro 里出现稍微复杂的循环、条件分支和变量拼接，就束手无策。

.qmake 的解析流程有一个非常关键的特点：它在解析 .pro 时，就是自上而下逐行执行，变量没有声明后置之说。举个例子，你在前面用了某个变量的值，而这个变量在后面才被赋值，那么前面拿到的就是空字符串；你必须在赋值之后再使用它。这种特性和 C/C++ 的预处理器很相似，和你平时写的配置文件思维“键值对乱序无所谓”完全不同。

2.1 分清等号家族的几个“近亲”

.qmake 里的等号不像数学里的等号，它更像操作指令。这里把常用的几种赋值方式整理出来，它们几乎决定了你能否写出多平台兼容的 .pro：

很多从 CMake 转过来的新手容易犯的错误，是把 SOURCES = a.cpp 当成“追加一个源文件”。在 CMake 里多次使用 set(SOURCES ...) 并不会默认清空（取决于使用方式），但在 qmake 里，只要你用了 =，就是一刀切：前面的内容全没了。所以如果你在某个目录分支里写 SOURCES = platform_win.cpp，那之前积累的所有跨平台源文件条目都会被抹掉。这正是许多条件分支项目里坑人的根源。

正确做法是在分支里使用 +=，保证不同分支是增量添加。举个真实场景：你有一个日志模块，Linux 下使用 syslog，Windows 下使用事件日志，你可能会写出这样一份 .pro：

makefile复制SOURCES += logger.cpp
win32 {
    SOURCES += win_event_logger.cpp
}
linux {
    SOURCES += syslog_logger.cpp
}

如果第二行你写成了 SOURCES = win_event_logger.cpp，那 logger.cpp 就会被清掉，最终编译时你会收到各种诡异的“未定义引用”链接错误。这类问题排查起来往往比语法报错更痛苦，因为它不报错，只是链接时告诉你缺了函数实现。所以记住一个习惯：增量相关一律使用 +=，只有当你刻意要重置某个变量时才用 =。

2.2 条件作用域：让一份 .pro 适配多平台、多版本

qmake 支持作用域语法，写法类似于 if，但语法相当简洁，只需要在大括号前写条件，就能让里面的赋值语句仅在条件成立时执行。在上一小节的例子中我直接写了 linux { ... } 和 win32 { ... }，这就是最典型的作用域写法。

除了平台条件，CONFIG 也是一个被高频使用的条件开关。qmake 默认会根据当前构建配置把 debug 或 release 加入到 CONFIG 变量中。你可以借助这一点实现差异化处理：

makefile复制CONFIG += debug_and_release

CONFIG(debug, debug|release) {
    DESTDIR = $$PWD/bin/debug
} else {
    DESTDIR = $$PWD/bin/release
}

在这段代码里，CONFIG(debug, debug|release) 的语义是“如果当前 CONFIG 中包含 debug，就执行第一段，否则执行第二段”。第二个参数 debug|release 是候选集合，它帮 qmake 明确要检查的作用范围。这种写法在命令行构建时特别有用，因为你可以直接决定最终的二进制产物输出在哪个目录，不用每换一次 debug/release 就手动挪文件。

还有一个不得不提的常用内置变量是 QT。QT += widgets、QT += network、QT += sql 这种写法，实际是在告诉 qmake：这个工程要链接 Qt 的哪些模块。你可能觉得这只是声明依赖，很机械，但很少有人讲清它和 LIBS += -lQt5Widgets 的区别——QT 模块声明的是一种更高层的工程语义，qmake 会额外处理模块间的相互依赖，比如你声明了 QT += widgets，它同时会知道需要 widget 模块依赖的 gui、core 等；而手动写 LIBS 时，你只负责把库名写对，模块依赖的“连带责任”得自己承担。

2.3 变量存在先后顺序，别让“赋值”变成“错觉”

qmake 按行号顺序解释这一点，还经常体现为另一个细节：如果你先用 message($$VAR) 打印变量，再给它赋值，那打出来的就是空的。由于 qmake 中 .pro 内 message() 的作用是向控制台输出调试信息，这条信息打印的时机完全取决于调用位置，所以你会看到先打印空白、后头又赋值成功这种怪异现象。

对这个问题的处理，我用过最简单高效的办法：真正需要交叉依赖的公共配置，尽量抽到文件的前部，等它们全部定义完之后，再统一去用。或者，你可以在 .pro 文件最后输出一行完整的拼接结果，方便确认整体变量内容是否符合预期。

3. 实例拆解：用 qmake 协调第三方库与工程源码

讲理论说得再多，不落到实际项目里总隔着一层纸。这里我拿一个常见需求出来：某项目需要把采集到的时域信号转换成频域波形，然后显示出来。Qt 圈子里大家大概率会选 QCustomPlot，同时配合一个 FFT 库，于是热词里会出现“qt时域图转换为频域图，使用qcustomplot显示”“qcustomplot kissfft时域到频域波形”这类搜索。真正到落地的步骤，并不是在源码里 include 个文件就好，而是你得先想清楚：第三方库的代码怎么进入你的 qmake 工程。

3.1 源码工程化 vs 预编译库二进制：两种集成逻辑

在 .pro 中集成第三方库，通常有两种主流方案。

方案一：直接把第三方库的源码放进你的工程源码目录，把它当成你自己项目的一部分来编译。对于 QCustomPlot 这种体量不大、只有 qcustomplot.h 和 qcustomplot.cpp 两个核心文件的控件来说，这是最直截了当的集成方式。你的 .pro 里只需要把这些文件加进 SOURCES 和 HEADERS，编译器自然会帮你编译、链接，什么都不用额外操心。

方案二：使用别人已经编译好的 .lib/.a/.dll/.so，在 .pro 里通过 INCLUDEPATH 和 LIBS 告诉 qmake 去哪里找头文件和库。这种做法的好处是编译时间明显变短，库本身不需要每次参与编译。缺点是：二进制库需要和你的编译环境严格匹配，包括编译器版本、Qt 版本、debug/release 模式。一旦不匹配，你可能会踩到一堆二进制兼容性的坑。

在大多数信号处理项目里，FFT 计算库往往采用方案二，因为算法库庞大的源码不值得每次都掺进你的工程。QCustomPlot 通常使用方案一，因为它本身虽然只有两个文件，但为了让它支持 OpenGL 等特性，你写 .pro 时还要按需追加相关模块。而且 QCustomPlot 的开发场景决定了使用者经常需要修改库的源码来定制图表，把它当“源码模块”管理更灵活。

3.2 INCLUDEPATH、LIBS、DEPENDPATH 各自负责什么

如果你决定了要采用方案二，必须理解 .pro 中三个变量分别在企业中扮演什么角色。很多人把三个变量混成一锅粥，一口气写上 INCLUDEPATH += C:/lib/fftw3 LIBS += C:/lib/fftw3/fftw3.lib，但完全不清楚哪一行负责哪一部分。

INCLUDEPATH 决定的是“找头文件”的搜索路径。当你代码里写 #include "fftw3.h"，预处理器会沿着 INCLUDEPATH 给出的目录去搜索。找不到头文件，最常见的报错是 fatal error: fftw3.h: No such file or directory。

LIBS 决定的是“找库文件”的路径和库名。在 Windows/MSVC 环境下，你通常会写全路径 .lib 文件名，比如 LIBS += D:/lib/fftw3/lib/x64/fftw3.lib。在 Linux/GCC 环境下，标准写法是 LIBS += -L/path/to/lib -lfftw3，其中 -L 指定库搜索目录，-l 指定库名，gcc 会自动在 lib 目录里寻找 libfftw3.so 或 libfftw3.a。

DEPENDPATH 则管的是 qmake 生成依赖关系时的额外搜索路径，如果你在 .pro 中只写了头文件路径、但编译时还需要跨目录追溯更深层的依赖，它会派上用场。平时常见的情况里，INCLUDEPATH 其实已经覆盖了绝大多数需求，DEPENDPATH 更多用于多级 pri 子项目之间。

把变量一拆，你会明白所谓“导入依赖”的正确姿势不是一股脑堆变量，而是要分清楚：你的代码在哪个环节需要解析头文件，哪个环节找不到符号。当你搞清楚这个，很多编译错误会从“玄学”变成可预期的流程问题。

3.3 还有一处真不少人忽略：DESTDIR 与 DLL 的输出目录

如果你在 Windows 下用动态链接库，光在 .pro 里把依赖写对还不够。一个典型窘境是：编译、链接全部报成功，生成的 exe 就在构建目录里躺着，双击却提示找不到某个 DLL。原因很简单，运行期可执行文件是按自己的搜索路径去加载 DLL 的，它不会因为你 LIBS 指向了库目录就自动去那个位置找。

从 qmake 的角度来看，解决方案有两类思路。思路一是把 DLL 复制到 exe 的输出目录。此时你可以在 .pro 里自定义 QMAKE_POST_LINK，构建完成后执行一条复制命令。我的做法是写一个通用复制段落到 .pro，利用 $$OUT_PWD 和 $$PWD 分别表示构建目录和源目录，把外部依赖统一复制到 DESTDIR：

makefile复制DESTDIR = $$PWD/bin
CONFIG(debug, debug|release) {
    QMAKE_POST_LINK += $$quote(copy /Y $$PWD\\..\\3rdparty\\fftw3\\dll\\libfftw3-3.dll $$DESTDIR\\debug\\)
} else {
    QMAKE_POST_LINK += $$quote(copy /Y $$PWD\\..\\3rdparty\\fftw3\\dll\\libfftw3-3.dll $$DESTDIR\\release\\)
}

这段内容是 Windows 风格，如果切到 Linux/macOS，则通常会配置 rpath，让程序运行时自动去相对路径寻找 .so 文件。rpath 的设置在 qmake 里也有专门变量，比如 QMAKE_RPATHDIR += $$PWD/../3rdparty/lib，它能直接改变运行时动态库搜索路径，不用复制也能跑。很多开发者在 Linux 上遇到“构建成功但运行时报 cannot open shared object file”，八成就是没设置 rpath 或没把 .so 路径加到 ldconfig。

4. 当“总工程师”交接不力：构建成功但跑不起来的平台插件问题

qmake 的工作做到位，编译、链接都顺顺当当，并不等于你的软件在别人机器上也能跑。热词里高频出现的“windows no qt platform plugin could be initialized reinstalling the applicat”，以及 Linux 上常见的“qxcbconnection: failed to initialize xrandr”，都是这类症状的典型代表。它们的共同点是构建环节全部正常，但程序一启动就卡在 Qt 平台插件的加载上。要弄清原因，先得明白 Qt 在到底怎么找到自己的平台插件。

Qt 在运行时需要通过 QApplication 加载一个平台插件，也就是广义上的“窗口系统后端”。在 Windows 上是 qwindows.dll（对应的其实是 qwindows 插件），在 Linux/X11 上是 libqxcb.so。这个插件不在你的可执行文件同一个目录下，而是在 Qt 安装目录的 plugins/platforms/ 子目录里。Qt 自己找插件有一套路径搜索逻辑，它默认会基于编译时写入的 Qt 安装路径去寻找，或者基于可执行文件的相对目录去尝试。

当你的应用部署到别的机器或挪到别的目录时，原来编译时写进去的安装路径可能会失效；如果 Qt 又没在 exe 目录下找到 platforms/ 子目录，它就会报出那句经典的“could not find the Qt platform plugin”。所以这一类问题的本质，是一个运行时资源布局难题，和你 .pro 写不写得“正确”反而关系没那么直接，只是很多新手会误以为是编译阶段的问题。

4.1 平台插件问题的典型现场还原

先说 Windows。你在 Qt Creator 里按 F5 能运行，是因为 Qt Creator 本身知道 Qt 装在哪里，会自动把 Qt 的 bin 目录、plugins 目录放进环境变量。可一旦你直接去 build 目录里双击那个 exe，环境变量少了 Qt 的路径，Qt 找不到 platforms/qwindows.dll，于是弹出那个著名对话框。

Linux/X11 下的 qxcbconnection 报错更迷惑，因为它是运行时才检查 XCB 扩展是否可用。热词里的 qxcbconnection: failed to initialize xrandr 就是 qxcb 插件在尝试初始化 XRandR 扩展时失败。如果你是在服务器或无显示器环境下跑 GUI 程序，出现这个再正常不过；如果你有显示器但缺少 xcb 相关库，同样会失败。从这个角度看，它不是 .pro 文件能直接修好的，而是你目标运行环境里缺系统级依赖。

不过，qmake 部分并非无事可做。至少你可以通过 .pro 预先控制好部署目录结构、复制规则，让调试和发布阶段所依赖的平台插件被正确带进可执行文件目录。我的常用做法是专门留一个 deploy.pri，在工程里集中定义输出目录、第三方 DLL 和 Qt 插件的拷贝规则，这样每次构建后都会自动形成一套“可以拎走”的运行目录。这套梳理思路，往往是很多人从“我自己机器有人跑”迈向“别人机器也能跑”的关键一步。

4.2 一套能“减负”的部署目录设计

我给自己定过一个朴素的部署原则：让 build 出来的目录结构，尽量接近最终发布目录。也就是说，不要在 Debug 状态下编译到一个完全单薄的目录，等到发布时才临时去思考要带哪些 DLL 插件。我习惯在 .pro 里把 DESTDIR 设置成统一输出目录，并附加一个拷贝文件列表，让构建的结果天然包含运行所需的最小依赖集。

具体可以这样组织。假设你的 Qt 安装在 C:/Qt/5.15.2/mingw81_32，工程源码目录下有一个 deploy 目录，你的 .pro 中可以自定义一个 deploy 命令：

makefile复制CONFIG(release, debug|release) {
    DEPLOY_COMMAND = $$quote($$QMAKE_COPY_DIR $$[QT_INSTALL_PREFIX]/plugins/platforms $$DESTDIR/platforms)
}

大致逻辑是：把 Qt 安装目录下 plugins/platforms 文件夹复制到 DESTDIR。实际项目中还需要把 styles、imageformats、tls 等按需复制，把 Qt 的 DLL 也复制过去。你可以直接用 windeployqt 工具自动完成大半活，但如果你希望在命令行构建时不依赖额外工具，在 .pro 里手写一段部署规则也能达到同样效果。

当你把构建与部署规则写进 .pro，qmake 的“总工程师”属性又会多一层价值：项目描述不再只描述源码怎么编译，还描述最终产物如何组装起来。

5. 排查 qmake 问题的三个实用调试姿势

.qmake 的报错大多短促而不留情面，比如 Unknown test function 或者变量明明存在却展开为空。很多人一看到这类输出就立刻跑去搜索引擎复制粘贴，这个习惯其实并不高效。qmake 自身提供了多个调试选项，可以让你“看穿”它内部行为，比盲目搜报错信息要靠谱得多。

5.1 让 qmake 暴露解析过程：-d 与 -Wall

在命令行里执行 qmake -d your.pro，qmake 会输出非常详细的解析过程，包括读了哪些文件、定义了什么变量、调用哪些内置测试函数。-d 的全称是 debug，会把这些过程打印到终端上。缺点是信息量确实很大，好几屏的内容翻起来比较痛苦，所以有时你也可以加上 -d 配合 > qmake_debug.log 2>&1，把输出存成文件再搜索关键字。

如果你只是想知道 qmake 对 .pro 中某些语法是否满意，-Wall 会更温和，它会启用所有警告。比如很多人在 .pro 里错误使用了一个函数名，qmake 默认可能就放过了，但加了 -Wall 会提示这是一个未知的测试函数。让 qmake 把“心里的犹豫”都写在脸上，排查问题的门槛立刻降了很多。

5.2 把生成的 Makefile 当“日志”读

这个思路其实是最直接、也最容易被忽略的好主意。很多人只在构建失败时才会去翻 Makefile，平时根本不看它。但 qmake 生成的 Makefile，本质上就是 qmake 对整个 .pro 的“理解结果”。当你想知道某个变量到底有没有生效、某个编译选项到底追加没有，最快的验证方式不是对着 .pro 猜，而是去生成的 Makefile 里搜索。

我自己排查问题的一个例子是，当时我写了 DEFINES += USE_FEATURE_X，却发现编译后代码里的宏没有生效。当时第一时间去翻 Makefile，搜索 USE_FEATURE_X，压根没有。继续往上查，发现自己把 DEFINES 那条赋值写在了一个错误作用域里，根本没有进入当前构建配置的分支。这类问题如果你不看 Makefile，只能一次次加 message() 打印验证，效率极低。

5.3 使用 -E 预展开与 qmake -query 确认路径

有些时候问题出在变量值本身，比如路径带不带斜杠、写的是相对路径还是绝对路径。此时 qmake -E 可以帮你把 .pro 中所有变量展开并输出展开后的结果，类似于 C/C++ 编译器的预处理输出。它会让你一眼看出某个 $$PWD 是否被正确展开成了绝对路径，某个 $$[QT_INSTALL_LIBS] 在具体环境里到底指向何处。

另外，qmake -query 可以查看 Qt 当前安装信息，包括 QT_INSTALL_PREFIX、QT_INSTALL_LIBS、QT_VERSION 等字段。当你怀疑 Qt 环境配错时，执行 qmake -query 看下输出结果即可，很多时候“找不到 Qt 库”“platform plugin 初始化失败”的根因是系统里有多个 Qt 版本，当前调用的 qmake 来自一个与其他模块不匹配的版本。顺便提示一句：在命令行里跑 qmake 前，最好先确认它到底指向哪儿，where qmake（Windows）或 which qmake（Linux/macOS）是好习惯。

6. 从单品走向多模块：subdirs 工程与 pri 共享的边界感

如果一个项目只有单个可执行程序，.pro 文件写起来并不复杂。但实际项目很少这么天真，通常是一套完整软件体系由主程序、核心库、插件等不同模块组成，甚至一个代码库里要同时产出多个可执行程序。这种时候，qmake 的另一个“大工程管理”玩法：TEMPLATE = subdirs 就派上用场了。

用 subdirs 模式，你可以在一个顶层 .pro 里列出多个子项目，qmake 会按照依赖关系依次处理每个子项目的构建。它的关键配置是 SUBDIRS 变量：

makefile复制TEMPLATE = subdirs
SUBDIRS += core \
           ui \
           tools

core.file = core/core.pro
ui.file = ui/ui.pro
ui.depends = core
tools.file = tools/tools.pro
tools.depends = ui

这里 ui.depends = core 相当于明确告诉 qmake：构建 ui 之前，先构建 core，这样 ui 链接 core 时才能保证库文件已经生成。很多人在向 subdirs 工程中添加子项目时，经常忘了 subdirs 模式下 .pro 之间自动共享源码变量吗？其实它根本不会自动传递其他信息，每个子项目独立解析、独立生成 Makefile，所有公共配置只能通过共享的 pri 文件来同步。

6.1 把可复用配置抽进 pri 之前，先想清楚什么该抽

-pri 文件本质上是 qmake 的“模块化片段”，你可以把若干子工程都要用的路径、库列表、公共宏定义放到一个 pri 文件中，然后通过 include(common.pri) 把它们引入各个 .pro。热词里那个“qt creator 创共享pri”说的就是这层需求。但这个操作并不建议一开始无脑做，因为过度抽象会让 .pro 的阅读成本急剧上升，最典型的反例是把三五个项目各自不同的私有配置也硬塞进公共 pri，结果改一个子项目配置却波及所有项目。

我通常只把这两类内容放进 pri：一是第三方依赖路径与版本宏定义，比如多少个模块都指向同一个 FFT 库、同一个 JSON 库版本；二是跨平台编译开关，比如某组编译选项写错会影响全局，但必须保持统一。归根结底，pri 是为了解决“多处重复、需要同步”的问题，而不是为了减少 .pro 行数。如果某段配置只在单个子项目里使用，放进 pri 就纯属画蛇添足。

6.2 多级目录之间的相对路径处理

多模块工程里最容易出错的是路径。因为 .pro 文件分散在不同目录，qmake 内置变量 $$PWD 指向“当前 .pro 文件所在目录”，而不是“你执行 qmake 的目录”。你在 core/core.pro 里写 INCLUDEPATH += $$PWD/../include，实际指向的是项目根目录下的 include；如果你在顶层 .pro 里也写同样的相对路径，由于顶层 .pro 所在目录不同，同一行代码可能指向完全错误的位置。

正是因为这一点，我建议多模块工程中最好不要使用裸的相对路径，尽量从 $$PWD 出发或在 pri 中基于顶层 PRO_FILE_PWD 计算。比如有一个 common.pri，它可能被子项目 include，那可以在 pri 里先定义公共根目录：

makefile复制PROJECT_ROOT = $$PWD/..
INCLUDEPATH += $$PROJECT_ROOT/include
LIBS += -L$$PROJECT_ROOT/lib

这里的技巧是：pri 文件存于哪里，$$PWD 就会指向哪里，一般 pri 文件若和 .pro 不在同一目录，可以谨慎使用它来推导。把路径基准统一在一个固定锚点，再通过追加的方式切换子项目路径，就能避免不同目录下的 .pro 由于相对路径基准不同而互相猜忌。

qmake 在日常项目里看似只做一个简单的 Makefile 生成步骤，但它的很多设计都“恰好在某个规模上够用”。有人说 qmake 不够现代、不想学，我认为这个说法有一定道理，但在 Qt 庞大的历史遗产和 Qt Creator 默认支持的强势加持下，读懂 qmake 依旧是一种能直接转化为生产力的技能，尤其是当你调试老项目、参与 Qt 插件开发或者在嵌入式 Linux 环境中交叉编译时，qmake 的知识几乎是绕不开的基本功。如果你已经能把 .pro 里的变量、作用域、子项目依赖关系整明白，再去看 CMake 工程中的 target 依赖和接口传播，会感觉两条路线上的许多核心思想惊人的相似。毕竟，构建系统的核心问题永远是那几个：源码清单、依赖关系、输出位置，谁能在不同规模的项目里把它们组织得顺手，谁就是合格的“总工程师”。