ue-module-build-system

Name: ue-module-build-system
Author: quodsoler

github.com/quodsoler开发4191.3k 次安装4 周前更新

代码仓库

关于 ue-module-build-system

面向 Unreal Engine 5.8 开发者的技能，涵盖 UnrealBuildTool 模块与目标规则、项目和插件描述符，以及模块注册。还提供依赖配置、模块创建和编译错误排查方面的指导。

主要功能

01讲解 `Build.cs` 依赖与包含路径
02配置 `Target.cs` 和构建选项
03说明 `.uproject` 与 `.uplugin` 设置
04指导创建和注册模块及插件
05排查 UBT、UHT 和链接错误

适用场景

01调整模块依赖和头文件包含设置
02创建 UE 模块或插件
03诊断构建、链接或模块加载故障

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/quodsoler/unreal-engine-skills --skill ue-module-build-system

安装后在 Claude Code 中输入/ue-module-build-system确认已加载。

附带文件references/build-cs-reference.mdreferences/common-build-errors.md

详细介绍

UE 模块和构建系统

目标引擎：UE 5.8。以下 API 已根据 5.8 头文件和 UnrealBuildTool 源码验证；旧形式列在“已弃用 — 请勿使用”下。

本技能涵盖 UnrealBuildTool（UBT）的 ModuleRules（*.Build.cs）和 TargetRules（*.Target.cs）、.uproject 和 .uplugin 描述文件、模块注册（Modules/ModuleManager.h 中的 IModuleInterface 和 IMPLEMENT_MODULE，模块 Core）、插件发现（Interfaces/IPluginManager.h 中的 IPluginManager，模块 Projects），以及这些文件可能导致的编译器、链接器、UHT 和 UBT 错误。

上下文

如果 .agents/ue-project-context.md 存在，请阅读它（模块名称、约定、已启用的插件、GAS/网络设置）。如果文件不存在，也请继续。

根据请求和代码库确定相关领域。只有当两种合理的理解会导致不同代码时，才提出问题。

请求涉及……	转到
现有 `Build.cs` 中的依赖、包含路径、PCH、警告	Build.cs 结构
`Target.cs`、`BuildSettingsVersion`、`IncludeOrderVersion`、目标类型	Target.cs
`.uproject`、模块 `Type`、`LoadingPhase`、启用插件	.uproject 文件
添加模块（`IMPLEMENT_MODULE`、模块接口、`StartupModule`）	创建新模块
添加插件（`.uplugin`、运行时模块和编辑器模块、依赖项）	创建插件
“要使用类型 X，我应该添加哪个模块？”	类型由哪个模块提供
LNK2019、C1083、UHT、UBT 或运行时模块加载错误	解决构建错误

Build.cs 结构

每个模块都有一个 <ModuleName>.Build.cs，与其 Public/ 和 Private/ 文件夹并列。类名必须与模块名相同。

// Source/MyGame/MyGame.Build.cs
using UnrealBuildTool;

public class MyGame : ModuleRules
{
    public MyGame(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        // Types from these modules appear in this module's Public/ headers
        PublicDependencyModuleNames.AddRange(new string[]
        {
            "Core",
            "CoreUObject",
            "Engine",
            "InputCore",
            "EnhancedInput",
        });

        // Used only inside Private/ .cpp files; not re-exported downstream
        PrivateDependencyModuleNames.AddRange(new string[]
        {
            "Slate",
            "SlateCore",
            "UMG",
        });

        // Loaded through FModuleManager at runtime, never linked
        DynamicallyLoadedModuleNames.Add("OnlineSubsystem");
    }
}

公有依赖与私有依赖

字段	使用场景
`PublicDependencyModuleNames`	模块中的某个类型出现在你的某个 Public/ 头文件中（基类、成员、参数、返回类型、`UPROPERTY`）。下游模块会继承包含路径。
`PrivateDependencyModuleNames`	仅在 Private/ `.cpp` 文件或私有头文件中使用该模块。
`PublicIncludePathModuleNames` / `PrivateIncludePathModuleNames`	需要该模块的头文件（前向声明、内联类型），但不需要链接其中的任何内容。
`DynamicallyLoadedModuleNames`	你自行调用 `FModuleManager::Get().LoadModule(...)`；UBT 只负责确保该模块已构建。

