HarmonyOS鸿蒙Next中子目录native模块怎么链接系统库？

一般不需要把系统库的 .so 手动拷到你模块自己的 lib 目录里。

结论

对于 HarmonyOS/OpenHarmony 的 系统库：

• 子目录模块也可以正常链接
• 关键不是“模块在不在根目录”，而是：
  • 这个模块本身有没有正确配置 CMakeLists.txt
  • DevEco 有没有把这个模块识别成一个 native 构建单元
  • 你的头文件/库搜索路径是不是还写死成了“根目录相对路径”

先说你这个现象的本质

你说：

• 根目录模块里链接 libvulkan.so 时，可以正常联想补全
• 挪到 features/ 下后，不正常了

这通常说明不是 Vulkan 库本身的问题，而是下面几类问题之一：

1. 模块自己的 CMakeLists.txt 没被正确接入
2. build-profile.json5 / 模块配置没有声明 native 构建
3. 原来写的相对路径在子目录下失效了
4. IDE 的代码补全依赖的头文件路径没有跟着更新
5. 你引用的是外部库头文件，不是系统库头文件，但路径仍按根目录写法

系统库怎么链接

如果是系统库，比如：

• libvulkan.so
• libEGL.so
• libGLESv3.so
• libhilog_ndk.z.so
• libace_ndk.z.so

通常做法是直接在模块自己的 CMakeLists.txt 里链接，不需要复制系统库文件。

例如：

target_link_libraries(your_target PUBLIC libvulkan.so)

或者常见写法：

target_link_libraries(your_target PUBLIC
    libhilog_ndk.z.so
    libace_ndk.z.so
    libvulkan.so
)

这里的前提是：

• 这个模块本身已经被 DevEco/NDK 正确识别并参与构建
• 使用的是 SDK/NDK 提供的系统桩库

子目录模块要重点检查什么

1. 模块自己的 build-profile.json5

要确认这个 features/xxx 模块本身有 native 构建配置。

例如要有类似：

{
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt"
    }
  }
}

如果这个配置只在根模块里有，子模块没有，那 IDE 往往不会正确给你做 native 解析和补全。

2. 模块自己的 CMakeLists.txt

子模块应该有自己独立的 CMakeLists.txt，不要继续依赖根模块那一份的相对路径逻辑。

3. 不要写死根目录相对路径

很多人从根模块搬到 features/ 后，问题出在这里。

比如原来这么写：

include_directories(../../../../somepath/include)

模块位置一变，这种路径就错了。

更稳妥的写法是尽量基于：

• ${CMAKE_CURRENT_SOURCE_DIR}
• ${CMAKE_CURRENT_LIST_DIR}

例如：

include_directories(${CMAKE_CURRENT_SOURCE_DIR}/include)

或者引第三方库头文件：

include_directories(${CMAKE_CURRENT_SOURCE_DIR}/../../../libs/include)

这样你至少知道路径是相对“当前模块的 CMake 文件”算的。

为什么“联想补全”会失效

IDE 补全主要依赖两类东西：

1. 头文件路径
2. 当前 target 的编译配置

它不是靠你有没有把 .so 拷到 lib/ 目录来补全的。

也就是说：

• 补全正常，通常说明头文件路径和 native target 配好了
• 补全失效，通常说明 IDE 没拿到这个子模块的 C/C++ 编译信息

所以你要查的是：

• 这个子模块的 native target 有没有被构建系统识别
• 头文件 include path 是否正确
• CMakeLists.txt 是否实际参与同步

而不是先去拷系统 .so

什么时候才需要把 .so 放到模块里

只有在链接的是第三方预编译库时，才通常需要自己管理：

• 头文件放到某个 include/
• 预编译 .so 放到例如 libs/arm64-v8a/
• 用 add_library(... SHARED IMPORTED) + set_target_properties(...)
• 再 target_link_libraries(...)

例如第三方库才会这样：

add_library(thirdparty SHARED IMPORTED)
set_target_properties(thirdparty PROPERTIES
    IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/libs/arm64-v8a/libthirdparty.so
)

target_link_libraries(your_target PUBLIC thirdparty)

但系统库不是这个思路。

对你这个问题的直接回答

是否需要将外部库中对应的 so 库移动到模块的 lib 目录下？

• 系统库：不需要
• 第三方预编译库：通常需要自己管理路径，但也不一定非得叫 lib 目录，只要 CMake 配对即可

子目录 native 模块应该如何设置并正常联想补全？

重点做这几件事：

1. 给子模块单独配置 externalNativeOptions
2. 确保子模块有自己的 CMakeLists.txt
3. 修正所有相对路径，避免继续按根目录写法
4. 系统库直接 target_link_libraries(...)
5. 头文件路径用 include_directories(...) 或 target_include_directories(...)
6. 重新 Sync / Rebuild，让 IDE 重新生成 native 索引

更推荐的写法

比起全局 include_directories，更建议：

target_include_directories(your_target PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

然后：

target_link_libraries(your_target PUBLIC
    libhilog_ndk.z.so
    libace_ndk.z.so
    libvulkan.so
)

这样 target 级别更清晰，搬模块时也更不容易坏。

如果你现在就要排查

你可以按这个顺序看：

1. features/xxx/build-profile.json5 里有没有 native 配置
2. features/xxx/src/main/cpp/CMakeLists.txt 是否真实生效
3. #include <vulkan/vulkan.h> 能不能跳转
4. target_link_libraries 写的是不是系统库名
5. 是否还残留根模块时代的相对路径
6. Sync Project / Clean / Rebuild 后是否恢复补全

最后给你一个判断标准

如果你遇到的是：

• #include <vulkan/vulkan.h> 都不补全
  那多半是头文件路径/模块 native 配置问题

如果你遇到的是：

• 头文件能补全，但链接时报找不到符号
  那多半是**target_link_libraries 问题**

find_library 在 DevEco/Hvigor 注入的 OHOS CMake toolchain 下，会基于当前 SDK/NDK 的 sysroot 和目标架构去找系统库，一般不需要把 openharmony/hms 下的系统 so 再手工拷贝到模块目录。你可以在 CMakeLists 里打印 CMAKE_SYSROOT、CMAKE_FIND_ROOT_PATH、OHOS_ARCH 等变量确认实际搜索路径。现在“完整输入能识别、Ctrl+左键能跳转，但 Windows 版不能补全”，更像 IDE 索引/语言服务问题，不是链接配置问题。建议先以编译和链接结果为准；Win 端可尝试删除 .cxx、.hvigor、.idea 缓存后重新 Sync/Index。

在 HarmonyOS Next 的 native 模块中，通过 CMakeLists.txt 的 target_link_libraries 指令直接指定系统库名称（如 hilog_ndk、ace_napi）。系统库路径已预置，无需额外配置。若使用 BUILD.gn，在 deps 中引用对应 ohos_shared_library 目标即可。