在虚幻引擎中配置模块与构建系统（Build.cs/Targe…

处理 UE 的 Build.cs、Target.cs、模块创建、插件搭建及链接/包含/IWYU 构建错误时，按此流程配置依赖、导出宏与加载阶段。

适用场景

解决思路

1. 开始前先读取 `.agents/ue-project-context.md`（若存在），获取模块名、引擎版本、启用的插件和构建目标，以确定依赖与包含配置。
2. 先确认属于哪种情况：1) 在现有 Build.cs 中配置依赖；2) 从零创建新模块；3) 创建新插件；4) 解决构建错误（链接、包含或 IWYU）；5) 为新构建目标设置 Target.cs。
3. 在模块的 `ModuleName.Build.cs` 中设置 `PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;` 并启用 `bEnforceIWYU = true;`（UE5 新模块推荐）。
4. 把出现在公共头文件中的类型所属模块加入 `PublicDependencyModuleNames`（如 Core、CoreUObject、Engine）。
5. 把仅在 Private/ 的 .cpp 文件中使用的依赖加入 `PrivateDependencyModuleNames`（如 Slate、SlateCore），避免把一切都放进 Public 导致下游模块包含路径膨胀。
6. 对运行时加载但编译期不链接的模块使用 `DynamicallyLoadedModuleNames.Add("OnlineSubsystem");`。
7. 需要暴露额外头文件路径时用 `PublicIncludePaths.Add(Path.Combine(ModuleDirectory, "Public/Interfaces"));`，仅本模块使用则用 `PrivateIncludePaths.Add(...)`；UBT 已自动加入 Public/ 和 Private/，除非有嵌套子目录头文件否则无需手动设置。
8. 为所有需要跨 DLL 边界可见的类、函数、变量加上 `MODULENAME_API` 宏（由 UBT 根据模块目录名大写生成），否则其他模块引用时会出现 unresolved external symbol 链接错误。
9. 在 IWYU 模式下，每个 .cpp 文件先包含自己的 .h，再只包含它直接使用的头文件（如 `#include "MyClass.h"` 后接 `#include "Engine/Actor.h"`）。
10. 除非第三方代码要求，否则设置 `bEnableExceptions = false;` 和 `bUseRTTI = false;`。
11. 对随引擎附带的第三方静态库使用 `AddEngineThirdPartyPrivateStaticDependencies(Target, "zlib", "OpenSSL");`。
12. 在 `Source/ProjectName.Target.cs` 和 `Source/ProjectNameEditor.Target.cs` 中设置 `Type`（Game/Editor/Client/Server/Program）、`DefaultBuildSettings = BuildSettingsVersion.Latest;`、`IncludeOrderVersion = EngineIncludeOrderVersion.Latest;`，并用 `ExtraModuleNames.AddRange(...)` 列出所有要编译的模块。
13. 根据用途选择构建配置：Debug（完整符号、无优化）、DebugGame（引擎优化、游戏调试）、Development（默认）、Test（类似 Shipping 但保留控制台/统计）、Shipping（最终发布、剥离调试）。
14. 在 .uproject 的 `Modules` 数组中登记模块，指定 `Name`、`Type`（Runtime/RuntimeNoCommandlet/Editor/EditorNoCommandlet/Developer/DeveloperTool/CookedOnly/UncookedOnly/RuntimeAndProgram/EditorAndProgram/Program）和 `LoadingPhase`（EarliestPossible/PostSplashScreen/PreEarlyLoadingScreen/PreLoadingScreen/PostConfigInit/PreDefault/Default/PostDefault/PostEngineInit/None）。
15. 创建新模块时按 `Source/MyModule/Public/`、`Source/MyModule/Private/`、`MyModule.Build.cs` 组织目录。
16. 在 `Public/MyModule.h` 中定义继承 `IModuleInterface` 的接口类，提供静态 `Get()`（用 `FModuleManager::LoadModuleChecked`）和 `IsAvailable()`（用 `FModuleManager::Get().IsModuleLoaded`）。
17. 在 `Private/MyModule.cpp` 中实现模块类并重写 `StartupModule()` 和 `ShutdownModule()`，用 `IMPLEMENT_MODULE`（非 gameplay 模块）、`IMPLEMENT_GAME_MODULE`（含 UObject/gameplay 代码）或 `IMPLEMENT_PRIMARY_GAME_MODULE`（主游戏模块）注册；无逻辑时可用 `FDefaultModuleImpl`/`FDefaultGameModuleImpl`。
18. 创建插件时按 `Plugins/MyPlugin/MyPlugin.uplugin`、`Source/MyPlugin/`（含 Public/Private/Build.cs）、可选的 `MyPluginEditor/`、`Content/`、`Resources/Icon128.png` 组织目录。
19. 在 `.uplugin` 中填写 FileVersion、Version、FriendlyName、Description、Category、CanContainContent 等字段，并在 `Modules` 数组中登记运行时与编辑器模块。
20. 插件中运行时模块不得包含编辑器专用头文件：在 Build.cs 中用 `if (Target.bBuildEditor) { PrivateDependencyModuleNames.Add("UnrealEd"); }` 条件添加，代码中用 `#if WITH_EDITOR` 保护。
21. 编辑器模块的 Build.cs 中把 UnrealEd 加入 PublicDependencyModuleNames，并把运行时模块加入 PrivateDependencyModuleNames。
22. 区分引擎插件（`Engine/Plugins/`，对该引擎安装的所有项目可用）与项目插件（`YourProject/Plugins/`，随项目走）；同名时项目插件优先。
23. 内容型插件不设 Source/ 目录、不在 .uplugin 中写 Modules 数组，只含 Content/ 和 Resources/，并设置 `"CanContainContent": true`。
24. 注意 launcher（二进制）安装只含预构建的引擎模块二进制，依赖未预构建的引擎模块会导致 LNK1104；GitHub 源码构建暴露所有引擎模块，可用 `Target.LinkType` 条件包含仅源码构建可用的依赖。
25. 解决构建错误：LNK2019 通常是缺少依赖或缺少 `MODULENAME_API`；C1083 通常是缺少依赖或 IWYU 下包含路径错误；IWYU 违规需让每个文件直接包含其使用的所有头文件；循环依赖可抽取共享接口模块或改用 `DynamicallyLoadedModuleNames`。
26. 在运行时模块中用 `#if WITH_EDITOR` 和 Build.cs 中的 `if (Target.bBuildEditor)` 保护编辑器专用代码，避免 Shipping/Server 构建失败。
27. 避免反模式：不要把一切放进 PublicDependencyModuleNames；不要漏掉导出符号的 `MODULENAME_API`；不要在 IWYU 下依赖传递包含；不要无保护地从运行时模块引用编辑器模块；不要用错 LoadingPhase（注册资产类型太晚会启动时报缺失类型，必要时用 PreDefault 或 PostConfigInit）；不要忘记把模块加入 .uproject 或 .uplugin。

适用边界 · 注意事项

• 不涉及虚幻引擎项目（不使用 UBT、Build.cs、Target.cs、.uproject/.uplugin）时。
• 仅处理 UObject 宏（UCLASS/UPROPERTY/UFUNCTION）、反射或 UHT 头文件规则时，应改用 ue-cpp-foundations 技能。
• 没有安装虚幻引擎或无法访问引擎源码/预构建二进制时，无法实际验证依赖与链接配置。