如果让我在常用的几个构建系统里挑一个“被低估得最厉害”的，我大概率会选 Qbs。很多人一听到 Qbs，第一反应就是“Qt 生态里那个只能配 Qt Creator 用的东西”，我一开始也这么想。直到某次在一个跨平台工具库上被 CMake 的“改了头文件却不重新编译”问题折腾到怀疑人生，偶然用 Qbs 重写了一遍构建描述之后，才意识到它在依赖追踪、并行调度和多目标构建上的设计思路，确实要比传统基于文本规则的构建系统完整很多。这篇文章不打算讲 Hello World，而是围绕真正把 Qbs “用起来”会碰到的东西：Profile 配置、自定义 Module、性能调优、跨平台条件化、排错思路，最后给一个完整的库+应用+测试工程示例。适合已经能跑通简单 Qbs 工程、想在真实项目里深入使用的人。

1. Qbs 凭什么值得投入时间：审美差异背后的工程价值

1.1 传统构建系统让机器“照着做”，Qbs 让机器“自己算”

很多人第一次打开 Qbs 的工程文件，会有一种奇怪的感觉：这看起来不像构建脚本，更像是一棵对象树。确实如此。CMake 和 Makefile 的底层逻辑是“命令式”——你把编译器怎么调用、依赖怎么连接一条一条写清楚，构建工具照着执行；而 Qbs 的工程描述更像“声明式”——你告诉它最终要产出什么（可执行文件、动态库、测试程序），每个产出包含哪些文件、依赖哪些模块，剩下的编译顺序、依赖推导和增量更新交给 Qbs 自己处理。

这种差异在真实维护中非常明显。CMake 里常见的“我把新头文件加进目录，但 Make 就是没重新扫描”“这个宏定义要透传给下一个 target，我得一个个 target_link_libraries 去补”，在 Qbs 里基本不会发生。Qbs 在构建之前会把整棵工程描述编译成一个不可变的构建图（build graph），图中每个节点是一次具体操作：编译、链接、复制文件、代码生成。每次构建时，Qbs 直接拿当前源码状态和构建图做对比，只执行失效节点。因为整张图是结构化的，节点之间的依赖关系不是靠字符串比较硬凑出来的，而是通过文件标签（file tags）和规则（Rule）自动传播的。

Qbs 的规则系统有四个基础构件：FileTagger（把文件后缀映射为标签，比如.cpp映射为cpp）、Scanner（扫描源码中的#include、import等引用，发现额外依赖）、Rule（消费一种或多种标签的输入，产出带新标签的产物）、Transformer（单输入单输出的快速转换）。这四个构件叠加，就是 Qbs 能“自己算依赖”的原因。你会发现问题被抽象得特别干净：想集成一个新的代码生成工具，本质上就两步——给输入文件打标签，写一条规则把标签变成cpp。

1.2 Qbs 解决了哪些实际问题，代价又有哪些

到底值不值得从 CMake 迁到 Qbs？我的回答是：看项目形态。如果你的项目是一个由你自己维护全部源码、需要长期支持多平台多配置的独立工程，Qbs 的收益远远大于学习成本。如果你主要工作是拼接一堆第三方开源库，指望每个库都原生支持 Qbs，那现阶段生态还不支持这种玩法，会相当痛苦。

我把几个主流构建系统的差异整理成一张表，方便对比：

Qbs 最大的代价就是生态。CMake 里有FindXXX.cmake帮你定位各种库，Qbs 里很多时候你得自己写探测模块。但如果你维护的是自家几个库和应用的组合，这反而成了优势——你可以把所有构建知识收拢到一套 Qbs 描述里，而不是散落在无穷无尽的 CMake 片段中。第二个代价是团队需要替构建系统本身的“面子工程”花一点时间，比如让所有人理解 Profile 和 configuration 的区别。不过一旦跨过这个坎，日常构建维护工作量会明显下降。

2. 决定构建正确性的三件套：Profile、Module 与 Product 的协作

2.1 Profile 是“环境快照”，不是“平台名称”

