企业官网建设流程全解析

装库这件事，最让人上火的时刻往往不是编译报错，而是配置阶段那一行find_package。你明明已经用包管理器把库装好了，pkg-config也能查到版本号，可 CMake 一跑就甩给你一句Could NOT find Foo。更离谱的是，同一份 CMakeLists.txt，在同事的机器上一切正常，换到你的 Ubuntu 上就翻车——这时候你才会意识到，find_package不是一个简单的"查找文件"函数，它背后有一整套搜索约定、两套完全不同的运行模式，以及一堆默认值埋着的坑。

这篇内容就是围绕find_package这个指令本身展开的。它适合三类人：刚接触 CMake、被find_package的各种_DIR、_ROOT、CMAKE_PREFIX_PATH搞晕的新手；正在把老工程从 Makefile、Keil 工程迁移到 CMake、需要处理第三方依赖的工程师；以及需要给自家库写Config文件、让别人能顺利find_package到自己的库作者。我会从指令的本质讲起，一路讲到 Module 模式和 Config 模式的内部结构、版本匹配规则、跨平台差异，最后给出一套可以直接照着做的排查链路。

1. find_package 不是下载器，它只在两个地方做选择

先把最容易误解的一点说清楚：find_package从来不会帮你下载、安装任何东西。它只做一件事——在磁盘上已经存在的路径里，找到某个库的"描述文件"，然后把这个库的头文件路径、库文件路径、编译选项、传递依赖，打包成 CMake 能理解的形式交给你。找不到就是找不到，它没有能力自己解决问题。

1.1 一个几乎人人都会遇到的报错现场

假设你在一台 Ubuntu 机器上，用系统包管理器装了一个数学计算库 MyMath，头文件在/usr/local/include/mymath.h，库文件在/usr/local/lib/libmymath.so。然后你写了这样一份 CMakeLists.txt：

cmake_minimum_required(VERSION 3.16) project(demo CXX) find_package(MyMath REQUIRED) add_executable(demo main.cpp) target_link_libraries(demo PRIVATE MyMath::MyMath)

配置阶段直接失败，报错大意是Could NOT find MyMath (missing: MyMath_DIR)。这个报错里有两个关键信息：第一，它没找到 MyMath 的描述文件；第二，它明确告诉你它缺的是MyMath_DIR，而不是libmymath.so。很多人第一反应是去改CMAKE_INCLUDE_PATH和CMAKE_LIBRARY_PATH，改完发现毫无作用——因为你把 Config 模式当成了 Module 模式来治。

这两种模式的差别，是所有find_package问题的分水岭。CMAKE_INCLUDE_PATH、CMAKE_LIBRARY_PATH只对 Module 模式里的find_path、find_library有帮助；而 Config 模式压根不看这两个变量，它要的是一个"目录"，目录里躺着MyMathConfig.cmake这样的文件。

1.2 Module 模式与 Config 模式，各管什么地盘

Module 模式的流程是这样的：find_package(Foo)触发 CMake 去CMAKE_MODULE_PATH和 CMake 自带的Modules目录里找一个名叫FindFoo.cmake的脚本，然后执行这个脚本。脚本里通常是一串find_path、find_library、find_program，通过暴力搜索各种常见路径，凑出一组变量（比如FOO_INCLUDE_DIRS、FOO_LIBRARIES），最后用find_package_handle_standard_args统一设置Foo_FOUND。

Config 模式完全不同。它不执行你写的脚本，而是去找库在安装时自己生成的一份文件，常见命名是FooConfig.cmake或foo-config.cmake。这份文件由库的构建系统在install阶段生成，里面记录了这个库的真实路径、版本号、编译开关、以及它依赖的其他库。因为信息来自库作者，所以精度通常远高于通用的 Find 脚本。