从私有依赖开始，仅当公有头文件要求时才提升为公有依赖。所有依赖都设为公有会增加每个下游模块的编译时间。

包含路径和 IWYU

UBT 会自动发现 Public/、Internal/ 和 Private/；PublicIncludePaths/PrivateIncludePaths 仅用于额外的子文件夹。在 BuildSettingsVersion.V2 及更高版本下，bLegacyPublicIncludePaths 为 false，因此其他模块的头文件会相对于该模块的 Public/（或 Classes/）根目录编写：

// Source/MyGame/Private/MyActor.cpp
#include "MyActor.h"                          // own header first
#include "GameFramework/Actor.h"              // Engine/Classes/GameFramework/Actor.h
#include "Engine/World.h"                     // only what this file uses directly
#include "GameFramework/PlayerController.h"

IWYUSupport 默认值为 IWYUSupport.Full，这允许 UnrealBuildTool -Mode=IWYU 重写模块的包含项；对于你手动维护的代码，请设置 IWYUSupport = IWYUSupport.KeepAsIs。

API 导出宏

UBT 会定义 <MODULENAME>_API（模块名称大写后加 _API）：编译模块时为 DLLEXPORT，导入模块时为 DLLIMPORT；单体构建会将其定义为空。其他模块引用的任何内容都需要此宏：

// Source/MyGame/Public/MyGameTypes.h
#pragma once
#include "CoreMinimal.h"

class MYGAME_API FMyGameTypes
{
public:
    void DoSomething();
};

MYGAME_API void MyGameFreeFunction();

引擎头文件会在文件顶部用 #define UE_API CORE_API 包装此宏，并在底部使用 #undef UE_API（Async/Mutex.h）。这是仅限引擎的约定；项目代码应直接编写 MYGAME_API。被其他模块引用的类缺少 MYGAME_API，是导致 LNK2019 最常见的原因。

警告和编译器标志

bWarningsAsErrors = true;
CppCompileWarningSettings.ShadowVariableWarningLevel = WarningLevel.Error;   // MSVC C4456/C4458/C4459
CppCompileWarningSettings.UnsafeTypeCastWarningLevel = WarningLevel.Warning; // MSVC C4244/C4838
CppCompileWarningSettings.DeprecationWarningLevel = WarningLevel.Error;      // MSVC C4996 from UE_DEPRECATED

bEnableExceptions = false;               // default; enable only for third-party code that throws
bUseRTTI = false;                        // default; enable only for third-party dynamic_cast/typeid
CppStandard = CppStandardVersion.Cpp20;  // per-module override; the engine default is Cpp20
bUseUnity = false;                       // opt this module out of unity builds

// Engine-bundled third-party libraries (Engine/Source/ThirdParty/<Name>/<Name>.Build.cs)
AddEngineThirdPartyPrivateStaticDependencies(Target, "zlib", "OpenSSL", "libcurl");

所有 ModuleRules 字段、RuntimeDependencies API、平台条件以及完整的引擎模块表，都位于 references/build-cs-reference.md。

Target.cs

Source/MyGame.Target.cs 和 Source/MyGameEditor.Target.cs。类必须命名为 <FileName>Target；否则 UBT 会报错："Expecting to find a type to be declared in a target rules named 'MyGameTarget'"。

// Source/MyGame.Target.cs
using UnrealBuildTool;
using System.Collections.Generic;

public class MyGameTarget : TargetRules
{
    public MyGameTarget(TargetInfo Target) : base(Target)
    {
        Type = TargetType.Game;
        DefaultBuildSettings = BuildSettingsVersion.V7;
        IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_8;
        ExtraModuleNames.Add("MyGame");
    }
}

