答案是cmake_module_path必须显式设置且不可清空，默认路径仅在未设时回退使用；其路径顺序从左到右优先匹配，分号分隔，应使用相对路径并保留系统默认路径。
find_package 用 Module 模式时，CMAKE_MODULE_PATH 是唯一可控的搜索路径
如果你写 find_package(MyLib MODULE REQUIRED)，CMake 就只认 CMAKE_MODULE_PATH 里的路径，其他地方（比如系统自带的 Modules 目录）哪怕有 FindMyLib.cmake 也不会被考虑——除非你没设 CMAKE_MODULE_PATH，它才会 fallback 到默认路径。
所以不是“怎么用”，而是“必须设”：不设就找不到自定义 Find*.cmake，哪怕文件就放在项目根目录下。
-
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake;${CMAKE_MODULE_PATH}")—— 这是最常见写法，把项目内cmake/目录加到最前，优先级最高 -
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")—— 效果相同，但更安全，不会覆盖系统原有路径（比如 CMake 自带 Modules） - 绝对不要写
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")—— 这会清空所有默认路径，导致find_package(Threads)、find_package(OpenMP)等内置模块全挂
为什么 find_package(MyLib) 有时能不设 CMAKE_MODULE_PATH 也能成功？
因为没加 MODULE 选项时，CMake 默认先走 Module 模式（查 FindMyLib.cmake），失败后再自动切 Config 模式（查 MyLibConfig.cmake）。你没设 CMAKE_MODULE_PATH 却找到了，大概率是：
- 系统已装该库（如
apt install libyaml-cpp-dev），且它提供了yaml-cpp-config.cmake，CMake 在/usr/lib/x86_64-linux-gnu/cmake/yaml-cpp/这类路径里找到了 - 你机器上 CMake 自带了
FindYAML.cmake（在${CMAKE_ROOT}/share/cmake-3.x/Modules/下），而你恰好用了小写名或别名 -
MyLib名字碰巧匹配某个内置模块（比如find_package(Boost)能成功，是因为 CMake 自带FindBoost.cmake）
换句话说：能不设路径就成功，说明你依赖的是别人预置好的东西；一旦要找自己写的或第三方没打包的库，CMAKE_MODULE_PATH 就绕不开。
C++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
CMAKE_MODULE_PATH 的路径顺序直接影响 find_package 行为
CMake 按 CMAKE_MODULE_PATH 中路径的**从左到右顺序**查找 Find*.cmake。第一个匹配的文件会被执行，后面的同名文件完全忽略。
- 如果同时存在
cmake/FindMyLib.cmake和third_party/cmake/FindMyLib.cmake，把cmake/放前面才能用你自己的版本 - 多个路径用分号
;分隔，不能用冒号或空格；Windows 和 Linux 都一样 -
message(STATUS "CMAKE_MODULE_PATH = ${CMAKE_MODULE_PATH}")可实时验证路径是否生效，比猜强得多 - 路径中不要硬编码绝对路径（如
/home/user/myproj/cmake），一律用${CMAKE_CURRENT_SOURCE_DIR}或${CMAKE_CURRENT_LIST_DIR}
常见错误：find_package 找不到，但 FindXXX.cmake 明明存在
最典型的三个原因：
-
find_package(MyLib MODULE REQUIRED)写了MODULE，但CMAKE_MODULE_PATH没包含FindMyLib.cmake所在目录 —— 查不到就直接报错，不 fallback -
FindMyLib.cmake文件名大小写不符（Linux 下find_package(mylib)不会匹配FindMyLib.cmake，必须严格对应） -
FindMyLib.cmake里没设置MyLib_FOUND或设置了但值为FALSE——find_package认为“找到文件但没找到库”，仍报错
真正容易被忽略的是最后一点：很多自写 Find*.cmake 只负责查路径，不检查头文件或库是否存在，结果 MyLib_INCLUDE_DIRS 被设了，但 MyLib_FOUND 没设或设错，REQUIRED 就直接跪了。