默认行为是"先 Module 后 Config"（可通过CMAKE_FIND_PACKAGE_PREFER_CONFIG变量翻转，CMake 3.15 起可用）。也就是说，find_package(MyMath)会先去找FindMyMath.cmake，找不到再切到 Config 模式。这也是为什么有些库明明装了，却因为 CMake 自带一个写得不太好的 Find 脚本，反而拿到了错误的路径——CMake 优先用了那个脚本，压根没去读库自己的 Config 文件。

1.3 搜索顺序决定了你改哪个变量才有效

Config 模式的搜索顺序大致是这样，越靠前优先级越高：

1. 命令行或缓存变量Foo_DIR，直接指向包含配置文件的目录
2. Foo_ROOT（CMake 3.12 起），指定一个安装根目录
3. CMAKE_PREFIX_PATH列表中的每个前缀
4. CMAKE_FRAMEWORK_PATH、CMAKE_APPBUNDLE_PATH
5. 环境变量PATH中的目录（在 Windows 上还会去查注册表）
6. 系统默认前缀，例如/usr/local、/usr、/opt，以及 CMake 自己的安装目录

在每个前缀下面，CMake 会拼出一大堆后缀去尝试，比如<prefix>/、<prefix>/cmake/、<prefix>/lib/cmake/Foo/、<prefix>/share/Foo/cmake/、<prefix>/lib/x86_64-linux-gnu/cmake/Foo/等等。同时它还会对包名做大小写变形尝试，因为有些库习惯装成fooConfig.cmake而不是FooConfig.cmake。

我踩过的一个典型坑：库装在了/opt/mymath下，配置文件在/opt/mymath/lib/cmake/MyMath/MyMathConfig.cmake，我以为把CMAKE_PREFIX_PATH设成/opt/mymath/lib就行，结果失败。正确做法是设成安装根目录/opt/mymath，让 CMake 自己去拼后面的lib/cmake/MyMath这一段。前缀是"根"，不是"配置文件所在目录"——这个区别看起来小，但很多人就是在这里反复试错。

2. Module 模式：FindFoo.cmake 里究竟该写什么

理解了模式划分，接下来聊聊自己写 Find 脚本。这件事在两种场景下必须做：一是目标库没有提供 Config 文件，二是你要找的东西不是标准库（比如某个只有可执行文件的工具）。官方Modules目录下的脚本虽然多，但覆盖面有限，遇到私有库只能自己动手。

2.1 手写一个 FindMyMath.cmake 的完整过程

一个合格的 Find 脚本，核心就是"用最少的假设，把路径找出来，并且提供现代 CMake 的导入目标"。下面这份是可以直接抄的结构：

# FindMyMath.cmake find_path(MyMath_INCLUDE_DIR NAMES mymath.h HINTS ${MyMath_ROOT} ENV MyMath_ROOT PATH_SUFFIXES include ) find_library(MyMath_LIBRARY NAMES mymath libmymath HINTS ${MyMath_ROOT} ENV MyMath_ROOT PATH_SUFFIXES lib lib64 ) include(FindPackageHandleStandardArgs) find_package_handle_standard_args(MyMath REQUIRED_VARS MyMath_LIBRARY MyMath_INCLUDE_DIR VERSION_VAR MyMath_VERSION ) if(MyMath_FOUND AND NOT TARGET MyMath::MyMath) add_library(MyMath::MyMath UNKNOWN IMPORTED) set_target_properties(MyMath::MyMath PROPERTIES IMPORTED_LOCATION "${MyMath_LIBRARY}" INTERFACE_INCLUDE_DIRECTORIES "${MyMath_INCLUDE_DIR}" ) endif() mark_as_advanced(MyMath_INCLUDE_DIR MyMath_LIBRARY)

这里有几个细节值得单独说。HINTS ${MyMath_ROOT} ENV MyMath_ROOT的意思是：如果用户设置了MyMath_ROOT变量或同名环境变量，优先从这里找，但找不到也不会报错，会继续走系统默认路径。这是"可覆盖但不强制"的设计，比直接写死路径友好得多。