Source/MyGameEditor.Target.cs 声明 MyGameEditorTarget，其主体相同，但将 Type = TargetType.Editor; 和 ExtraModuleNames.AddRange(new string[] { "MyGame", "MyGameEditor" }); 作为例外。

5.8 项目模板会生成 BuildSettingsVersion.V7（Latest 也等于 V7）。请固定使用明确的值；每次升级引擎时，Latest 的含义都会改变。
EngineIncludeOrderVersion.Unreal5_8 会选择 UE_ENABLE_INCLUDE_ORDER_DEPRECATED_IN_5_8 定义，使已移除的引擎隐式包含仍可供代码使用。Unreal5_1–Unreal5_5 已标记为 [Obsolete]，且不受支持；Unreal5_6 已弃用。模块可通过 ModuleRules.IncludeOrderVersion 覆盖此设置。

`BuildSettingsVersion`	启用的默认设置
`V2`	`PCHUsage = UseExplicitOrSharedPCHs`、`bLegacyPublicIncludePaths = false`
`V3`	`bLegacyParentIncludePaths = false`
`V4`	`CppStandard` 默认值变为 `Cpp20`，`WindowsPlatform.bStrictConformanceMode = true`
`V5`	`bValidateFormatStrings = true`
`V6`	`WindowsPlatform.bStrictInlineConformance = true`、`UndefinedIdentifierWarningLevel = Error`
`V7`（= `Latest`）	`ReturnTypeWarningLevel`、`DanglingWarningLevel`、`UnreachableCodeWarningLevel` = `Error`

`TargetType`	构建内容
`Game`	独立游戏可执行文件
`Editor`	编辑器构建；包含 `Editor` 类型的模块
`Client`	不含仅服务器代码的联网客户端
`Server`	专用服务器，不含渲染器
`Program`	独立工具（需要选择 `bCompileAgainstEngine`/`bCompileAgainstCoreUObject`）

构建配置（UnrealTargetConfiguration）：Debug、DebugGame（引擎已优化，游戏未优化）、Development（默认）、Test、Shipping。实用的目标开关：bUseUnityBuild、bUseLoggingInShipping、bUseChecksInShipping、bWithLiveCoding、LinkType = TargetLinkType.Monolithic、GlobalDefinitions/ProjectDefinitions，以及用于“忽略对共享构建环境的违规（例如，编辑器目标修改定义）”的 bOverrideBuildEnvironment = true。

.uproject 文件

{
    "FileVersion": 3,
    "EngineAssociation": "5.8",
    "Category": "",
    "Description": "",
    "Modules": [
        {
            "Name": "MyGame",
            "Type": "Runtime",
            "LoadingPhase": "Default",
            "AdditionalDependencies": [ "Engine", "AIModule", "UMG" ]
        },
        { "Name": "MyGameEditor", "Type": "Editor", "LoadingPhase": "Default" }
    ],
    "Plugins": [
        { "Name": "ModelingToolsEditorMode", "Enabled": true, "TargetAllowList": [ "Editor" ] },
        { "Name": "StateTree", "Enabled": true },
        { "Name": "MyPlugin", "Enabled": true, "Optional": true }
    ]
}

AdditionalDependencies 是描述符中“构建此模块所需的其他依赖项列表”。插件引用支持 Name、Enabled、Optional、TargetAllowList/TargetDenyList、PlatformAllowList/PlatformDenyList、TargetConfigurationAllowList。

模块类型（`ModuleHostType`）

`Type`	加载条件
`Runtime`	使用 UE 运行时的任何目标（游戏代码的默认类型）
`RuntimeNoCommandlet`	除命令let外的任何目标
`RuntimeAndProgram`	任何目标或程序
`CookedOnly` / `UncookedOnly`	仅已烹制构建 / 仅未烹制（编辑器、PIE）构建 — `UncookedOnly` 是 Blueprint 节点（K2Node）模块的类型
`Developer`	仅在启用开发者工具支持时加载（已弃用：请使用 `DeveloperTool`）
`DeveloperTool`	启用了 `bBuildDeveloperTools` 的任何目标
`Editor` / `EditorNoCommandlet`	仅编辑器 / 编辑器，但不包括命令let
`EditorAndProgram`	编辑器或程序目标
`Program`	仅程序目标
`ServerOnly` / `ClientOnly` / `ClientOnlyNoCommandlet`	仅服务器 / 客户端、命令let和编辑器 / 客户端和编辑器
`External`	不会自动加载；仅供引用

