GitLab流水线编译C++程序时/usr/include路径缺失的问题

可能的原因及对应解决方法 #

1. CMake自动识别系统路径，不生成显式-I参数，但编译器默认搜索路径异常 #

CMake会将/usr/include这类标准系统目录识别为系统包含路径，不会通过-I参数显式输出，而是依赖编译器自身的默认搜索路径。如果流水线环境中编译器的默认搜索路径被修改（比如使用交叉编译工具链、自定义编译器配置），就会出现文件存在但编译时找不到的情况。

解决步骤：

• 在流水线中执行以下命令，查看编译器的默认包含路径：

  echo | c++ -v -x c++ -E -
  

• 如果输出中没有/usr/include，说明编译器默认路径不包含该目录，可通过以下方式强制添加：
  • 使用BEFORE关键字让CMake优先处理该路径，避免被系统路径规则过滤：

    include_directories(BEFORE /usr/include)
    

  • 更推荐使用target_include_directories（针对具体编译目标），避免全局设置的副作用：

    target_include_directories(你的目标名称 PRIVATE
           /usr/include
           ${CMAKE_SOURCE_DIR}/inc
           ${CMAKE_SOURCE_DIR}/test/inc)
    

2. CMake启用了跳过系统包含路径的选项 #

如果流水线中的CMake配置开启了CMAKE_SKIP_SYSTEM_INCLUDES，会跳过所有系统默认包含路径，即使手动添加/usr/include也会被忽略。

解决步骤：

• 在流水线中执行cmake -LA查看缓存变量，确认CMAKE_SKIP_SYSTEM_INCLUDES是否为ON。
• 如果是，在CMake命令中添加参数关闭该选项：

  cmake .. -DCMAKE_SKIP_SYSTEM_INCLUDES=OFF
  

3. 流水线环境的编译器与本地不一致 #

本地使用的编译器（比如GCC）和流水线中的编译器（比如Clang、交叉编译GCC）可能存在默认路径差异，导致同样的CMake配置表现不同。

解决步骤：

• 确认流水线和本地使用的编译器版本一致，可在流水线中执行c++ --version对比。
• 如果必须使用不同编译器，针对该编译器调整包含路径配置，比如交叉编译时可能需要指定CMAKE_SYSROOT。

内容的提问来源于stack exchange，提问作者Epsilon