find_package_handle_standard_args的第一个参数决定了最终变量名。如果你写MyMath，它设置的是MyMath_FOUND；如果写MYMATH，设置的就是MYMATH_FOUND。这一点在跨脚本调用时特别容易出问题——上游脚本用if(MYMATH_FOUND)判断，你这边设成了MyMath_FOUND，条件永远为假，然后你会看到"库明明找到了，链接却失败"的诡异现象。

2.2 导入目标与老式变量，选哪个

老式写法是暴露MyMath_INCLUDE_DIRS和MyMath_LIBRARIES两个变量，调用方这么用：

find_package(MyMath REQUIRED) include_directories(${MyMath_INCLUDE_DIRS}) target_link_libraries(demo PRIVATE ${MyMath_LIBRARIES})

这种写法能用，但问题很多。include_directories是目录级作用域，会污染当前目录下所有目标；${MyMath_LIBRARIES}只能传递库文件本身，传递不了编译定义、C++ 标准要求、以及这个库自己依赖的其他库。一旦 MyMath 依赖 pthread，调用方还得自己再加一个Threads::Threads。

现代写法是提供IMPORTED目标，也就是上面的MyMath::MyMath。它的好处是全都自动带上：包含目录、编译定义、传递依赖、链接时的顺序约束。写完target_link_libraries(demo PRIVATE MyMath::MyMath)就结束了，不需要再手动include_directories。

建议：新写的 Find 脚本一律同时提供导入目标。变量可以保留作为兼容层，但主体逻辑走导入目标，后续维护成本会低很多。

写导入目标时最容易出错的属性是IMPORTED_LOCATION。对于动态库和静态库，它填的是.so、.a、.dll、.dylib的完整路径。如果你想区分 Debug 和 Release，需要改用IMPORTED_LOCATION_DEBUG和IMPORTED_LOCATION_RELEASE，否则在单配置生成器（比如 Visual Studio）下会拿到同一个路径，调试版本链接到 Release 库，行为可能和你预期不同。

2.3 REQUIRED、QUIET、COMPONENTS 三个开关的真实语义

这三个参数看起来简单，组合起来行为差异不小。

REQUIRED的含义是"找不到就报错，直接终止配置"。它会把原本的NOTFOUND变成SEND_ERROR级别的消息。但要注意，在 Module 模式下，REQUIRED并不能强制find_package_handle_standard_args忽略缺失项——真正决定是否报错的是那个函数收到的REQUIRED_VARS列表。如果你的脚本里REQUIRED_VARS写漏了一个关键变量，即使调用方写了REQUIRED，也可能出现"报错说找到了，实际用的时候路径是空的"。

QUIET是抑制输出，把找到/没找到的信息降级。它和REQUIRED可以同时使用：找不到依然报错，但找到时不打印任何东西。REQUIRED和QUIET同时关闭时，默认行为是"找到了打印一行简要信息，没找到也打印但不报错"。

COMPONENTS指定需要的组件，比如find_package(Qt6 COMPONENTS Core Widgets REQUIRED)。在 Config 模式下，处理组件是配置文件自己的责任，通常通过check_required_components宏实现；在 Module 模式下，则由脚本作者自己解析Foo_FIND_COMPONENTS变量来决定找哪些子模块。两者的行为并不统一，所以看到某个库的组件检查"不生效"时，先去翻它的配置文件或 Find 脚本，而不是怀疑 CMake 本身。

3. Config 模式：库作者留下的接头暗号

Config 模式的信息精度高，但前提是你得知道它在找什么文件、文件里长什么样。理解了文件结构，排查速度能快一个数量级。

3.1 三种典型失败现场与对应特征

第一种是missing: Foo_DIR。这是最明确的信号：CMake 连一个名为FooConfig.cmake或foo-config.cmake的文件都没扫到。常见原因是库装在了非标准前缀下，或者包名大小写不一致。