加载阶段（`ModuleLoadingPhase`）

`LoadingPhase`	时间
`EarliestPossible`	插件可以加载时立即执行（`GConfig` 已存在）
`PostConfigInit`	配置系统启动后立即执行；仅用于非常底层的钩子
`PostSplashScreen`	系统启动画面后的第一个屏幕
`PreEarlyLoadingScreen`	`PostConfigInit` 之后、CoreUObject 初始化之前
`PreLoadingScreen`	加载屏幕触发之前
`PreDefault`	紧接在 `Default` 之前——其他模块需要的资源类型、自定义类
`Default`	引擎初始化期间，在游戏模块加载后（大多数模块）
`PostDefault`	紧接在 `Default` 之后
`PostEngineInit`	引擎完全初始化后
`None`	从不自动加载；使用 `FModuleManager::Get().LoadModule()`

创建新模块

Source/
  MyModule/
    MyModule.Build.cs
    Public/
      IMyModule.h           (public module interface, optional)
      MyModuleTypes.h
    Private/
      MyModule.cpp          (IMPLEMENT_MODULE lives here)
      MyModuleTypes.cpp

// Source/MyModule/Public/IMyModule.h
#pragma once
#include "Modules/ModuleManager.h"

class IMyModule : public IModuleInterface
{
public:
    static IMyModule& Get()
    {
        return FModuleManager::LoadModuleChecked<IMyModule>("MyModule");
    }

    static bool IsAvailable()
    {
        return FModuleManager::Get().IsModuleLoaded("MyModule");
    }
};

// Source/MyModule/Private/MyModule.cpp
#include "IMyModule.h"

class FMyModule : public IMyModule
{
public:
    virtual void StartupModule() override
    {
        // Load dependent modules, register settings, delegates, asset types
    }

    virtual void ShutdownModule() override
    {
        // Unregister in reverse order; dependencies loaded in StartupModule are still alive
    }
};

IMPLEMENT_MODULE(FMyModule, MyModule)

宏（`Modules/ModuleManager.h`）	用途
`IMPLEMENT_MODULE(FMyModule, MyModule)`	不包含游戏玩法类的模块（工具、编辑器、库）
`IMPLEMENT_GAME_MODULE(FMyModule, MyModule)`	包含游戏玩法 `UCLASS` 的模块；展开为 `IMPLEMENT_MODULE`
`IMPLEMENT_PRIMARY_GAME_MODULE(FDefaultGameModuleImpl, MyGame, "MyGame")`	每个游戏恰好使用一次；在单体构建中，它会通过 `UE_PROJECT_NAME` 定义项目名称；第三个参数是 `DEPRECATED_GameName`（`ModuleManager.h:1100`），且未使用

FDefaultModuleImpl 和 FDefaultGameModuleImpl 是为没有启动逻辑的模块准备的现成类；FDefaultGameModuleImpl::IsGameModule() 返回 true，因此热重载工具会将其视为游戏代码。第二个宏参数必须与 Build.cs 模块名称一致；宏的单体和模块化形式都会使用 UE_STATIC_ASSERT_WARN（ModuleManager.h:950、:968）将其与 UE_MODULE_NAME 比较，若名称不匹配，会发出类似弃用提示的“Module name mismatch”警告；仅在 bWarningsAsErrors 下才会成为错误。IModuleInterface 的其他钩子：PreUnloadCallback()、PostLoadCallback()、SupportsDynamicReloading()、SupportsAutomaticShutdown()。