很多 Qbs 新手会把 Profile 和“平台”画等号，这其实是第一个容易踩的坑。Profile 在 Qbs 里的作用是完整描述一套编译环境：编译器路径、体系架构、系统根目录、ABI、Qt 版本等。同一个 Linux 机器上，你可以有三个 Profile：一个用 GCC、一个用 Clang、一个专门给 ARM 交叉编译，它们都跑在同一台机器上。

快速创建一个 Profile 的方式是先自动检测：

qbs setup-toolchains --detect qbs config --list profiles

如果机器装了 Qt，你还可以把 Qt 的配置也挂到某个 Profile 上：

qbs setup-qt /opt/qt/bin/qmake myprofile

自动检测通常能找到系统里常见的编译器，但它不会读你的心思。交叉编译这种场景，建议手动建立一个新 Profile，并显式指定工具链的关键属性。这里我习惯的做法是先用基础 Profile 继承，再逐项覆盖：

qbs config profiles.arm64.baseProfile myprofile qbs config profiles.arm64.qbs.architecture: arm64 qbs config profiles.arm64.cpp.toolchainInstallPath: /opt/arm-gcc/bin qbs config profiles.arm64.cpp.sysroot: /opt/arm-sysroot qbs config profiles.arm64.cpp.compilerName: arm-linux-gnueabihf-g++

注意不同 Qbs 版本里属性名会有微调，但思路是一致的：Profile 就是构建环境的快照。我在团队里要求所有成员把 Profile 配置写进一个初始化脚本，用命令直接生成，而不是让每个人手动qbs config，否则一定会出现两个开发者的编译器路径不同、导致同样的代码编译出不一样结果的尴尬情况。排查这类问题最痛苦，因为构建日志全部正常，就是行为不一致。

用 Qbs 构建时，指定 Profile 的方式是：

qbs build profile:arm64

如果你不指定，会使用默认 Profile。这里有个细节我建议养成习惯：显式写出profile:参数，哪怕本地只有一个 Profile。因为 CI 机器和开发机的默认 Profile 很可能不一致，显式指定能避免构建在换环境后，因为“一套配置隐式生效”而浪费半天定位。

2.2 自定义 Module 把公共构建能力封装成可复用单元

Qbs 的 Module 是高级玩法里最有价值的一块。一个 Module 可以包含属性定义、参数校验、运行环境设置甚至构建规则，Product 通过一个Depends就能继承整套行为。这有点像把一堆 CMake 函数和接口 target 打包成一个小 SDK，但语法和逻辑都更干净。

举一个我在实际项目中封装过多次的例子：自定义代码生成器。假设你有若干.myidl文件，需要由一个命令行工具生成对应的 C++ 源码。用 Qbs 写一个codegen模块，大概长这样：

Module { name: "codegen" property string generatorPath: "codegen" property stringList codegenFlags: [] validate: { if (generatorPath === "") { errors.push("generatorPath must not be empty"); } } Rule { inputs: ["myidl"] Artifact { filePath: input.baseName + ".generated.cpp" fileTags: ["cpp"] } prepare: { var args = product.codegen.codegenFlags; args = args.concat([input.filePath, output.filePath]); var cmd = new Command(product.codegen.generatorPath, args); cmd.description = "codegen " + input.fileName; return [cmd]; } } }

然后在 Product 里调用：

Product { name: "demo" type: "application" Depends { name: "codegen" } files: ["main.cpp", "interface.myidl"] } FileTagger { patterns: ["*.myidl"] fileTags: ["myidl"] }

当 Qbs 扫描到interface.myidl时，先由 FileTagger 把它打上myidl标签，再由 codegen 模块里的 Rule 消费这个标签，生成interface.generated.cpp并自动打上cpp标签，随后进入正常的编译链路。整个过程不需要你手动告诉构建系统“先跑 codegen 再编译”，Qbs 靠标签自动完成顺序推导。

这个例子里有两个值得注意的“为什么”。第一，为什么用inputs: ["myidl"]而不是直接列文件名？因为 Rule 只关心“哪些输入文件打了这个标签”，这样任何模块都可以给文件打上myidl标签，自动被处理，扩展性极好。第二，为什么要在prepare里通过product.codegen.generatorPath取属性？因为同一个 Product 可能同时依赖多个模块，Qbs 通过product.模块名.属性名来访问具体模块实例的属性，避免命名冲突。这个模式是 Qbs 里集成外部工具的标准姿势，比在 CMake 里到处add_custom_command可读性和复用性高太多。