第二种是找到了文件，但报Foo_FOUND为假，或者报组件缺失。这时候文件是被读到了，问题出在文件内部逻辑，比如它内部调用了find_dependency(SomeOtherLib)而这个依赖没找到。这类报错通常会在上面一行显示真正的缺失项。

第三种最隐蔽：配置完全成功，链接时才报undefined reference。原因往往是导入的IMPORTED_LOCATION指向的库架构不对，或者你安装的是只有头文件的部分，真正的实现库没装上。

3.2 FooConfig.cmake 里到底写了什么

库的安装导出的配置文件，结构通常长这样：

# MyMathConfig.cmake include(CMakeFindDependencyMacro) find_dependency(Threads) include("${CMAKE_CURRENT_LIST_DIR}/MyMathTargets.cmake") set(MyMath_VERSION 1.4.2) check_required_components(MyMath)

第一行的find_dependency是关键。它的作用和find_package一样，但多了两个特性：一是会把找不到时的处理交给调用方（如果配置失败会正确传播），二是会自动加上QUIET和REQUIRED的折射，避免重复打印。很多"配置文件找到了但依然失败"的情况，根因就是这一行里的依赖在你的环境里没装。

MyMathTargets.cmake是真正定义IMPORTED目标的地方，一般由install(EXPORT ...)自动生成，里面是一大堆add_library(MyMath::MyMath SHARED IMPORTED)和对应的属性设置。这个文件不要手改，改了下次重新安装就没了。

版本文件MyMathConfigVersion.cmake是配套的，内容大致是这样：

set(PACKAGE_VERSION "1.4.2") if(PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION) set(PACKAGE_VERSION_COMPATIBLE FALSE) else() set(PACKAGE_VERSION_COMPATIBLE TRUE) if(PACKAGE_FIND_VERSION STREQUAL PACKAGE_VERSION) set(PACKAGE_VERSION_EXACT TRUE) endif() endif()

它做的事就是回答两个问题："这个版本够不够新"和"是不是完全相等"。find_package(MyMath 1.2)时，CMake 会设定PACKAGE_FIND_VERSION，然后执行这个脚本，根据它设置的两个布尔值决定接受还是拒绝。

3.3 用 HINTS、PATHS、Foo_DIR 精准指路

排查阶段最有效的办法是先用命令行变量直接怼进去，验证"只要指对目录就能工作"，然后再回头处理搜索路径的问题。

# 直接指定配置文件所在目录 cmake -S . -B build -DMyMath_DIR=/opt/mymath/lib/cmake/MyMath # 或者指定安装根目录 cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/mymath # 多个前缀用分号隔开 cmake -S . -B build -DCMAKE_PREFIX_PATH="/opt/mymath;/opt/other"

Foo_DIR和CMAKE_PREFIX_PATH的区别要记住：前者必须精确到包含配置文件的目录，后者只需要给到安装根目录。临时调试用Foo_DIR最快，长期方案应该写进工具链文件或项目文档里用CMAKE_PREFIX_PATH。

在脚本内部，find_package的HINTS和PATHS也可以加搜索位置，区别是HINTS会被CMAKE_FIND_USE_*系列开关影响，而PATHS默认是硬搜索但优先级最低（在NO_DEFAULT_PATH关闭时，系统路径依然会被查找）。HINTS更适合写"猜测性位置"，PATHS适合写"确定的额外位置"。

4. 版本匹配、组件与导入目标的三个翻车点

把库找到了只是第一步，接下来这三处细节处理不好，照样会出问题，而且往往出在编译链接的后期，排查成本更高。

4.1 版本号比较用的是"组件式"规则

find_package(Foo 1.4.2)中的版本号会被拆成组件逐个比较，而不是当作字符串。比较规则由 Config 版本文件里的逻辑决定，常见策略有以下几种：

