静态库需同时配置.lib路径和头文件路径,缺一不可;须按平台区分后缀,显式设置PublicIncludePaths,并匹配UE的CRT版本以防LNK2038。

直接在项目模块的 .Build.cs 里配静态库,是最简单也最容易出错的方式——不是加了路径和 .lib 就能用,漏掉头文件路径或依赖顺序,编译器立刻报 LNK2019 或 C2065。
静态库必须同时提供 .lib + 头文件,缺一不可
UE 不像普通 C++ 工程能靠 IDE 自动推导包含路径。你把 mylib.lib 放进 PublicAdditionalLibraries,但没告诉编译器去哪找 mylib.h,它连函数声明都看不到,更别说链接实现。
-
PublicIncludePaths必须显式添加头文件所在目录,比如Path.Combine(ThirdPartyPath, "include") - 如果头文件里又
#include,还得确保该路径也在PublicIncludePaths中,或用PublicDefinitions加宏控制条件编译 - Windows 下静态库后缀是
.lib,Linux 是.a,macOS 是.tbd或.a;Build.cs中必须按Target.Platform分支处理
PublicDependencyModuleNames 和 PrivateDependencyModuleNames 的选择影响符号可见性
如果你的静态库内部调用了 UE 引擎模块(比如用了 FString 或 UObject),那它就不是“纯原生”库,而是一个依赖引擎的 UE 兼容库。这时不能只把它当黑盒塞进去。
- 若你的模块头文件中公开暴露了该静态库的类型(如返回
MyLibResult结构体),就得把它的头文件路径加到PublicIncludePaths,且该库所依赖的 UE 模块(如"Core")必须出现在PublicDependencyModuleNames中,否则其他模块引用你时会找不到FString - 如果只是内部调用、不对外暴露任何类型,所有头文件路径走
PrivateIncludePaths,依赖模块写进PrivateDependencyModuleNames即可 - 误把本该私有的依赖写成 public,会导致下游模块意外继承一堆无关头文件路径,引发命名冲突或编译变慢
第三方库的运行时依赖(如 DLL / so)仍需手动部署
静态库 .lib 是编译期链接进去的,但很多“静态库”其实只是包装了对系统 DLL 的调用(比如某些音频 SDK 静态链接了导入库,实际仍要 LoadLibrary)。这类库不会因你加了 .lib 就自动带上运行时依赖。
- 检查该静态库是否真无外部 DLL 依赖:用
dumpbin /dependents mylib.lib(Windows)或nm -C mylib.a | grep "U "(Linux)看是否有未解析的外部符号 - 如果有,比如依赖
avcodec-60.dll,你得在打包时把对应 DLL 放进Binaries/Win64/目录,或在代码里用FPlatformProcess::ExecProcess前确保其存在 - UE 的
Build.cs不负责拷贝运行时 DLL,那是Target.cs或打包脚本的事
最常被忽略的一点:静态库的 C 运行时(CRT)版本必须和 UE 一致。UE5.7 默认用 MSVC v17.7+ 的 /MT(静态 CRT),如果你的 .lib 是用 /MD 编译的,链接时会出现 LNK2038(mismatch detected for 'RuntimeLibrary')。这种问题不会在 Build.cs 里体现,但编译失败时错误信息里一定有这句。
C++免费学习笔记(深入):立即使用
在学习笔记中,你将探索 C++ 的入门与实战技巧!