2.3 Product 依赖与参数传递的三种姿势

Product 之间的依赖管理是每个构建系统都绕不开的细节。Qbs 里最朴素的写法是：

CppApplication { name: "demoApp" files: ["main.cpp"] Depends { name: "demoCore" } }

这样写之后，Qbs 会自动把demoCore的头文件路径和链接参数带入demoApp，前提是demoCore正确导出了这些信息。如果demoCore是一个动态库，希望下游使用者自动带上它的头文件目录，比较稳妥的做法是在库的 Product 里加一个Export块：

DynamicLibrary { name: "demoCore" files: ["core.cpp", "core.h"] cpp.defines: ["DEMO_CORE_LIBRARY"] Export { Depends { name: "cpp" } cpp.includePaths: [path] } }

Export的作用就是“当我被别的 Product 依赖时，我默认提供哪些模块属性”。这里的path指向当前.qbs文件所在目录，也就是core.h所在的目录。这下下游产品只要Depends { name: "demoCore" }，什么都不用额外配置，就能正确 include 和链接。这是 Qbs 对比 CMake 的 target usage requirements 更简洁的地方——没有那么多INTERFACE_INCLUDE_DIRECTORIES要手工拼。

除开这种隐式传递，Qbs 还支持在Depends里显式覆盖属性，比如：

Depends { name: "demoCore" cpp.defines: ["USE_DEMO_CORE_NEW_API"] }

这种方式适合临时性的参数覆盖，但我不建议到处用。依赖方向越是显式，工程越容易维护。如果你想把一组公共配置从顶层传下去，更推荐在Project里定义自己的 property，比如：

Project { property string globalVersion: "1.4.0" property bool enableTests: true references: [ "src/lib/lib.qbs", "src/app/app.qbs", "tests/tests.qbs" ] }

然后在子 Product 里用project.globalVersion读取。用自定义 property 传递工程级信息，语义会比塞进cpp.defines里更清晰，也避免了一处改动导致多个模块隐式重编。

3. 把构建速度榨干：增量构建、并行调度与缓存技巧

3.1 并行度不是越大越好

Qbs 默认会根据 CPU 核心数开启并行构建，所以很多时候你什么都不用做就觉得“还挺快”。但在真实的大型工程里，无脑开满并行是会导致构建崩溃的。原因很简单：编译器和链接器的内存占用不在一个量级。

我实际观察过，一台 32 核机器上同时跑 30 个编译任务，内存峰值可能冲到 40GB 以上，如果每个任务还开了 LTO，翻倍也不奇怪。更麻烦的是链接阶段，一个大动态库的链接内存占用往往相当于十几个编译任务的总和。Qbs 的并行调度会尽量让规则交错执行，但极端情况下仍然会撞上内存墙。

我常用的控制方式是构建时显式限制任务数：

qbs build -j 8

这个数字怎么定？我一般按“总内存 / 单个编译任务平均内存”来算，再留出 20% 余量。经验值：16GB 内存的笔记本开-j 6比较稳，32GB 的台式机可以开到-j 12。如果你用 Ninja 风格的最小重建，可以更激进一点，但没必要。

另外一个容易被忽略的瓶颈是终端输出。Qbs 默认会打日志，当几千个文件同时编译时，日志写入本身会占不少 I/O。真正追问题的时候再开全量日志，平时我用-q静默输出，只在出错时查看局部上下文：

qbs build -q -j 8

3.2 增量构建为什么会“莫名失效”

Qbs 的增量构建依赖构建图持久化。构建图保存在build目录里，理论上只要源码没有变化，第二次构建就是在几秒内完成“检查并跳过”。但在实际使用中，很多人会遇到“明明没改东西，一编译就是一大片重来”的诡异现象。我梳理过几类常见原因。