AnyNewerVersion是默认值，这解释了为什么很多库你写了find_package(Foo 1.0)，结果它接受了 3.x 版本——如果你的代码依赖的是 1.x 的旧 API，这种"太新"的版本反而会带来编译错误。这种情况下必须显式写find_package(Foo 1.0 EXACT)，或者让库作者把策略改成SameMajorVersion。

还有一个细节是版本范围。CMake 3.19 起支持find_package(Foo 1.2...1.6)这种写法，意思是接受 1.2 到 1.6 之间的版本。这在处理多环境构建时很有用，比写死一个版本更灵活。

4.2 COMPONENTS 的实现责任在库那边

find_package(Foo COMPONENTS a b REQUIRED)的语义是"我要 a 和 b 这两个组件，缺一个就失败"。但 CMake 本身并不检查这些组件是否存在，它只是把列表放到Foo_FIND_COMPONENTS变量里，由配置文件或 Find 脚本自己处理。

Config 文件结尾那句check_required_components(Foo)就是干这个的。这个宏会遍历Foo_FIND_COMPONENTS，检查Foo_<component>_FOUND变量，如果有任何一个为假，就把Foo_FOUND置为假，并在REQUIRED的情况下报错。

所以当你写COMPONENTS却发现组件缺失没有任何报错时，八成是配置文件里漏了check_required_components。反之，如果某个可选组件没装却导致了整体失败，检查一下是不是多写了REQUIRED，或者配置文件的组件判断逻辑写得太严格。

提示：查组件是否真的被检查，可以在配置后打印Foo_FOUND和各个Foo_<component>_FOUND变量，一眼就能看出哪个环节没生效。

4.3 Debug 与 Release、动态与静态的导入差异

单配置生成器（Unix Makefiles、Ninja）下，CMAKE_BUILD_TYPE决定用哪套导入位置；多配置生成器（Visual Studio、Xcode）下，构建时可以选择配置，所以需要同时提供IMPORTED_LOCATION_DEBUG和IMPORTED_LOCATION_RELEASE。如果只有IMPORTED_LOCATION，在多配置环境下所有配置都会指向同一个文件。

动态库和静态库的处理也不一样。静态库在链接时需要把传递依赖也一起带上，这正是INTERFACE_LINK_LIBRARIES的用途。如果库作者忘了设这个属性，你会看到静态链接时报一堆符号未定义，然后在网上搜半天"为什么 find_package 找到了还是链接失败"。

我自己遇到过一个特别典型的例子：某个库同时装出了.a和.so，find_library默认优先选.so，但我为了静态发布强行加了CMAKE_FIND_LIBRARY_SUFFIXES调整，结果某些模块还是链到了动态库，最终产物混着两种链接方式，运行时报错。解决办法是明确用导入目标而不是自己找库文件路径，让库自己决定用哪个。

5. 跨平台和交叉编译场景下的路径差异

同一份 CMakeLists.txt 在 Ubuntu 上跑通，换到 Windows 上失败，是很常见的情况。原因几乎都能归到搜索路径的默认值差异上。

5.1 Ubuntu 与 Windows 上默认搜索的差别

Ubuntu 上，系统默认前缀包括/usr/local、/usr、/opt，包管理器安装的库大多落在/usr/lib/x86_64-linux-gnu/cmake/这类位置，Config 模式的默认后缀组合能覆盖到。所以"用系统包管理器装完就能 find_package 到"在 Linux 上成立的概率比较高。

Windows 上没有这种约定。库通常被解压到C:\libs\foo-1.2.3这样的目录，或者通过某个包管理器放到用户目录下。此时必须显式设置CMAKE_PREFIX_PATH，或者配置环境变量。路径分隔符方面，CMake 统一用正斜杠/最稳妥，反斜杠在字符串里会被当转义符，写C:\libs常常变成C:libs。