接着，在以下三个位置注册模块：.uproject（或 .uplugin）的 Modules 数组；每个需要构建该模块的 Target.cs 中的 ExtraModuleNames；以及使用该模块的模块的依赖列表。仅限编辑器的模块（"Type": "Editor"，在 if (Target.bBuildEditor) 中调用 PrivateDependencyModuleNames.Add("UnrealEd")）由 ue-editor-tools 介绍。

创建插件

Plugins/
  MyPlugin/
    MyPlugin.uplugin
    Resources/Icon128.png
    Content/                    (only when CanContainContent is true)
    Source/
      MyPlugin/
        MyPlugin.Build.cs
        Public/  Private/MyPluginModule.cpp
      MyPluginEditor/
        MyPluginEditor.Build.cs
        Public/  Private/MyPluginEditorModule.cpp

{
    "FileVersion": 3,
    "Version": 1,
    "VersionName": "1.0",
    "FriendlyName": "My Plugin",
    "Description": "Does something useful.",
    "Category": "Gameplay",
    "CreatedBy": "MyStudio",
    "CreatedByURL": "",
    "DocsURL": "",
    "MarketplaceURL": "",
    "SupportURL": "",
    "EnabledByDefault": false,
    "CanContainContent": true,
    "IsBetaVersion": false,
    "IsExperimentalVersion": false,
    "Installed": false,
    "Modules": [
        { "Name": "MyPlugin", "Type": "Runtime", "LoadingPhase": "PreDefault" },
        { "Name": "MyPluginEditor", "Type": "Editor", "LoadingPhase": "Default", "PlatformAllowList": [ "Win64", "Mac", "Linux" ] }
    ],
    "Plugins": [
        { "Name": "GameplayAbilities", "Enabled": true },
        { "Name": "StateTree", "Enabled": true, "Optional": true }
    ]
}

在 Plugins 中声明所有依赖其模块的插件；否则，UBT 会发出警告：“Plugin 'MyPlugin' does not list plugin 'X' as a dependency, but module 'MyPlugin' depends on module 'Y'”。
IsExperimentalVersion / IsBetaVersion 用于设置编辑器显示的成熟度；EnabledByDefault: true 会在每个项目中启用该插件，无需在 .uproject 中添加条目。
纯内容插件完全省略 Modules，并保留 "CanContainContent": true。
游戏功能插件（UGameFeatureData、actions）由 ue-game-features 介绍。

// Plugins/MyPlugin/Source/MyPlugin/MyPlugin.Build.cs — runtime module
using UnrealBuildTool;

public class MyPlugin : ModuleRules
{
    public MyPlugin(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
        PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "GameplayAbilities" });
    }
}

// Plugins/MyPlugin/Source/MyPluginEditor/MyPluginEditor.Build.cs — editor module
using UnrealBuildTool;

public class MyPluginEditor : ModuleRules
{
    public MyPluginEditor(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
        PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine" });
        PrivateDependencyModuleNames.AddRange(new string[] { "MyPlugin", "UnrealEd", "ToolMenus", "PropertyEditor" });
    }
}

运行时模块绝不包含编辑器头文件；使用 #if WITH_EDITOR 限定编辑器代码，并使用 if (Target.bBuildEditor) 限定编辑器依赖项。

引擎插件与项目插件： Engine/Plugins/ 由该安装上的所有项目共享；<Project>/Plugins/ 随项目一起分发，并在名称冲突时优先。已安装（Launcher）引擎只提供预编译的引擎模块：依赖未预编译的引擎模块会失败，并显示“Missing precompiled manifest for 'X'. This module can not be referenced in a monolithic precompiled build, remove this reference or migrate to a fully compiled source build.”。

此类型由哪个模块提供