第一类是时间戳倒挂。你在跨平台共享目录或者网络文件系统上工作，文件修改时间精度不够，或者编译产物比源码时间戳“更新”，Qbs 在比较时会误判产物已过期。这类问题最典型的特征是：本地复现不出来，只在挂载目录上出现。解决方案很朴素，把构建目录放到本地磁盘上，而不是项目目录所在的网络盘。

第二类是依赖扫描范围失控。Qbs 的 Scanner 会读取源码里的#include，如果你给了过宽的 include 路径，扫描器会去检查大量无关目录，导致任意一个无关文件变动都可能触发重编译。优化思路是收紧 include 路径，不要让cpp.includePaths包含整个/usr/include或项目根目录。把 include 路径精确到具体子目录，扫描范围小很多，增量判断也准确很多。

第三类是构建图损坏需要重置。Qbs 升级大版本之后，旧版构建图不一定兼容，可能出现“无论怎么增量都全量重编”的情况。处理方式不复杂但很实用：

qbs clean -f qbs build

我知道有些人对clean有心理阴影，觉得会丢失什么。Qbs 里clean只是清理构建产物和构建图，不会碰源码。真到了构建状态不可信的时候，越早 clean 越省时间。硬顶着不 clean，反复用奇怪参数去“修复”，反而浪费更多。

3.3 多配置、多目录与构建产物隔离

Qbs 对多配置的支持是我最欣赏的部分之一。你不需要像 CMake 那样为 Debug 和 Release 各建一套目录，再反复切换。Qbs 可以直接在构建目录中区分不同配置：

qbs build -d build/debug profile:myprofile config:debug qbs build -d build/release profile:myprofile config:release

这里-d指定了不同的构建目录，两个配置可以同时长期存在，互不干扰。Qbs 还会在 build 目录内部按 Profile 和 configuration 进一步划分子目录，所以即便你切换 Profile，也不会发生两个环境共用同一份产物的问题。

在多配置场景下，我强烈建议给每个配置一个明确的名字，可以在工程顶层定义一个 configuration 属性，然后在 Product 里用它做条件编译。比如：

Properties { condition: qbs.buildVariant === "debug" cpp.defines: ["DEBUG_BUILD"] }

这样一条命令构建出来的产物，宏定义、优化级别、符号表信息都自动匹配对应配置，不需要手工维护多个 CMake 变量开关矩阵。构建产物隔离做好了，Debug 和 Release 并行验证、并行提交 CI 都可以很放心。

4. 可抄作业的工程：跨平台库+应用+测试的 Qbs 配置

4.1 顶层 Project 与模块拆分

纸上谈兵没意思，直接给一个我在真实项目里反复使用的工程骨架。假设你要维护一个跨平台的客户端项目，包含一个核心库、一个主程序、一组单元测试，目录结构最好这样组织：

DemoSuite/ ├── demo.qbs ├── src/ │ ├── core/ │ │ ├── core.qbs │ │ ├── core.cpp │ │ └── core.h │ └── app/ │ ├── app.qbs │ └── main.cpp └── tests/ ├── tests.qbs └── test_main.cpp

顶层demo.qbs只需要做两件事：声明全局 property 和引用子工程：

Project { name: "DemoSuite" property string version: "1.4.0" references: [ "src/core/core.qbs", "src/app/app.qbs", "tests/tests.qbs" ] }

references会把子文件里的 Product 全部并进同一个构建图。这样无论从顶层构建还是从 IDE 打开工程，都能看到所有目标和依赖关系。这里有一个经验：不要把每个子模块的 Product 都写在顶层一个文件里。文件一多，合并冲突是小事，更大的问题是 IDE 的代码模型会变得很慢，因为每次编辑一个文件，都要重新解析整棵工程。拆分成多个.qbs文件之后，Qbs 可以做更细粒度的缓存。

src/core/core.qbs这里是核心库：

DynamicLibrary { name: "demoCore" files: ["core.cpp", "core.h"] cpp.defines: ["DEMO_CORE_LIBRARY"] Export { Depends { name: "cpp" } cpp.includePaths: [path] } }

src/app/app.qbs是主程序，依赖核心库：

CppApplication { name: "demoApp" files: ["main.cpp"] Depends { name: "demoCore" } }

tests/tests.qbs是测试程序，同样依赖核心库：

