第 17 章：问题排查
第 17 章：问题排查
17.1 配置阶段错误
17.1.1 CMake 版本不匹配
错误信息：
CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
CMake 3.22 or higher is required. You are running version 3.16.3.
解决方案：
# 检查版本
cmake --version
# 升级 CMake
pip install cmake --upgrade
# 或
sudo snap install cmake --classic
# 或降低项目要求
cmake_minimum_required(VERSION 3.16)
17.1.2 编译器未找到
错误信息：
CMake Error: Could not find compiler set in environment variable CXX:
g++-15
解决方案：
# 检查编译器
which g++
g++ --version
# 设置正确的编译器
export CXX=g++
export CC=gcc
# 或在 CMake 中指定
cmake -DCMAKE_CXX_COMPILER=g++ -DCMAKE_C_COMPILER=gcc
# 或使用工具链文件
cmake -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake
17.1.3 find_package 找不到库
错误信息：
CMake Error: Could not find a package configuration file provided by "OpenSSL"
排查步骤：
# 1. 检查库是否安装
dpkg -l | grep openssl
# 或
apt list --installed 2>/dev/null | grep openssl
# 2. 检查开发包是否安装
apt list --installed 2>/dev/null | grep libssl-dev
# 3. 设置搜索路径
cmake -DCMAKE_PREFIX_PATH=/usr/local/ssl
# 或
cmake -DOPENSSL_ROOT_DIR=/usr/local/ssl
# 4. 使用调试模式查看查找过程
cmake --debug-find-pkg=OpenSSL -S . -B build
# 5. 查看缓存变量
cmake -S . -B build -L | grep -i openssl
17.1.4 源文件未找到
错误信息：
CMake Error: Cannot find source file:
src/main.cpp
解决方案：
# 检查路径是否相对于 CMakeLists.txt 所在目录
# 正确
add_executable(app ${CMAKE_CURRENT_SOURCE_DIR}/src/main.cpp)
# 或使用相对路径（相对于当前 CMakeLists.txt）
add_executable(app src/main.cpp)
# 检查文件是否存在
if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/src/main.cpp")
message(FATAL_ERROR "src/main.cpp 不存在！")
endif()
17.1.5 生成器不支持
错误信息：
CMake Error: Could not create named generator Ninja
解决方案：
# 查看可用生成器
cmake --help | grep generators
# 安装 Ninja
apt install ninja-build
# 或使用 Make
cmake -G "Unix Makefiles"
17.2 构建阶段错误
17.2.1 编译错误
常见错误：
fatal error: some_header.h: No such file or directory
解决方案：
# 添加包含目录
target_include_directories(myapp PRIVATE
${CMAKE_CURRENT_SOURCE_DIR}/include
${CMAKE_CURRENT_BINARY_DIR} # 生成的头文件
)
# 使用 SYSTEM 避免警告
target_include_directories(mylib SYSTEM PUBLIC
/usr/local/include
)
# 检查是否链接了正确的库
target_link_libraries(myapp PRIVATE correct_lib)
17.2.2 链接错误
错误信息：
undefined reference to `some_function()'
排查步骤：
# 1. 检查符号是否存在
nm -C libsome.a | grep some_function
# 或
readelf -s libsome.so | grep some_function
# 2. 检查链接顺序
# 静态库链接顺序很重要：被依赖者在后面
target_link_libraries(app PRIVATE mylib dep_lib)
# 3. 检查是否遗漏链接库
# 常见遗漏：pthread, m, dl, rt
target_link_libraries(app PRIVATE Threads::Threads)
# 4. 检查 C++ 名称修饰
# 确保 C 和 C++ 库正确混合使用
extern "C" {
#include "c_header.h"
}
链接库顺序问题：
# 错误：依赖者在前面
target_link_libraries(app PRIVATE base mylib) # mylib 依赖 base
# 正确：被依赖者在后面
target_link_libraries(app PRIVATE mylib base)
# 或使用链接组解决循环依赖
target_link_libraries(app PRIVATE
-Wl,--start-group
libA libB
-Wl,--end-group
)
17.2.3 未定义符号错误
错误信息：
CMake Error: Target "mylib" has dependency on "OpenSSL::SSL"
but target was not found.
解决方案：
# 确保 find_package 在使用前调用
find_package(OpenSSL REQUIRED)
target_link_libraries(mylib PUBLIC OpenSSL::SSL)
# 或检查目标是否存在
if(TARGET OpenSSL::SSL)
target_link_libraries(mylib PUBLIC OpenSSL::SSL)
else()
message(WARNING "OpenSSL 未找到")
endif()
17.2.4 重复定义错误
错误信息：
multiple definition of `some_function'
解决方案：
# 检查是否重复链接同一库
target_link_libraries(app PRIVATE mylib)
target_link_libraries(app PRIVATE mylib) # 重复！
# 检查头文件是否在多个源文件中定义了全局变量
# 使用 extern 声明
# header.h
extern int global_var; # 声明
# source.cpp
int global_var = 42; # 定义
17.3 运行时错误
17.3.1 共享库找不到
错误信息：
error while loading shared libraries: libmylib.so: cannot open shared object file
解决方案：
# 设置 RPATH
set_target_properties(myapp PROPERTIES
INSTALL_RPATH "$ORIGIN/../lib"
INSTALL_RPATH_USE_LINK_PATH TRUE
)
# 构建时设置 RPATH
set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib")
# 或禁用 RPATH（不推荐）
set(CMAKE_SKIP_RPATH TRUE)
set(CMAKE_SKIP_INSTALL_RPATH TRUE)
# 临时解决方案
export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH
# 永久解决方案
echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/myapp.conf
sudo ldconfig
17.3.2 程序找不到资源文件
解决方案：
# 定义数据目录
target_compile_definitions(myapp PRIVATE
DATA_DIR="${CMAKE_INSTALL_PREFIX}/share/myapp"
)
# 或使用相对于可执行文件的路径
set_target_properties(myapp PROPERTIES
INSTALL_RPATH "$ORIGIN"
)
# 在代码中获取可执行文件路径
# Linux: readlink /proc/self/exe
# macOS: _NSGetExecutablePath
# Windows: GetModuleFileName
17.4 变量调试
17.4.1 打印变量值
# 打印单个变量
message(STATUS "MY_VAR = ${MY_VAR}")
# 打印多个变量
message(STATUS "
项目配置:
PROJECT_NAME: ${PROJECT_NAME}
PROJECT_VERSION: ${PROJECT_VERSION}
CMAKE_BUILD_TYPE: ${CMAKE_BUILD_TYPE}
CMAKE_CXX_COMPILER: ${CMAKE_CXX_COMPILER}
CMAKE_INSTALL_PREFIX: ${CMAKE_INSTALL_PREFIX}
")
# 条件打印
if(VERBOSE_CONFIG)
message(STATUS "CMAKE_CXX_FLAGS: ${CMAKE_CXX_FLAGS}")
message(STATUS "CMAKE_EXE_LINKER_FLAGS: ${CMAKE_EXE_LINKER_FLAGS}")
endif()
17.4.2 列出所有变量
# 在 CMakeLists.txt 中
get_cmake_property(_vars VARIABLES)
foreach(_var ${_vars})
message(STATUS "${_var} = ${${_var}}")
endforeach()
# 命令行方式
cmake -S . -B build -L # 用户变量
cmake -S . -B build -LA # 包含高级变量
17.4.3 条件断点
# CMake 没有断点，但可以模拟
function(debug_var var_name)
if(DEBUG_CMAKE)
message(STATUS "[DEBUG] ${var_name} = ${${var_name}}")
if(${ARGC} GREATER 1)
message(STATUS "[DEBUG] ${ARGV1}")
endif()
endif()
endfunction()
debug_var(CMAKE_BUILD_TYPE)
debug_var(PROJECT_VERSION "项目版本")
17.4.4 缓存变量问题
# 查看 CMakeCache.txt
cat build/CMakeCache.txt | grep -i my_var
# 删除缓存重新配置
rm -rf build
cmake -S . -B build
# 只删除特定变量
cmake -S . -B build -UMY_VAR
# 强制覆盖
cmake -S . -B build -DMY_VAR=new_value -DMY_VAR:STRING=new_value
17.5 生成器表达式调试
17.5.1 无法直接打印
# 不能在配置阶段打印生成器表达式
message(STATUS "$<CONFIG>") # 输出：$<CONFIG>（字面量）
# 使用 file(GENERATE) 来调试
file(GENERATE
OUTPUT "${CMAKE_BINARY_DIR}/debug_config.txt"
CONTENT "Config: $<CONFIG>\nCompiler: $<CXX_COMPILER_ID>\n"
)
# 构建后查看
cat build/debug_config.txt
17.5.2 使用自定义目标调试
add_custom_target(debug_genex
COMMAND ${CMAKE_COMMAND} -E echo "Config: $<CONFIG>"
COMMAND ${CMAKE_COMMAND} -E echo "Compiler: $<CXX_COMPILER_ID>"
COMMAND ${CMAKE_COMMAND} -E echo "Platform: $<PLATFORM_ID>"
COMMENT "调试生成器表达式"
)
17.6 目标属性调试
17.6.1 检查目标属性
# 打印目标的所有属性
function(dump_target target)
message(STATUS "=== 目标: ${target} ===")
get_target_property(type ${target} TYPE)
message(STATUS " 类型: ${type}")
get_target_property(srcs ${target} SOURCES)
message(STATUS " 源文件: ${srcs}")
get_target_property(dirs ${target} INCLUDE_DIRECTORIES)
message(STATUS " 包含目录: ${dirs}")
get_target_property(libs ${target} LINK_LIBRARIES)
message(STATUS " 链接库: ${libs}")
get_target_property(defs ${target} COMPILE_DEFINITIONS)
message(STATUS " 编译定义: ${defs}")
get_target_property(opts ${target} COMPILE_OPTIONS)
message(STATUS " 编译选项: ${opts}")
endfunction()
dump_target(myapp)
17.6.2 检查传递依赖
# 递归检查目标依赖
function(dump_target_deps target depth)
math(EXPR next_depth "${depth} + 1")
string(REPEAT " " ${depth} indent)
message(STATUS "${indent}目标: ${target}")
get_target_property(libs ${target} LINK_LIBRARIES)
if(libs)
foreach(lib ${libs})
if(TARGET ${lib})
dump_target_deps(${lib} ${next_depth})
endif()
endforeach()
endif()
endfunction()
dump_target_deps(myapp 0)
17.7 构建日志调试
17.7.1 详细构建输出
# CMake 配置时的详细输出
cmake -S . -B build --log-level=VERBOSE
cmake -S . -B build --log-level=DEBUG
cmake -S . -B build --log-level=TRACE
# 构建时的详细输出
cmake --build build --verbose
# 或
make VERBOSE=1
# 或
ninja -v
# CTest 详细输出
ctest --test-dir build -V
ctest --test-dir build -VV
17.7.2 编译命令数据库
# 生成 compile_commands.json
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
# 使用 Ninja 生成器时自动产生
cmake -S . -B build -G Ninja
# build/compile_commands.json 包含所有编译命令
# 查看特定文件的编译命令
cat build/compile_commands.json | jq '.[] | select(.file | contains("main.cpp"))'
# 或使用 bear
bear -- make
17.8 常见陷阱和解决方案
17.8.1 变量作用域问题
# 问题：在子目录中设置的变量不影响父目录
# sub/CMakeLists.txt
set(MY_VAR "value") # 仅在 sub/ 有效
# 解决：使用 PARENT_SCOPE
set(MY_VAR "value" PARENT_SCOPE)
# 或使用缓存变量
set(MY_VAR "value" CACHE STRING "描述")
17.8.2 include 与 add_subdirectory 区别
# add_subdirectory: 创建新作用域
add_subdirectory(sub)
# sub 中的变量不会影响当前作用域
# include: 在当前作用域执行
include(sub/CMakeLists.txt)
# sub 中的变量会影响当前作用域（注意！）
17.8.3 file(GLOB) 不自动更新
# 问题：添加新文件后需要重新运行 cmake
file(GLOB SOURCES "src/*.cpp")
# 解决方案一：手动列出文件（推荐）
set(SOURCES
src/main.cpp
src/utils.cpp
src/network.cpp
)
# 解决方案二：使用 CONFIGURE_DEPENDS（CMake 3.12+）
file(GLOB SOURCES CONFIGURE_DEPENDS "src/*.cpp")
17.8.4 目标名称冲突
# 问题：多个目录使用相同的目标名
# dir1/CMakeLists.txt
add_library(utils src/utils.cpp) # 冲突！
# 解决：使用命名空间或前缀
add_library(myproject_dir1_utils src/utils.cpp)
add_library(MyProject::dir1::utils ALIAS myproject_dir1_utils)
17.9 调试工具
17.9.1 CMake 内置调试
# 调试模式
cmake --trace-expand # 展开所有变量
cmake --trace-source=file.cmake # 追踪特定文件
# 性能分析
cmake --profiling-format=google-trace --profiling-output=trace.json
# 使用 chrome://tracing 查看
17.9.2 cmake_print_variables
include(CMakePrintHelpers)
cmake_print_variables(CMAKE_BUILD_TYPE PROJECT_VERSION)
cmake_print_target_properties(myapp)
17.9.3 try_compile
# 测试编译功能
try_compile(HAS_CXX17
${CMAKE_BINARY_DIR}/test
SOURCES ${CMAKE_SOURCE_DIR}/cmake/test_cxx17.cpp
CXX_STANDARD 17
)
if(HAS_CXX17)
message(STATUS "编译器支持 C++17")
else()
message(FATAL_ERROR "需要支持 C++17 的编译器")
endif()
17.10 业务场景
场景：系统化问题排查流程
问题出现
│
├── 1. 配置阶段错误
│ ├── 检查 CMake 版本
│ ├── 检查编译器
│ ├── 检查 find_package 结果
│ └── 查看 CMakeCache.txt
│
├── 2. 构建阶段错误
│ ├── 编译错误 → 检查包含目录、编译选项
│ ├── 链接错误 → 检查链接库、链接顺序
│ └── 使用 --verbose 查看完整命令
│
├── 3. 运行时错误
│ ├── 共享库找不到 → 检查 RPATH
│ ├── 资源文件找不到 → 检查路径
│ └── 使用 ldd 检查依赖
│
└── 4. 调试技巧
├── 清理重新构建：rm -rf build
├── 详细输出：--verbose
├── 变量检查：message()
└── 目标检查：dump_target()
17.11 注意事项
| 问题 | 常见原因 | 解决方案 |
|---|---|---|
| 配置失败 | 版本不匹配/依赖缺失 | 升级 CMake/安装依赖 |
| 编译失败 | 头文件路径/编译选项 | 检查 target_include_directories |
| 链接失败 | 库未链接/顺序错误 | 检查 target_link_libraries |
| 运行时失败 | RPATH/动态库路径 | 设置 INSTALL_RPATH |
| 测试失败 | 工作目录/环境变量 | 设置 WORKING_DIRECTORY |
17.12 扩展阅读
上一章：第 16 章 — Docker 与 CI/CD | 下一章：第 18 章 — 最佳实践 →