关于 unreal-thirdparty
面向 Unreal Engine C++ 插件开发者的第三方库集成参考，涵盖链接方案、平台与 ABI 限制、打包方式及常见构建问题。
主要功能
- 01静态与动态库链接方案
- 02Build.cs 属性与模块配置
- 03平台 ABI 与打包指导
- 04隔离编译设置的屏障模块
- 05常见集成问题与 UE 版本变更
适用场景
- 01为 Unreal Engine 插件接入预编译库
- 02打包 DLL 和其他运行时依赖
- 03排查链接器或平台 ABI 故障
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/unreal-thirdparty确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/build-system.mdlinking-patterns.mdpatterns-and-pitfalls.mdplatform-specifics.md详细介绍
Unreal Engine 第三方库集成——C++ 指南
官方文档（请始终查阅以获取最新详情）
| 来源 | URL |
|---|---|
| Epic：集成第三方库 | https://dev.epicgames.com/documentation/unreal-engine/integrating-third-party-libraries-into-unreal-engine |
| Epic 社区：静态库 + Blueprint 教程 | https://dev.epicgames.com/community/learning/tutorials/0yJy/unreal-engine-fab-c-creating-your-own-3rd-party-function-library-and-using-it-in-blueprints |
| UE 论坛：了解其工作原理 | https://forums.unrealengine.com/t/adding-third-party-libraries-to-unreal-understanding-how-this-works/211244 |
| georgy.dev：第三方集成 | https://georgy.dev/posts/third-party-integration/ |
| unrealcode.net：封装库 | https://www.unrealcode.net/WrappingALibrary/ |
| Linux ABI / Sysroot 指南 | https://pgaleone.eu/2023/06/18/unreal-engine-third-party-linux-sysroot-dependencies/ |
| GitHub：Boost/PCL 插件示例 | https://github.com/ValentinKraft/Boost_PCL_UnrealThirdPartyPlugin |
| GitHub：UnrealImGui（参考实现） | https://github.com/IDI-Systems/UnrealImGui |
| 引擎第三方源代码 | Engine/Source/ThirdParty/（打包前请先检查此处——Epic 已提供 libcurl、zlib、libpng、OpenSSL 等） |
更多社区资源
插件模板
UE 提供 Third Party Library 插件模板。在编辑器中选择：Plugins > New Plugin > Third Party Library（滚动到底部）。这会生成基于 DLL 的集成所需的脚手架。对于静态库，在 Build.cs 中采用两行配置更简单。
核心架构
完整的 Build.cs 参考（包含所有属性和路径变量）请参阅 references/build-system.md。
集成流程：
Third-Party Source (or prebuilt binaries)
|
v
[Optional: Recompile with UE toolchain for ABI compat]
|
v
Place headers + libs in Plugin/Source/ThirdParty/
|
v
Create External Module (.Build.cs with ModuleType.External)
|-- PublicIncludePaths -> header directories
|-- PublicAdditionalLibraries -> .lib / .a files
|-- PublicDelayLoadDLLs -> DLL names (Windows delay-load)
|-- RuntimeDependencies -> .dll / .so / .dylib staging
|-- PublicDefinitions -> preprocessor macros
v
Consumer Module depends on External Module
|-- PublicDependencyModuleNames.Add("MyThirdPartyLib")
|-- #include with THIRD_PARTY_INCLUDES_START/END
v
Use library API in UE C++ code
推荐的目录结构：
MyPlugin/
MyPlugin.uplugin
Source/
MyPlugin/ # Runtime module (your code)
MyPlugin.Build.cs
Private/
Public/
ThirdParty/
MyLibrary/ # External module (no source)
MyLibrary.Build.cs # Type = ModuleType.External
include/ # Library headers
lib/
Win64/ *.lib
Linux/ *.a or *.so
Mac/ *.a or *.dylib
Binaries/
ThirdParty/MyLibrary/Win64/ # DLLs (if dynamic linking)
四种集成方式
每种方式的详细代码示例请参阅 references/linking-patterns.md。
| 方式 | 适用场景 | Build.cs 属性 |
|---|---|---|
| 静态库 | 最简单；单个可执行文件；无需分发 DLL | PublicAdditionalLibraries |
| 动态库 + 导入库 | DLL 在编译时解析符号 | PublicAdditionalLibraries + PublicDelayLoadDLLs + RuntimeDependencies |
| 动态库，无导入库 | 通过 GetDllExport 在运行时查找函数指针 | 仅 RuntimeDependencies |
| 多平台静态库 | 为各个平台提供单独库文件的跨平台插件 | PublicAdditionalLibraries，配合 Target.Platform 分支 |
库文件类型
| 平台 | 静态库 | 动态库 | 导入库 | 前缀 |
|---|---|---|---|---|
| Windows | .lib | .dll | .lib | 无 |
| Linux / Android | .a | .so | 不适用 | lib |
| macOS / iOS | .a | .dylib | 不适用 | lib |
Build.cs 快速参考
| 属性 | 用途 |
|---|---|
Type = ModuleType.External | 模块封装预编译库，不编译 UE 源代码 |
PublicIncludePaths | 头文件搜索目录 |
PublicSystemIncludePaths | 与上项相同，但会抑制这些头文件产生的警告 |
PublicAdditionalLibraries | 静态库 / 导入库文件路径 |
PublicDelayLoadDLLs | 用于 Windows 延迟加载的 DLL 文件名 |
RuntimeDependencies | 打包时与可执行文件一同暂存的文件 |
PublicDefinitions | 预处理器定义（"WITH_MYLIB=1"） |
PublicFrameworks | macOS 框架 |
bUseRTTI | 启用 RTTI（Boost 和某些 C++ 库所必需） |
bEnableExceptions | 启用 C++ 异常（许多库所必需） |
bForceEnableRTTI | 在整个引擎范围内强制启用 RTTI（在 TargetRules 中） |
平台特定注意事项
有关 Windows DLL 加载、macOS @rpath/dylib 以及 Linux ABI/sysroot 的详细信息，请参阅 references/platform-specifics.md。
关键规则：
- Windows： 只能按名称查找 DLL（导入表中没有路径）。使用
FPlatformProcess::GetDllHandle()或延迟加载。UE 会搜索 Engine/Project/Plugin 的Binaries/Win64/目录。 - macOS： Dylib 使用
@rpath安装名称。使用install_name_tool -id @rpath/libfoo.dylib设置。UBT 会自动添加 RPATH 条目。 - Linux： 必须使用 UE 的 Clang +
libc++（而非系统libstdc++）重新编译 C++ 库。C 库（ABI 稳定）无需重新编译。使用 UE 的 CMake 工具链文件。
常见模式与陷阱
请参阅 references/patterns-and-pitfalls.md，了解实现方案、关键陷阱和故障排查方法。
关键陷阱：
- UE 的
check宏会与使用check作为标识符的第三方代码冲突——使用#undef check或封装 include - 使用
/MD编译（多线程 DLL），以匹配 UE 的运行时——CRT 不匹配会导致链接器错误 - RTTI + 异常默认关闭——Boost、PCL 和许多 C++ 库都要求在 External 模块和每个使用该模块的模块中设置
bUseRTTI = true和bEnableExceptions = true - 仅使用 Release 库——UE 使用 Release CRT；使用 Debug 构建的库会导致
_ITERATOR_DEBUG_LEVEL不匹配和访问冲突 - VS 项目设置会被忽略——只有
.Build.cs才重要；Visual Studio 属性对 UBT 毫无影响 Binaries/ThirdParty/不会重新生成——如果删除，模板中的 DLL 就会丢失；UBT 无法重新构建它们- Linux ABI 不匹配——使用
libstdc++编译的 C++ 库，其符号修饰与 UE 的libc++不同
UE 版本特定的 Build.cs 更改
请参阅 references/build-system.md，了解完整的逐版本变更日志。
影响第三方集成的关键破坏性变更：
- UE 5.0：
FVector改为 3 个 double；TObjectPtr取代原始 UObject 指针 - UE 5.2：
bEnforceIWYU（bool）改为IWYUSupport（enum） - UE 5.3：
BuildSettingsVersion.V4默认使用 C++20；TRemoveConst弃用，改用std::remove_const - **UE 5.4：**MSVC 默认警告级别改为
/W4；FText内部实现从TSharedRef改为TRefCountPtr - **UE 5.5：**新的
Engine/Build/BatchFiles/RunUBT脚本取代直接调用 UBT；不再需要PER_MODULE_BOILERPLATE；StructUtils插件已弃用（移至引擎） - UE 5.6：
FString::Appendf强制使用static constexpr格式字符串；GMalloc访问已弃用 - UE 5.7：
FindObject弃用bExactClass，改用EFindObjectFlags
高级模式
Barrier 模块（隔离不兼容的编译器设置）
当第三方库要求设置 bUseRTTI = true 和 bEnableExceptions = true，但你希望尽可能缩小影响范围时，可以创建一个 barrier 模块，通过干净的接口隔离该库：
Plugin/
Source/
ThirdParty/MyLib/ # ModuleType.External (headers + libs)
MyLibBarrier/ # Barrier module (bUseRTTI=true, bEnableExceptions=true)
Public/ -> clean types only, no third-party headers, no UObject.h
Private/ -> wraps third-party includes with BeginIncludes/EndIncludes
MyPlugin/ # Main module, depends on MyLibBarrier (NOT on MyLib directly)
barrier 模块的公共头文件不得包含第三方头文件或触发包含 UObject.h。所有第三方类型都以不透明的 barrier 类型传递。请参阅 AGX Dynamics 文档中的生产环境示例。
通过 UE4CMake 集成 CMake
UE4CMake 插件提供 CMakeTarget.add()，可在 Build.cs 中将 CMake 库作为 UBT 的一部分进行构建：
CMakeTarget.add(Target, this, "TargetName",
Path.Combine(ModuleDirectory, "../Libs/Source"),
"-DCUSTOM_OPTION=ON", false);
它会根据 CMake 输出自动填充 PublicIncludePaths 和 PublicAdditionalLibraries，将源文件注册到 ExternalDependencies 以检测更改，并通过 PRAGMA_PUSH_PLATFORM_DEFAULT_PACKING / PRAGMA_POP_PLATFORM_DEFAULT_PACKING 处理结构体打包。
UnrealMacroNuke（全面清除宏污染）
对于会与 check 之外的许多 UE 宏冲突的库，UnrealMacroNuke 会生成成对的头文件，用于取消定义和重新定义所有冲突宏：
#pragma warning(push)
#pragma warning(disable: <codes>)
#include "UndefineMacros_UE_5.3.h"
#include "third_party/library.hpp"
#include "RedefineMacros_UE_5.3.h"
#pragma warning(pop)
Conan 包管理器集成
conan-ue4cli 包可自动针对 UE 捆绑的依赖项构建第三方库。Build.cs 会调用 conan install，并解析 conanbuildinfo.json 以提取 include 路径、库路径和定义。当 UE 和第三方库依赖同一库的不同版本（例如 zlib、libpng）时，这是解决符号插入问题的关键。
Android APL（Android 打包层）
Android 第三方库需要 APL XML 文件，以部署原生库并集成 Java：
// Build.cs -- Android
AdditionalPropertiesForReceipt.Add("AndroidPlugin",
Utils.MakePathRelativeTo(
Path.Combine(ThirdPartyPath, "LIBRARY_APL.xml"),
Target.RelativeEnginePath));
用于变更检测的 ExternalDependencies
注册外部文件，以便在文件修改时触发重新构建：
ExternalDependencies.Add(Path.Combine(ModuleDirectory, "include", "version.h"));
这样可确保指定文件发生变化时，UBT 会重新生成 makefile，适用于跟踪标头文件或库二进制文件的更新。
AddEngineThirdPartyPrivateStaticDependencies
使用引擎捆绑的库，无需维护自己的副本：
AddEngineThirdPartyPrivateStaticDependencies(Target, "OpenSSL", "libWebSockets", "libcurl", "zlib");
这是使用引擎已附带库的首选方式。