CppApplication { name: "demoTests" files: ["test_main.cpp"] Depends { name: "demoCore" } cpp.defines: ["UNIT_TEST"] }

这个骨架看起来简单，但已经覆盖了 Qbs 最核心的日常用法：多模块拆分、库导出头文件路径、应用依赖库、测试作为独立目标。在此基础上扩展任何业务模块，都只是在references里加一行的事。

4.2 条件化配置：一套代码，多种目标

跨平台项目里，最常见的需求就是“同一个源码目录，在不同平台编译不同的文件、启用不同的宏”。Qbs 的Properties块和condition是干这个事的首选。我习惯把所有平台相关差异集中放在 Product 开头，一眼就能看到：

CppApplication { name: "demoApp" files: [ "main.cpp" ] Properties { condition: qbs.targetOS.contains("windows") cpp.windowsCompiler: "msvc" cpp.defines: ["WIN32_LEAN_AND_MEAN"] } Properties { condition: qbs.targetOS.contains("linux") cpp.cxxFlags: ["-fvisibility=hidden"] } }

qbs.targetOS是 Qbs 内置的上下文变量，除此之外还有qbs.architecture、qbs.buildVariant、qbs.toolchain。比如你要区分 x86_64 和 ARM 的编译参数：

Properties { condition: qbs.architecture === "arm64" cpp.cxxFlags: ["-march=armv8.2-a+fp16"] }

这种写法比 CMake 的if(WIN32)块嵌套更直白，因为每个Properties块都是独立的声明，不需要维护if/elseif/endif的配对关系。在真实项目里，我还会把平台差异收敛到一个统一的共享模块里，比如写一个platformConfig模块，内部集中处理各种平台的宏、警告、链接选项，业务 Product 只需要Depends { name: "platformConfig" }。这比在每个 Product 里散落一堆Properties更容易维护，也符合“知识收口”的思路。

4.3 自定义 Rule 集成外部代码生成工具

回到前面自定义 Module 的例子，如果你暂时不想把规则封装成模块，也可以直接在 Product 里用 Rule 集成外部工具。这适合一次性、项目特定的代码生成场景。比如我用过一个简易 IDL 工具，输入.myproto文件，输出.myproto.generated.cpp，配置写法如下：

Product { name: "codegenTarget" type: "application" files: ["main.cpp", "service.myproto"] FileTagger { patterns: ["*.myproto"] fileTags: ["myproto"] } Rule { inputs: ["myproto"] Artifact { filePath: input.baseName + ".generated.cpp" fileTags: ["cpp"] } prepare: { var cmd = new Command("/opt/tools/myproto-gen", [input.filePath, output.filePath]); cmd.description = "generate " + output.fileName; return [cmd]; } } }

这里要注意filePath的写法和普通字符串拼接不太一样：它依赖input.baseName，这个属性是在构建图生成阶段就确定的。如果工具还产生头文件，你可以再加一个Artifact块，给生成的头文件打上hpp标签，这样其他源码中的 include 也能被正确扫描到：

Artifact { filePath: input.baseName + ".generated.h" fileTags: ["hpp"] }

集成代码生成工具时，我最大的体会是：先让工具在命令行手动跑通，再写 Qbs 规则。如果你连手动执行都还带路径参数问题，写成 Rule 只会更难调。Rule 里的prepare函数本质上就是拼命令行，所以一定保证参数顺序和手动执行时一致。

5. 踩坑实录：Qbs 排错的完整思路

5.1 resolve 阶段：大部分问题都发生在依赖图建立之前

Qbs 的构建流程可以粗分为两个阶段：resolve（解析工程描述、生成构建图）和build（执行构建图中的操作）。很多人只看得到build报错，忽略了前面还藏着一个 resolve 步骤。很多“莫名其妙找不到头文件”“模块属性未定义”“循环依赖冲突”，其实都是在 resolve 阶段就炸了。

我排错的第一步永远是先看完整解析日志：

qbs resolve --log-level debug