还有一个容易忽略的点：Windows 上包名大小写敏感度低，但 CMake 的配置文件查找是按名字做变形尝试的。如果库导出的是fooConfig.cmake，而你写的是find_package(Foo)，CMake 会尝试Foo、foo、FOO等变形，通常能命中，但有时会因为目录名不符合预期而失败。遇到这种情况，直接把Foo_DIR指过去验证一下，能省很多时间。

# Windows 上更稳妥的写法：在 CMakeLists.txt 顶部集中管理 list(APPEND CMAKE_PREFIX_PATH "C:/libs/mymath-1.4.2") list(APPEND CMAKE_PREFIX_PATH "$ENV{USERPROFILE}/scoop/apps")

5.2 交叉编译时要把搜索根目录锁死

交叉编译的核心问题是：CMake 默认会去宿主机的/usr、/usr/local找库，结果找到的是给宿主机编译的版本，链接时才报架构不匹配。解决办法是在工具链文件里做两件事。

第一，设置CMAKE_FIND_ROOT_PATH为目标系统的 sysroot，并配置查找模式：

set(CMAKE_FIND_ROOT_PATH /opt/sysroot) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

PROGRAM设为NEVER是因为编译工具本身（比如宿主机上的protoc）应该从宿主机找；而LIBRARY、INCLUDE、PACKAGE设为ONLY表示只在 sysroot 里找，避免污染。

第二，把目标平台库的前缀目录加进CMAKE_PREFIX_PATH，而不是靠默认路径。因为默认路径在交叉编译场景下几乎没有意义。

我见过一种更隐蔽的失败：CMAKE_FIND_ROOT_PATH_MODE_PACKAGE没设，导致 Config 模式仍然按宿主机路径查找，找到了宿主机上的同名库，生成的导入目标指向宿主机文件。编译能过，链接能过，烧到板子上就跑不起来。这类问题只能靠严格设置查找模式来避免。

5.3 和包管理器配合时的路径约定

现在很多项目用包管理器来管依赖，安装路径大多有规律，把前缀加进CMAKE_PREFIX_PATH之后，Config 模式通常能自动命中。麻烦的是"同一个库存在多份"的情况：系统装了一份、包管理器装了一份、项目本地又解压了一份。CMake 的搜索是有顺序的，但顺序和你的直觉不一定一致。

一个可靠的实践是：在项目根目录的 CMakeLists.txt 最前面显式把项目自带的依赖目录加到CMAKE_PREFIX_PATH的最前面，并考虑用NO_CMAKE_SYSTEM_PATH之类的选项收紧搜索范围。这样构建结果不会因为某个同事机器上多装了一个库而发生变化，可复现性会高不少。

注意：不要在多个地方重复追加CMAKE_PREFIX_PATH，尤其是同时用set和list(APPEND)。set会覆盖之前的追加，导致顺序和你预期的完全相反。

6. 把 find_package 的排查过程走一遍

前面讲的都是原理，最后这部分说排查。我自己的习惯是固定按一个链路走，从报错信息出发，逐步缩小范围，而不是想到哪个变量就改哪个。

6.1 用 --debug-find 看它到底逛了哪些目录

CMake 提供了一个非常实用的开关，能打印出所有查找过程：

cmake -S . -B build --debug-find 2>&1 | grep -A 30 "find_package"

输出内容大致是这样：

find_package considered the following locations for the Config module: /opt/mymath/lib/cmake/MyMath/MyMathConfig.cmake /usr/local/lib/cmake/MyMath/MyMathConfig.cmake /usr/lib/cmake/MyMath/MyMathConfig.cmake The file was not found.

这份输出的价值在于：它列出了 CMake 实际尝试过的完整路径。你只要对照自己的实际安装位置，就能立刻判断出是"目录前缀不对"还是"文件名不对"。如果输出里连你预期的前缀都没出现，说明CMAKE_PREFIX_PATH没生效；如果前缀出现了但文件名不匹配，那就是包名大小写或命名约定的问题。