添加到 `*DependencyModuleNames`	用途	要启用的插件
`Core`	`FString`、`TArray`、`FName`、`UE_LOG`、`FModuleManager`	—
`CoreUObject`	`UObject`、`UClass`、`FInstancedStruct`、反射	—
`Engine`	`AActor`、`UActorComponent`、`UWorld`、`UGameInstance`、`UAudioComponent`	—
`InputCore`	`FKey`、`EKeys`	—
`EnhancedInput`	`UInputAction`、`UInputMappingContext`、`UEnhancedInputComponent`	`EnhancedInput`
`GameplayTags`	`FGameplayTag`、`FGameplayTagContainer`、`UGameplayTagsManager`	—
`GameplayTasks`	`UGameplayTask`、`UGameplayTasksComponent`	—
`GameplayAbilities`	`UAbilitySystemComponent`、`UGameplayAbility`、`UGameplayEffect`	`GameplayAbilities`
`NetCore`	`FFastArraySerializer`、推送模型宏	—
`DeveloperSettings`	`UDeveloperSettings`	—
`Slate`、`SlateCore`	`SWidget`、`SCompoundWidget` / `FSlateBrush`、`FSlateColor`	—
`UMG`	`UUserWidget`、`UButton`、`UTextBlock`	—
`CommonUI`、`CommonInput`	`UCommonActivatableWidget`、`UCommonButtonBase`	`CommonUI`
`ModelViewViewModel`	`UMVVMViewModelBase`、`UMVVMView`	`ModelViewViewModel`（5.8 中为 Beta）
`AIModule`、`NavigationSystem`	`AAIController`、`UBehaviorTree` / `UNavigationSystemV1`	—
`StateTreeModule`、`GameplayStateTreeModule`	`UStateTree`、`FStateTreeTaskBase` / `UStateTreeComponent`	`StateTree`、`GameplayStateTree`
`MassEntity`、`MassCore`、`MassSignals`	`FMassEntityManager`、`UMassProcessor` / `FTransformFragment` / `UMassSignalSubsystem`	—（核心模块）
`Niagara`	`UNiagaraComponent`、`UNiagaraSystem`、`UNiagaraFunctionLibrary`	`Niagara`
`PCG`	`UPCGComponent`、`UPCGGraph`、`UPCGSettings`	`PCG`
`Mover`	`UMoverComponent`、`UCharacterMoverComponent`	`Mover`（5.8 中为 Experimental）
`GameplayCameras`	`UGameplayCameraComponent`、`UCameraAsset`	`GameplayCameras`（5.8 中为 Experimental）
`LevelSequence`、`MovieScene`	`ULevelSequence`、`ULevelSequencePlayer` / `UMovieScene`	—
`PhysicsCore`、`Chaos`	`UPhysicalMaterial` / Chaos 求解器类型	—
`ProceduralMeshComponent`	`UProceduralMeshComponent`	`ProceduralMeshComponent`
`GeometryScriptingCore`、`GeometryFramework`	`UGeometryScriptLibrary_MeshPrimitiveFunctions` / `UDynamicMesh`	`GeometryScripting`
`AudioExtensions`	`IAudioParameterControllerInterface`、`FAudioParameter`	—

完整表格（包括编辑器和网络模块）请参阅 references/build-cs-reference.md。

解决构建错误

错误文本	首先检查
`LNK2019 unresolved external symbol` / `LNK2001`	模块未添加到 `*DependencyModuleNames`，或者被引用的类缺少 `MYGAME_API`
`C1083: Cannot open include file`	模块未添加到依赖项中，或者包含路径不是相对于模块的 `Public/` 根目录编写的
`#include found after .generated.h file`	将 `#include "MyClass.generated.h"` 移到最后一个包含项
`Expected a GENERATED_BODY() at the start of the class`	在 `UCLASS`/`USTRUCT` 的主体内第一行添加 `GENERATED_BODY()`
`Could not find definition for module 'X'`	找不到 `X.Build.cs`，或者 `.uproject`/`ExtraModuleNames` 中的模块名称错误
`Circular dependency for 'X.Build.cs' detected`	提取一个共享模块，或将其中一侧改为 `DynamicallyLoadedModuleNames`
`Missing precompiled manifest for 'X'`	已安装的引擎无法编译该引擎模块；移除该依赖，或使用源码构建版本
`Plugin 'X' failed to load because module 'Y' could not be found`	重新构建插件；该模块未针对当前目标编译
`Module 'X' not found - its StaticallyLinkedModuleInitializers function is null`	单体构建未链接该模块；将其添加到 `ExtraModuleNames` 或 `.uplugin`