如果解析过程中某个 Profile 不存在，Qbs 会明确告诉你profile "arm64" not found，那问题就变成了“为什么没有这个 Profile”，而不是“为什么编译不过”。还有一种很常见的情况：你在工程文件里引用了一个不存在的模块，比如手抖把Depends { name: "cpp" }写成了Depends { name: "cpx" }。resolve 会立刻报错，但如果你只看 build 阶段日志，可能会得到一堆莫名其妙的编译错误，定位方向完全跑偏。

所以我的习惯是：任何异常，先跑qbs resolve，通过之后再考虑 build 的问题。这个习惯帮我省下的时间，远比想象中多——尤其是在团队协作出现“我这能编，你那不能编”的情况时，resolve 日志能快速告诉你是不是有人忘配 Profile，而不是你们的代码本身有问题。

5.2 构建阶段的诡异问题：配置漂移与依赖扫描失效

如果 resolve 顺利，build 却编译出错误，最常见的是以下几类，我列个排查表：

这里最让我头疼的是“配置漂移”。比如同事在本地用qbs config profiles.myprofile.cpp.cxxFlags: ...加了一组参数，然后忘了同步进版本库，CI 上的构建结果自然和他本地不一致。这类问题排起来很容易陷入“代码一模一样，为什么产物不一样”的困惑。我的应对方式是：把 Profile 配置固化成脚本文件，并且用qbs config --list定期检查实际生效的配置。千万不能让关键编译参数只存在于某个人的本地命令行历史里。

另一个老生常谈但值得反复强调的是依赖扫描失效。Qbs 虽然内置了 Scanner，但它只能扫描到它能看到的 include 路径。如果你把生成的头文件放在某个不包含在cpp.includePaths的目录里，Qbs 可能不知道这个头文件变化会影响哪些编译单元。对应做法是：所有生成头文件显式加入扫描路径，或者把生成目录加入 includePaths。不要指望 Qbs 有“读心术”——它读不了你没告诉它的路径。

5.3 与 IDE、CI 配合的现实问题

Qbs 在 IDE 集成上的体验，比命令行要复杂一些。我用的方式是让 IDE 直接打开顶层.qbs文件，它会自动解析并生成代码模型。第一次打开会比较慢，因为要跑一次完整的 resolve，之后只要工程文件没大变，增量解析都很快。这里有一个优化技巧：把顶层Project的references按目录拆细，而不是塞进一个巨大文件。文件越大，解析越慢，IDE 卡顿的概率也越高。

和 CI 配合时，最大的坑是构建目录的并行锁冲突。Qbs 会在构建目录里放一个锁，多个 Qbs 实例同时操作同一个 build 目录会互相等待甚至直接报锁错误。我踩过这个坑：本地开着 Qt Creator 一直在后台解析同一个工程，CI 脚本又对这个目录执行qbs build，结果 CI 任务一直卡住。解决方式是 CI 使用独立的构建目录，不要和人手动的 build 目录混用：

qbs build -d build/ci profile:ci profile

另外，Qbs 版本升级之后，旧构建图不一定兼容。团队里只要有人升级了 Qbs，就会在提交时顺手把上次的构建目录清掉，否则别人拉下来会发现增量构建行为不一致。我的习惯是把 Qbs 版本也视作依赖的一部分——在 CI 环境固定版本，开发机统一版本，减少不可复现的构建问题。

还有一个容易被忽略的点：CI 机器没有图形环境，qbs setup-toolchains --detect可能在自动模式下会误判。建议在 CI 的初始化脚本里手动指定工具链，不要完全依赖自动检测。自动检测对日常开发够用，但在干净环境里，越小众的工具链越容易翻车。

最后再分享一点个人体会

Qbs 并不是万能的。如果你要在一个以第三方 CMake 工程为主的工作流里强行引入 Qbs，那大概率是给自己找不痛快。但如果是你自己控制的代码库，Qbs 的声明式构建模型会带来一种很舒服的体验：构建描述像一株规则清晰的分形树，而不是一团打满补丁的脚本。别急着拿它推翻现有体系，可以先挑一个独立的工具库或新模块试验几周，感受一下“改头文件其余自动跟进”的增量构建到底有多省心。等团队习惯了这种构建方式，再逐步扩大范围，你会发现很多以前花在构建配置上的加班时间，都能省下来去写业务了。