除了--debug-find，--debug-find-pkg=Foo可以把输出限定到某个包，日志量小很多，适合依赖众多的项目。在 CMakeLists.txt 里也可以临时打开set(CMAKE_FIND_DEBUG_MODE TRUE)，效果类似。

6.2 CMakeCache.txt 造成的幽灵结果

find_package找到的结果会缓存到CMakeCache.txt里，尤其是Foo_DIR这个变量。这带来一个非常经典的问题：你第一次配置时路径是错的，CMake 把错误的Foo_DIR存进了缓存；之后你修正了环境，重新运行 cmake，它依然用缓存里的旧值，于是你反复怀疑自己改的东西没生效。

判断方法很简单，在构建目录里搜一下：

grep -i "Foo_DIR" build/CMakeCache.txt

如果发现里面存的是一个已经不存在或错误的路径，直接删掉构建目录重新配置是最省事的做法。更精细的方式是在 CMakeLists.txt 里加unset(Foo_DIR CACHE)，或者用cmake -U Foo_DIR -S . -B build从命令行清掉这个缓存项。我一般建议遇到"配置结果和预期完全不符"的情况，先删构建目录再试一次，能排除掉一大半干扰因素。

6.3 一套可以直接复用的排查清单

把前面的内容收敛成一张清单，遇到find_package问题按顺序执行：

1. 看报错原文。是missing: Foo_DIR还是找到了但内部失败，这两类问题的方向完全不同。
2. 确认库是否真的装了，以及安装位置。用find / -name "*Config.cmake" 2>/dev/null | grep -i foo这类命令扫一遍，比猜快得多。
3. 用--debug-find-pkg=Foo看真实搜索路径，和上一步的结果对照。
4. 用-DFoo_DIR=<配置文件目录>手动指定，验证配置文件本身是完好的。
5. 如果Foo_DIR有效但CMAKE_PREFIX_PATH无效，检查前缀层级是否为安装根目录。
6. 如果都无效，确认是不是 Module 模式抢先命中了。此时可以写find_package(Foo CONFIG REQUIRED)强制走 Config 模式。
7. 配置成功但链接失败，检查导入目标的库文件路径、架构和 Debug/Release 属性。
8. 全都对但结果诡异，删掉构建目录重新配置，排除缓存污染。

第 6 条那个CONFIG关键字，是很多人不知道的实用技巧。当你明确知道库提供了 Config 文件，就不应该让 CMake 去试 Module 模式。显式写find_package(Foo CONFIG REQUIRED)或者find_package(Foo MODULE REQUIRED)，能避免"脚本版本和 Config 版本信息不一致"引发的一系列奇怪问题。我在处理依赖多、环境复杂的项目时，几乎会给每个第三方依赖都加上CONFIG，虽然多打了几个字，但把不确定性压到了最低。

顺带说一个和版本号有关的实用操作：如果你已经装了 CMake 但版本偏旧，某些新参数（比如Foo_ROOT、CMAKE_FIND_PACKAGE_PREFER_CONFIG）用不了，又不想动系统自带的版本，常见的做法是单独装一份新版本放在用户目录下，然后在 PATH 里把它排在前面。这种"不动系统、只改个人环境"的方式在多人共用的机器上尤其合适，不会影响到别人的构建流程。至于卸载，包管理器装的用对应包管理器卸载，手动解压的目录直接删掉即可，注意检查一下 PATH 里有没有残留的指向。

最后补一个小技巧，跟前面讲的find_dependency有关。如果你在写自家库的 Config 文件，并且这个库依赖了Threads这类通常在 Module 模式下提供的包，记得在find_dependency之后加一句对导入目标的引用检查，比如if(NOT TARGET Threads::Threads)就提前报错。这比等到用户链接时才蹦出一堆找不到符号的报错要友好得多，也省得对方来问你"为什么库找到了还是编译不过"。