完整错误消息、原因、MSVC 警告级别对应关系、Live Coding 限制和烹饪失败详见 references/common-build-errors.md。

已弃用 — 请勿使用

不要使用	在 5.8 中使用	来源
`bEnforceIWYU = true`	`IWYUSupport = IWYUSupport.Full`（已是默认值）	`Configuration/Rules/ModuleRules.Obsolete.cs` 中的 `[Obsolete("Deprecated in UE5.2 - Use IWYUSupport instead.")]`
`bUseAVX = true`	`MinCpuArchX64 = MinimumCpuArchitectureX64.AVX2`	`ModuleRules.Obsolete.cs` 中的 `[Obsolete("bUseAVX is obsolete ... replace with MinCpuArchX64")]`
在 `ModuleRules`/`TargetRules` 上设置 `ShadowVariableWarningLevel = WarningLevel.Error`	`CppCompileWarningSettings.ShadowVariableWarningLevel`	`ModuleRules.Obsolete.cs`、`TargetRules.Obsolete.cs` 中的 `[Obsolete("Deprecated in UE5.6 ...")]`
直接设置 `UnsafeTypeCastWarningLevel = ...`	`CppCompileWarningSettings.UnsafeTypeCastWarningLevel`	`ModuleRules.Obsolete.cs`、`TargetRules.Obsolete.cs` 中的 `[Obsolete("Deprecated in UE5.6 ...")]`
`bEnableUndefinedIdentifierWarnings` / `bUndefinedIdentifierErrors`	`CppCompileWarningSettings.UndefinedIdentifierWarningLevel`	分两步迁移：5.5 将它们移至规则类上的 `UndefinedIdentifierWarningLevel`，5.6 又将其移入 `CppCompileWarningSettings`。`ModuleRules.Obsolete.cs`、`TargetRules.Obsolete.cs` 中的 `[Obsolete(...)]`
在 `TargetRules` 上设置 `DeprecationWarningLevel = ...`	`CppCompileWarningSettings.DeprecationWarningLevel`	`TargetRules.Obsolete.cs` 中的 `[Obsolete("Deprecated in UE5.6 ...")]`
`bUsesSteam = true`	删除；此标志不起作用	`TargetRules.Obsolete.cs` 中的 `[Obsolete("Deprecated in UE5.5 - No longer used in engine.")]`
`bCompileChaos`、`bUseChaos`、`bCompilePhysX`、`bCompileAPEX`、`bCompileNvCloth`	删除；Chaos 始终启用	`TargetRules.Obsolete.cs` 中的 `[Obsolete("Deprecated in UE5.1 ...")]`
`bDisableDebugInfo = true`	`DebugInfo = DebugInfoMode.None`	`TargetRules.Obsolete.cs` 中的 `[Obsolete("Deprecated in UE5.4 - Replace with TargetRules.DebugInfo")]`
`bUseFastPDBLinking = true`	删除	`TargetRules.Obsolete.cs` 中的 `[Obsolete("Deprecated in UE5.7 - No longer recommended")]`
`IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_1` … `Unreal5_5`	`EngineIncludeOrderVersion.Unreal5_8`	`Configuration/Rules/TargetRules.cs` 中的 `[Obsolete("The Unreal 5.5 include order is unsupported.")]`
`EngineIncludeOrderVersion.Unreal5_6`	`Unreal5_8`	`TargetRules.cs` 中的 `[Obsolete("... deprecated and will be unsupported in 5.9.")]`
描述符中的 `"WhitelistPlatforms"`、`"BlacklistPlatforms"`、`"WhitelistTargets"`	`"PlatformAllowList"`、`"PlatformDenyList"`、`"TargetAllowList"`	`Configuration/Descriptors/ModuleDescriptor.cs` 中的已弃用字段回退读取器
`"Type": "Developer"`	`"Type": "DeveloperTool"`	`ModuleDescriptor.cs` 中的 "The 'Developer' module type has been deprecated in 4.24"
已发布项目中的 `EngineIncludeOrderVersion.Latest`、`BuildSettingsVersion.Latest`	固定为 `Unreal5_8` / `V7`	UBT 文档："Using Latest comes with a high risk of introducing compile errors"（`TargetRules.cs`）

