现代 CMake 依赖管理详解：从构建树、Target 封装到 find_package 工作原理

文章目录

- 一、依赖管理的基本概念
- - [1.1 构建树：依赖可见性的边界](#1.1 构建树：依赖可见性的边界)
  - [1.2 库是如何封装成 Target](#1.2 库是如何封装成 Target)
  - - [1.2.1 树内库的封装（`add_subdirectory`）](#1.2.1 树内库的封装（add_subdirectory）)
    - [1.2.2 预编译库的封装（`IMPORTED` Target）](#1.2.2 预编译库的封装（IMPORTED Target）)
  - [1.3 依赖管理方式](#1.3 依赖管理方式)
  - - [1.3.1 `add_subdirectory()`：树内模块的原生集成](#1.3.1 add_subdirectory()：树内模块的原生集成)
    - [1.3.2 `find_package()`：树外预装库的标准对接](#1.3.2 find_package()：树外预装库的标准对接)
    - [1.3.3 `FetchContent`：远程源码的按需拉取](#1.3.3 FetchContent：远程源码的按需拉取)
  - [1.4 如何导入依赖](#1.4 如何导入依赖)
  - - [1.4.1 库的形态决定导入方式](#1.4.1 库的形态决定导入方式)
    - [1.4.2 导入第三方库的标准流水线](#1.4.2 导入第三方库的标准流水线)
- [二、find_package() 的工作原理](#二、find_package() 的工作原理)
- - [2.1 导出 Target：让库支持 `find_package`](#2.1 导出 Target：让库支持 find_package)
  - [2.2 find_package 的查找机制](#2.2 find_package 的查找机制)
  - - [2.2.1 查找模式](#2.2.1 查找模式)
    - [2.2.2 搜索路径的逻辑](#2.2.2 搜索路径的逻辑)
  - [2.3 版本校验与 Imported Target 的创建](#2.3 版本校验与 Imported Target 的创建)
  - [2.4 失败处理与降级](#2.4 失败处理与降级)
- 三、最佳实践
- 参考资料

一、依赖管理的基本概念

CMake 依赖管理的本质只有一句话：把外部库封装成 Target，让它的头文件路径、库文件路径和编译选项沿着构建树自动传播 。只要抓住这一点，就不会再被 target_link_directories() 这类"历史遗留命令"带偏。

1.1 构建树：依赖可见性的边界

CMake 在配置阶段会构建一棵构建树（Build Tree），它直接映射你的源码目录结构。它决定了 target 的可见性边界与依赖传播范围，是理解依赖管理的起点。

树内目标（In-tree targets） ：通过 add_subdirectory() 引入的目录中定义的目标，天然处于同一构建树内。它们可以直接通过 target_link_libraries() 互相引用，且 PUBLIC / INTERFACE 属性会自动沿构建树传播。
树外目标（Out-of-tree targets） ：未通过 add_subdirectory() 加入构建体系的目标（如系统预装库、第三方预编译库），CMake 无法直接感知其属性，必须通过 find_package() 或手动定义 IMPORTED 目标来"桥接"进当前构建树。
临时构建树节点 ：FetchContent 在配置阶段拉取远程源码后，会在构建树中创建临时目录并自动调用 add_subdirectory()，因此拉取的源码会被纳入构建树，但其生命周期与构建目录绑定。

构建树的核心约束是：依赖可见性严格受限于目录层级 。add_subdirectory() 引入的子目录目标，仅对当前目录及其后续子目录可见；跨目录引用必须通过 target_link_libraries() 显式声明，禁止通过全局变量或硬编码路径绕过构建树边界。

用一个简单的项目结构来说明：

复制代码

my_project/
├── CMakeLists.txt
├── app/
│   ├── CMakeLists.txt
│   └── main.cpp
└── libs/
    ├── CMakeLists.txt
    └── utils/
        ├── CMakeLists.txt
        ├── utils.h
        └── utils.cpp

在根目录的 CMakeLists.txt 里写上：

cmake 复制代码

add_subdirectory(libs)
add_subdirectory(app)

那么 libs/utils 里定义的 utils 就成为树内目标。utils 声明的 PUBLIC 头文件路径会自动传递给 app。而像 OpenSSL 这样的树外目标，则必须通过 find_package() 桥接。

1.2 库是如何封装成 Target

要理解怎么导入库，首先要理解库是怎么被封装成 Target 的。无论哪种方式，最终都要能拿到这些信息，否则链接一定出问题：

头文件路径 ：INTERFACE_INCLUDE_DIRECTORIES
库文件路径 ：IMPORTED_LOCATION（静态库 / 动态库本体）
链接依赖 ：该库自身依赖的其他库（如 pthread、dl）
编译选项 ：如宏定义 -DFOO=1、C++ 标准 -std=c++17

现代 CMake 的理想状态是：这些信息已经封装在一个带命名空间的 Target 里，例如 OpenSSL::SSL。你只需要 target_link_libraries(app PRIVATE OpenSSL::SSL)，剩下的事 CMake 全包了。

1.2.1 树内库的封装（`add_subdirectory`）

当库源码就在当前仓库时，作者通过 add_library() 定义 Target，并使用 target_* 系列命令设置属性。

以 libs/utils 为例，其 CMakeLists.txt 如下：

cmake 复制代码

# libs/utils/CMakeLists.txt
add_library(utils utils.cpp)

# 设置头文件路径
target_include_directories(utils
    PUBLIC
        ${CMAKE_CURRENT_SOURCE_DIR}  # 消费者需要这个路径
    PRIVATE
        ${CMAKE_CURRENT_BINARY_DIR}  # 仅内部编译需要
)

# 设置依赖和编译选项
target_link_libraries(utils PUBLIC pthread)
target_compile_features(utils PUBLIC cxx_std_17)

在这个例子里，utils 就是一个标准的树内 Target。当父目录通过 add_subdirectory(libs/utils) 引入它后，app 只需 target_link_libraries(app utils)，前面设置的头文件路径和 pthread 依赖就会自动传递过来。

1.2.2 预编译库的封装（`IMPORTED` Target）

对于闭源库或预编译库，库提供者（或我们自己）需要手动创建 IMPORTED 目标，把"可消费信息"挂载上去。

cmake 复制代码

# 查找库文件和头文件
find_library(MYLIB_LIBRARY NAMES mylib PATHS /opt/mylib/lib)
find_path(MYLIB_INCLUDE_DIR NAMES mylib.h PATHS /opt/mylib/include)

# 创建 IMPORTED 目标（STATIC 或 SHARED）
add_library(mylib::mylib STATIC IMPORTED)

# 挂载属性
set_target_properties(mylib::mylib PROPERTIES
    IMPORTED_LOCATION ${MYLIB_LIBRARY}                 # 库文件路径
    INTERFACE_INCLUDE_DIRECTORIES ${MYLIB_INCLUDE_DIR} # 头文件路径
    INTERFACE_LINK_LIBRARIES "pthread;dl"              # 传递依赖
)

这样封装后，mylib::mylib 就拥有了和树内 Target 完全一致的使用体验。

这种手动封装方式适用于库路径已知且稳定 的场景；如果库路径随机器、平台或使用者变化，则需要借助 find_package() 的查找机制。

1.3 依赖管理方式

依赖管理方式如下所示：

依赖来源	推荐命令	是否进入构建树	版本控制方式
源码同在仓库	`add_subdirectory()`	是	Git Submodule
预装库 / 系统库	`find_package()`	否	系统包管理器
远程源码	`FetchContent`	是（临时）	CMake 声明

1.3.1 `add_subdirectory()`：树内模块的原生集成

这是最"原生"的方式。将子目录的 CMakeLists.txt 直接纳入当前构建树，子目录里的目标就是当前项目的"一等公民"，属性自动传播。唯一要注意的是：子目录会继承父目录的构建选项（比如 BUILD_SHARED_LIBS）。如果你希望子库强制静态编译，记得在 add_subdirectory() 之前显式覆盖：

cmake 复制代码

set(BUILD_SHARED_LIBS OFF)
add_subdirectory(libs/utils)

版本控制方面，通常交给 Git Submodule（推荐 git submodule update --init --recursive）或 Monorepo 的分支 / 标签来锁定。

1.3.2 `find_package()`：树外预装库的标准对接

这是对接系统库的标准姿势。它通过查找 <PackageName>Config.cmake（Config 模式）或 Find<PackageName>.cmake（Module 模式），定位已安装的库并生成 IMPORTED 目标。

cmake 复制代码

find_package(OpenSSL 3.0 REQUIRED)
target_link_libraries(app PRIVATE OpenSSL::SSL OpenSSL::Crypto)

Config 模式由库作者提供，信息最准确；Module 模式则是 CMake 内置或你自写的查找脚本，有可能过时。如果库本身不提供 CMake 支持，find_package() 就会失败，这时需要考虑 FetchContent 或手动封装 IMPORTED 目标。

版本由系统包管理器决定，因此在跨平台一致性要求高的场景下并不理想。

1.3.3 `FetchContent`：远程源码的按需拉取

当你需要统一各个平台的依赖版本时，FetchContent 非常合适。它在在配置阶段（而非构建阶段）从远程（Git/SVN/HTTP）拉取源码，解压到构建目录的 _deps 子目录，并自动调用 add_subdirectory() 将其纳入构建树，因此编译选项和 ABI 都与父项目完全一致。

cmake 复制代码

include(FetchContent)
FetchContent_Declare(
  fmt
  GIT_REPOSITORY https://github.com/fmtlib/fmt.git
  GIT_TAG 10.1.1	# 锁定版本
)
FetchContent_MakeAvailable(fmt) # 自动拉取、添加子目录
target_link_libraries(app PRIVATE fmt::fmt)

通过 FetchContent_Declare() 中的 GIT_TAG（推荐）或 URL_HASH 严格锁定版本，可以保证所有开发者和 CI 环境的一致性。如果频繁配置让你觉得慢，可以设置 FETCHCONTENT_UPDATES_DISCONNECTED 来禁用更新检查。

1.4 如何导入依赖

1.4.1 库的形态决定导入方式

在动手之前，先判断库的"存在形态"，这是选型的前提：

库的存在形式	推荐导入方式
源码就在当前仓库（子目录）	`add_subdirectory()`
系统已安装（如 `/usr/lib`）	`find_package()`
远程 Git / HTTP 源码	`FetchContent`
只有预编译库，无 CMake 支持	`find_library()` + `add_library(... IMPORTED)`

1.4.2 导入第三方库的标准流水线

现代 CMake 的设计哲学是"一切皆目标（Target）"，导入第三方库的本质是将外部依赖封装为可被 target_link_libraries() 消费的 target。在导入第三方库时，建议遵循这条流水线：

首选 find_package()：尽量拿到官方提供的 Imported Target。
找不到就用 FetchContent：拉取源码并参与构建。
极端情况手动封装 IMPORTED 目标 ：仅用于路径已知且稳定 的闭源预编译库，且绝对不要直接写 target_link_libraries(app /opt/mylib/lib/libmylib.a) 或 target_link_directories()。如 1.2.2 节所示，通过 find_library() 和 add_library(... IMPORTED) 手动封装预编译库。

二、find_package() 的工作原理

find_package() 的核心任务只有一件：在指定路径下找到符合版本要求的配置文件，并创建 IMPORTED Target 供你消费。理解这套机制最清晰的方式，是先站在"库作者"的视角看一份依赖如何被封装并导出，再回到"消费者"视角看它如何被发现和复用。

2.1 导出 Target：让库支持 `find_package`

一个库要想被外部项目通过 find_package() 使用，不能只产出 .a / .so 文件，还必须附带一份**"使用说明书"**------即 <PackageName>Config.cmake。这份文件的本质，是把构建树内 Target 的关键属性（头文件路径、库文件路径、依赖项）序列化 到磁盘，以便 CMake 在另一个项目中将其还原为 IMPORTED Target。

下面以 mylib 为例，完整演示一个"可被 find_package 的库"是如何封装的。

(1) 项目结构

复制代码

mylib/
├── CMakeLists.txt
├── include/
│   └── mylib.h
└── src/
    └── mylib.cpp

(2) 编写 CMakeLists.txt

cmake 复制代码

cmake_minimum_required(VERSION 3.14)
project(mylib LANGUAGES CXX)

# 1. 定义库目标
add_library(mylib src/mylib.cpp)

# 关键：区分构建时与安装后的头文件路径
# BUILD_INTERFACE：供当前构建树内的其他目标使用（如 add_subdirectory）
# INSTALL_INTERFACE：供安装后通过 find_package 使用的外部项目
target_include_directories(mylib
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:include>
)

# 2. 安装库文件，并记录导出信息
# EXPORT mylibTargets：将 mylib 的使用说明记录到名为 mylibTargets 的导出集中
install(TARGETS mylib
    EXPORT mylibTargets
    ARCHIVE DESTINATION lib      # 静态库
    LIBRARY DESTINATION lib      # 动态库
    RUNTIME DESTINATION bin      # Windows DLL
)

# 安装头文件
install(DIRECTORY include/
    DESTINATION include
)

# 3. 生成 Config.cmake（核心步骤）
# 将导出集 mylibTargets 序列化为 mylibConfig.cmake
# NAMESPACE mylib::：为导出的 Target 加上命名空间，避免命名冲突
# DESTINATION：安装到 CMake 的标准搜索路径下
install(EXPORT mylibTargets
    FILE mylibConfig.cmake
    NAMESPACE mylib::
    DESTINATION lib/cmake/mylib
)

# 4. 生成版本文件（可选但强烈推荐）
include(CMakePackageConfigHelpers)
write_basic_package_version_file(
    ${CMAKE_CURRENT_BINARY_DIR}/mylibConfigVersion.cmake
    VERSION 1.0.0
    COMPATIBILITY SameMajorVersion
)
install(FILES
    ${CMAKE_CURRENT_BINARY_DIR}/mylibConfigVersion.cmake
    DESTINATION lib/cmake/mylib
)

(3) 构建与安装

bash 复制代码

# 1. 配置
# cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$HOME/.local
cmake -S . -B build


# 2. 编译
cmake --build build

# 3. 安装（需要写权限）
sudo cmake --install build

第三步执行后，CMake 会根据 install() 命令，将文件复制到 ${CMAKE_INSTALL_PREFIX} 指定的路径下。安装完成后，文件系统布局如下（以 Linux 默认前缀 /usr/local 为例）：

复制代码

/usr/local/
├── include/
│   └── mylib.h
├── lib/
│   ├── libmylib.a
│   └── cmake/
│       └── mylib/
│           ├── mylibConfig.cmake          # 由 install(EXPORT) 自动生成
│           └── mylibConfigVersion.cmake  # 由 write_basic_package_version_file 生成

(4) 消费端的使用

至此，mylib 已经具备了被 find_package 发现的全部条件。任何外部项目现在都可以这样使用它：

cmake 复制代码

# 若库不在系统默认路径，需提前扩展搜索范围
# list(APPEND CMAKE_PREFIX_PATH "/opt/deps/mylib")

find_package(mylib 1.0 REQUIRED)
target_link_libraries(app PRIVATE mylib::mylib)

当 find_package(mylib) 执行时，CMake 会在 /usr/local/lib/cmake/mylib 下找到 mylibConfig.cmake。该文件内部会自动重建 mylib::mylib 这个 IMPORTED Target，并将之前序列化好的 IMPORTED_LOCATION 和 INTERFACE_INCLUDE_DIRECTORIES 还原。对消费者而言，这与使用树内 Target 没有任何区别------这正是现代 CMake 依赖管理的精髓所在。

2.2 find_package 的查找机制

理解了库的封装方式后，find_package() 的行为就变得完全透明：它本质上是在指定路径下，寻找库作者提供的"说明书"。

2.2.1 查找模式

find_package() 有两种工作模式，优先级从高到低依次是：

（1）Config 模式（首选）

CMake 会寻找 <PackageName>Config.cmake 或 <PackageName>-config.cmake。这类文件通常由库作者 随库一起发布，内部已经用 add_library(Foo::Foo IMPORTED) 把 Target 定义好，并完整描述了依赖传递关系。我们在 2.1 节中通过 install(EXPORT) 生成的正是这种文件。

它的本质非常明确：库作者亲自提供"使用说明书"。由于信息来自源头，这种方式的准确性最高，也是现代 CMake 依赖管理的标准路径。

(2) Module 模式（兜底）

当 CMake 未能找到 <PackageName>Config.cmake 时，会退而寻找 Find<PackageName>.cmake。这类文件通常由 CMake 官方、发行版维护者或消费方 手写，是为那些"不提供 CMake 支持"的库补充的通用查找脚本，而不是个人环境的路径备忘录。因此，它通过 find_library()、find_path() 等机制适配不同机器和环境，而不是硬编码某一台机器的安装路径。

从职责划分上看，Find 模块属于"消费端的适配逻辑"，不应随预编译库一同分发------库是"被消费的对象"，而 Find 模块是"消费端的适配层"。在 Module 模式下，它的核心任务可以概括为两步：探测路径，以及将探测结果封装为 IMPORTED Target。下面给出一个符合现代 CMake 规范的简化示例：

cmake 复制代码

# FindFoo.cmake
include(FindPackageHandleStandardArgs)

# 1. 找头文件
find_path(FOO_INCLUDE_DIR
    NAMES foo/foo.h
    PATH_SUFFIXES include
)

# 2. 找库文件
find_library(FOO_LIBRARY
    NAMES foo
    PATH_SUFFIXES lib
)

# 3. 版本（可选，示例从头文件解析）
if(FOO_INCLUDE_DIR)
    if(EXISTS "${FOO_INCLUDE_DIR}/foo/version.h")
        file(STRINGS "${FOO_INCLUDE_DIR}/foo/version.h" _ver
             REGEX "^#define FOO_VERSION \"[0-9.]+\"")
        string(REGEX MATCH "[0-9.]+" FOO_VERSION "${_ver}")
    endif()
endif()

# 4. 标准处理
find_package_handle_standard_args(Foo
    REQUIRED_VARS FOO_LIBRARY FOO_INCLUDE_DIR
    VERSION_VAR FOO_VERSION
)

# 5. 封装 Imported Target（现代 CMake 必须）
if(Foo_FOUND AND NOT TARGET Foo::Foo)
    add_library(Foo::Foo UNKNOWN IMPORTED)
    set_target_properties(Foo::Foo PROPERTIES
        IMPORTED_LOCATION ${FOO_LIBRARY}
        INTERFACE_INCLUDE_DIRECTORIES ${FOO_INCLUDE_DIR}
    )
endif()

# 6. 清理临时变量
unset(_ver)

需要明确的是：Module 模式是妥协，不是规范 。如果你有权修改库的构建系统，应优先通过 install(EXPORT) 提供 Config 模式支持。只有在面对路径不固定、跨平台差异大或闭源库等"无法预先确定位置"的场景时，才应考虑编写 Find<PackageName>.cmake。

误区澄清 ：这里的"路径不确定"，并非指你不知道自己把库下到了哪，而是指你无法假设所有使用者、所有机器、所有平台都把它放在同一个位置。

2.2.2 搜索路径的逻辑

当你执行 find_package(<PackageName>) 时，CMake 的搜索逻辑可以概括为两层。

第一层是构造"安装前缀（prefix）"列表，优先级大致为：<PackageName>_ROOT（CMake 变量或环境变量，CMP0074 起生效）、CMAKE_PREFIX_PATH（CMake 变量或环境变量），以及系统默认前缀（如 /usr、/usr/local）。

第二层是在每个 <prefix> 下搜索固定子目录。CMake 会依次查找：

text 复制代码

<prefix>/(lib|lib64|share)/cmake/<PackageName>/
<prefix>/(lib|lib64|share)/<PackageName>/
<prefix>/(lib|lib64|share)/<PackageName>/cmake/

在 Windows 上，还会额外搜索 <prefix>/<PackageName>.cmake 等路径。

回头看 2.1 节中安装的 mylib，它之所以能被顺利发现，正是因为它命中了：

text 复制代码

/usr/local/lib/cmake/mylib/mylibConfig.cmake

这个设计的动机非常明确：让项目有能力覆盖系统环境 。例如在 CI 中，你可以将自行编译的依赖安装到 /opt/deps，然后通过 -DCMAKE_PREFIX_PATH=/opt/deps 告诉 CMake 优先去该路径下查找，而不污染系统目录。

2.3 版本校验与 Imported Target 的创建

当你写下 find_package(OpenSSL 3.0 REQUIRED) 时，版本校验的逻辑取决于模式：

在 Config 模式下，由配置文件内部的 check_required_components 机制处理。
在 Module 模式下，则由 Find 脚本手动实现版本比对。

一旦找到并校验通过，CMake 就会创建 Imported Target。以 OpenSSL::SSL 为例，它本质上是一个带有这些属性的 Target：

IMPORTED_LOCATION：指向 libssl.so 或 libssl.a 的实际路径。
INTERFACE_INCLUDE_DIRECTORIES：头文件目录，会自动传递给你的 app。
INTERFACE_LINK_LIBRARIES：它可能还会依赖 Threads::Threads 或 dl 库，这些也会一并传递。

这也是为什么你不需要手动写 -I 或 -L 参数的原因。

2.4 失败处理与降级

REQUIRED 关键字会让查找失败时直接报错，适合生产环境；QUIET 则用于你想自己处理失败逻辑的场景：

cmake 复制代码

find_package(Foo QUIET)
if(NOT Foo_FOUND)
  # 降级到 FetchContent 或给出友好提示
endif()

需要明确的是，CMake 不会自动从 find_package() 降级到 FetchContent，你必须自己写这段逻辑。

三、最佳实践

拒绝 target_link_directories()，改用 Target 语义

target_link_directories() 是全局生效的"历史遗留接口"，它会绕过构建树的依赖隔离，容易把系统里的旧版本库链接进项目，而且完全不具备头文件路径和编译选项的传递能力。现代 CMake 的正确做法是：把依赖封装成 IMPORTED Target，让路径、选项和依赖关系沿着 target_link_libraries() 自动传播，从根本上避免隐式污染。
明确 find_package() 的失败语义：REQUIRED vs QUIET

REQUIRED 适合生产环境，查找失败立即终止配置，避免问题被掩盖；QUIET 则用于你需要自己接管失败逻辑的场景，例如配合 FetchContent 做降级。一个常见模式是：
cmake 复制代码
```
find_package(Foo QUIET)
if(NOT Foo_FOUND)
    # 降级到 FetchContent 或给出可操作的提示
endif()
```
区分 FetchContent 与 ExternalProject 的使用边界

两者都用于引入外部依赖，但介入构建的时机不同：FetchContent 在配置阶段拉取源码并直接纳入当前构建树，适合"像子项目一样参与构建"的源码依赖；ExternalProject 则在构建阶段才执行下载和编译，适合需要独立构建步骤、复杂工具链或 ./configure 流程的第三方项目。简单判断标准是：能否用一份统一的 CMake 构建规则搞定。
版本锁定的可信度遵循"越靠近项目越可靠"

依赖版本的可控程度从高到低通常是：FetchContent 的 GIT_TAG / URL_HASH → find_package()的版本约束 → 系统包管理器版本。原因很直观：前两者写在项目配置里，随仓库走，所有开发者和 CI 行为一致；后者则由运行环境决定，跨机器、跨平台时极易出现"在我机器上没问题"的情况。
预编译库优先封装为 IMPORTED Target，而非手写 Find<Name>.cmake

当库的路径和版本相对固定时，直接创建带命名空间的 IMPORTED Target 是最清晰、最符合现代 CMake 设计意图的做法；只有在面对路径不固定、跨平台差异大或闭源库等"无法预先确定位置"的场景时，才应考虑编写 Find<Name>.cmake 作为兼容层。
关于"路径不确定"的准确理解

这并不等于"你不知道自己把库装到了哪里"，而是指你无法假设所有使用者、所有机器、所有平台都把它放在同一个位置。
- 自用 / 固定团队 / CI 环境路径统一 → 直接 IMPORTED Target
- 系统库 / 多平台分发 / 闭源 SDK / 对外发布 → Find 或 Config

参考资料

find_package --- CMake 3.28.6 Documentation

现代 CMake 依赖管理详解：从构建树、Target 封装到 find_package 工作原理

文章目录

一、依赖管理的基本概念

1.1 构建树：依赖可见性的边界

1.2 库是如何封装成 Target

1.2.1 树内库的封装（add_subdirectory）

1.2.2 预编译库的封装（IMPORTED Target）

1.3 依赖管理方式

1.3.1 add_subdirectory()：树内模块的原生集成

1.3.2 find_package()：树外预装库的标准对接

1.3.3 FetchContent：远程源码的按需拉取

1.4 如何导入依赖

1.4.1 库的形态决定导入方式

1.4.2 导入第三方库的标准流水线

二、find_package() 的工作原理

2.1 导出 Target：让库支持 find_package

2.2 find_package 的查找机制

2.2.1 查找模式

2.2.2 搜索路径的逻辑

2.3 版本校验与 Imported Target 的创建

2.4 失败处理与降级

三、最佳实践

参考资料

1.2.1 树内库的封装（`add_subdirectory`）

1.2.2 预编译库的封装（`IMPORTED` Target）

1.3.1 `add_subdirectory()`：树内模块的原生集成

1.3.2 `find_package()`：树外预装库的标准对接

1.3.3 `FetchContent`：远程源码的按需拉取

2.1 导出 Target：让库支持 `find_package`