ESP-IDF v5.5.1编译报错：esp_timer.h找不到及组件依赖问题

问题现象 #

cpp-common组件在ESP-IDF v5.5.1环境编译时出现报错，明明已在COMPONENT_REQUIRES中声明esp_timer依赖，却提示头文件找不到，同时伴随组件依赖检查的BUG提示：

cpp-common/common/utils/utilities.cpp:88:10: fatal error: esp_timer.h: No such file or directory
   88 | #include "esp_timer.h"
      |          ^~~~~~~~~~~~~

compilation terminated.
ninja: build stopped: subcommand failed.
BUG: component_requirements.py: esp_timer.h found in component esp_timer which is already in the requirements list of cpp-common

该组件在ESP-IDF v4.4及以下版本无需添加REQUIRES配置即可正常编译。

组件结构：

cpp-common/
   common/
      comm/
      ...
      utils/
   CMakeLists.txt

问题原因 #

你的CMakeLists.txt混合了ESP-IDF组件注册逻辑与普通CMake库构建逻辑，在v5.x版本的ESP-IDF组件系统中，这种写法会引发依赖路径处理冲突：

• 手动硬编码添加esp_timer头文件路径，与COMPONENT_REQUIRES自动引入的路径重复，触发BUG提示
• register_component()之后又用add_library重新定义目标，覆盖了组件系统生成的目标，导致依赖路径未正确传递

修复后的CMakeLists.txt #

cmake_minimum_required(VERSION 3.16)

message("cpp-common")

if (NOT TARGET cpp-common)
  # ESP32环境下优先使用ESP-IDF组件系统注册
  if(IDF_TARGET)
    # 仅添加自身组件的头文件路径，依赖组件路径由COMPONENT_REQUIRES自动处理
    set(COMPONENT_ADD_INCLUDEDIRS common)
    set(COMPONENT_REQUIRES vfs esp_timer)
    # 注册组件后，ESP-IDF会自动生成目标并处理依赖
    register_component()
  else()
    # 非ESP32环境下使用普通CMake构建
    project(cpp-common)

    option(BUILD_STATIC_LIBS "Build a static version of the library" OFF)
    option(BUILD_RELEASE "Build the release version of the library" OFF)

    set(LIB_TYPE STATIC)
    if(NOT BUILD_STATIC_LIBS)
      set(LIB_TYPE SHARED)
    endif()

    if(NOT BUILD_RELEASE) 
      set(CMAKE_BUILD_TYPE Debug)
    endif()

    set(CMAKE_CXX_STANDARD 17)

    file(GLOB_RECURSE GLOB_SOURCE_FILES "${CMAKE_CURRENT_SOURCE_DIR}/common/**/*.c*")
    file(GLOB_RECURSE GLOB_HEADER_FILES "${CMAKE_CURRENT_SOURCE_DIR}/common/**/*.h*")

    add_library(${PROJECT_NAME} ${LIB_TYPE} ${GLOB_SOURCE_FILES} ${GLOB_HEADER_FILES})
    target_include_directories(${PROJECT_NAME} PUBLIC .)
  endif()

  # 仅在非ESP-IDF环境下设置额外编译选项
  if(NOT IDF_TARGET)
    target_compile_options(${PROJECT_NAME} INTERFACE -std=gnu++17)
  endif()
endif()

message("cpp-common Done")

关键修改点 #

• 移除硬编码的依赖组件头文件路径：ESP-IDF会通过COMPONENT_REQUIRES自动管理依赖组件的头文件搜索路径，手动添加会导致路径冲突
• 分离ESP-IDF组件构建与普通CMake构建逻辑：将非ESP32环境下的add_library等逻辑放到else()分支，避免覆盖register_component()生成的目标
• 删除冗余配置：去掉target_link_libraries(${COMPONENT_TARGET} ...)和手动引入IDF_INCLUDE_DIRECTORIES的代码，register_component()已自动处理依赖链接和路径
• 优化编译选项配置：仅在非ESP-IDF环境下设置-std=gnu++17，避免和ESP-IDF自带的C++标准配置冲突

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