常见错误

**所有依赖都放在 PublicDependencyModuleNames 中：**所有下游模块都会继承这些包含路径，并更频繁地重新编译。除非某个依赖是 Public/ 头文件所需的，否则应将其保留为私有依赖。

**缺少 MYGAME_API：**该类在自己的模块内可以编译，但从其他模块访问时会出现 LNK2019。将宏添加到类或自由函数的声明上，而不是定义上。

**IMPLEMENT_MODULE 名称不匹配：**在 Build.cs 为 MyModule 的模块中使用 IMPLEMENT_MODULE(FMyModule, MyGameplay)，会产生“Module name mismatch”警告（UE_STATIC_ASSERT_WARN，不是硬错误）；此外，在单体构建中会因链接器查找 IMPLEMENT_MODULE_MyModule 而无法加载。第二个参数是模块名称，不是类名。

**在运行时模块中编写编辑器代码：**在 PublicDependencyModuleNames 中使用 #include "Editor.h" 或 UnrealEd，会导致 Game、Client 和 Server 目标构建失败。请使用 #if WITH_EDITOR 和 if (Target.bBuildEditor) 包裹代码，或将代码移至 Editor 类型的模块。

**模块只在一处注册：**模块必须同时出现在 .uproject/.uplugin 的 Modules 中，以及每个 Target.cs 的 ExtraModuleNames 中；缺少任一项都会导致“Could not find definition for module”，或导致模块始终无法加载。

**注册所用的 LoadingPhase 不正确：**其他模块会在 Default 阶段读取的资产类型、自定义 UClass 注册项和控制台变量必须在 PreDefault 阶段加载。

未声明插件依赖：.uplugin 模块依赖另一个插件的模块，却没有相应的 Plugins 条目，会产生 UBT 依赖警告；禁用另一个插件时还会导致问题。

**依赖传递包含：**某个头文件之所以能编译，是因为 Engine/World.h 恰好包含了它；当较新 IncludeOrderVersion 下该引擎头文件精简了包含项后，编译就会失败。请显式包含所用内容。

**头文件路径错误：**包含 Actor.h 或 Engine/Actor.h 会触发 C1083；该文件位于 Engine/Classes 下的 GameFramework/Actor.h。

基本信息

作者: quodsoler
仓库: quodsoler/unreal-engine-skills
分类: 开发
安装次数: 1,286
GitHub Stars: 419

报告问题

ue-module-build-system

关于 ue-module-build-system

主要功能

适用场景

安装

详细介绍

UE 模块和构建系统

上下文

Build.cs 结构

公有依赖与私有依赖

包含路径和 IWYU

API 导出宏

警告和编译器标志

Target.cs

.uproject 文件

模块类型（`ModuleHostType`）

加载阶段（`ModuleLoadingPhase`）

创建新模块

创建插件

此类型由哪个模块提供

解决构建错误

已弃用 — 请勿使用

常见错误

相关技能

评论

ue-module-build-system

关于 ue-module-build-system

主要功能

适用场景

安装

详细介绍

UE 模块和构建系统

上下文

Build.cs 结构

公有依赖与私有依赖

包含路径和 IWYU

API 导出宏

警告和编译器标志

Target.cs

.uproject 文件

模块类型（ModuleHostType）

加载阶段（ModuleLoadingPhase）

创建新模块

创建插件

此类型由哪个模块提供

解决构建错误

已弃用 — 请勿使用

常见错误

相关技能

评论

模块类型（`ModuleHostType`）

加载阶段（`ModuleLoadingPhase`）