第2章模块系统详解

模块系统详解：模块定义、模块生命周期、模块依赖、模块加载顺序

好，咱们今天来聊聊 Unreal 的模块系统。说实话，这是整个插件架构的基石。你想想看，一个插件少则几个模块，多则几十个模块，如果连模块怎么定义、怎么加载都搞不清楚，后面写再多代码也是白搭。

我个人习惯把模块比作「乐高积木」。每个模块就是一块独立的积木，有自己的形状、功能和接口。你可以自由组合它们，但前提是——你得知道每块积木该怎么拼、什么时候拼、拼错了会怎样。

模块定义：.Build.cs 文件

每个模块的核心定义文件就是 .Build.cs。这个文件告诉 Unreal 构建系统：我这个模块叫什么、依赖谁、需要哪些路径。

来看一个典型的例子：

// MyPluginModule.Build.cs
using UnrealBuildTool;

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

        PublicDependencyModuleNames.AddRange(new string[]
        {
            "Core",
            "CoreUObject",
            "Engine"
        });

        PrivateDependencyModuleNames.AddRange(new string[]
        {
            "Slate",
            "SlateCore"
        });
    }
}

这里有几个关键点：

PublicDependencyModuleNames：公开依赖。其他模块如果依赖你这个模块，会自动继承这些公开依赖。说白了，就是「我公开了，别人也能用」。
PrivateDependencyModuleNames：私有依赖。只有你自己能用，外部模块看不到。我建议尽量用私有依赖，减少模块间的耦合。
PCHUsage：预编译头设置。嗯，这里要注意，如果你在插件里用了大量第三方库，建议用 UseExplicitOrSharedPCHs，否则编译时间会让你怀疑人生。

小技巧： 我在项目中遇到过一种情况——两个模块互相依赖。这时候别硬来，Unreal 不支持循环依赖。我的做法是抽一个公共接口模块出来，两边都依赖它。

模块生命周期：从加载到卸载

每个模块都有明确的生命周期。Unreal 引擎会按照特定顺序调用这些函数：

阶段	函数	说明
加载	`StartupModule()`	模块被加载时调用。初始化资源、注册对象、启动服务。
运行	（正常逻辑）	模块正常工作，处理各种请求。
卸载	`ShutdownModule()`	模块被卸载时调用。清理资源、注销对象、保存状态。
预卸载	`PreUnloadCallback()`	在 ShutdownModule 之前调用。用于一些紧急清理。

看一个实际例子：

class FMyPluginModule : public IModuleInterface
{
public:
    virtual void StartupModule() override
    {
        // 我习惯在这里注册自定义的 Asset 类型
        // 或者启动后台线程
        UE_LOG(LogTemp, Log, TEXT("MyPluginModule 已启动"));
    }

    virtual void ShutdownModule() override
    {
        // 清理所有分配的资源
        // 关闭线程、释放内存
        UE_LOG(LogTemp, Log, TEXT("MyPluginModule 已关闭"));
    }
};

注意： 我曾经在 ShutdownModule 里忘记释放一个全局单例，结果导致编辑器崩溃。后来我养成了一个习惯——每次卸载模块时，都检查一遍所有静态指针和全局对象。

模块依赖：谁依赖谁？

模块依赖说白了就是「我需要你，你才能工作」。Unreal 的依赖系统是声明式的——你在 .Build.cs 里写清楚，构建系统会自动处理。

依赖关系有三种：

公开依赖：A 依赖 B，且 A 的公开接口里用到了 B 的类型。其他模块如果依赖 A，会自动获得 B。
私有依赖：A 依赖 B，但只在 A 的内部实现里用 B。外部模块看不到这个依赖。
运行时依赖：编译时不依赖，但运行时需要。这种情况比较少见，一般用于动态加载的插件。

举个例子：

// 模块 A 公开依赖 Core、Engine
// 模块 B 公开依赖 A
// 那么模块 B 自动获得 Core、Engine 的访问权限

// 但如果模块 A 私有依赖 Slate
// 模块 B 依赖 A 时，无法直接使用 Slate 的类型

我个人建议：能用私有依赖就别用公开依赖。为什么呢？因为公开依赖会形成「依赖链」，一旦链上某个模块改了，所有下游模块都得重新编译。你想想看，一个大型项目里，这种连锁反应有多可怕。

模块加载顺序：谁先谁后？

模块加载顺序是个容易踩坑的地方。Unreal 的加载顺序大致如下：

引擎核心模块：Core、CoreUObject、Engine 等。这些是基础，必须先加载。
项目模块：你的游戏或编辑器项目里的模块。
插件模块：所有启用的插件模块。

但插件内部的模块顺序呢？这就看依赖关系了。Unreal 会做拓扑排序——先加载被依赖的模块，再加载依赖它的模块。

举个例子：

// 插件 MyPlugin 有三个模块：
// - MyPlugin_Core（无依赖）
// - MyPlugin_UI（依赖 MyPlugin_Core）
// - MyPlugin_Network（依赖 MyPlugin_Core）

// 加载顺序：
// 1. MyPlugin_Core
// 2. MyPlugin_UI 或 MyPlugin_Network（两者无依赖关系，顺序不确定）

  关键点： 如果两个模块没有依赖关系，它们的加载顺序是不确定的！我曾经在项目里遇到过一个 bug——模块 A 和模块 B 都依赖模块 C，但 A 和 B 之间没有依赖。结果 A 在 StartupModule 里尝试访问 B 的接口，但 B 还没加载，直接崩溃。解决方案很简单：要么让 A 依赖 B，要么在 A 里延迟访问 B 的接口。

避坑指南：我踩过的那些坑

做模块系统这么多年，我总结了几条血泪教训：

不要在 StartupModule 里做耗时操作：编辑器启动时，所有模块的 StartupModule 是串行执行的。你卡一秒，整个编辑器就卡一秒。我见过有人在这里加载几百兆的配置文件，结果启动时间从 10 秒变成 3 分钟。
小心静态初始化顺序：C++ 的静态变量初始化顺序是不确定的。如果你在模块的全局变量里依赖另一个模块的全局变量，大概率会出问题。我的做法是：用 StartupModule 来初始化所有全局状态。
模块卸载时要彻底：ShutdownModule 里不仅要释放内存，还要注销所有注册的回调、委托、消息处理器。否则编辑器关闭时可能会触发野指针。
依赖关系别搞太复杂：我见过一个插件有 20 多个模块，依赖关系像蜘蛛网一样。后来重构时，我把它们合并成 5 个模块，代码反而更清晰了。记住：模块是组织代码的工具，不是炫技的手段。

总结一下

模块系统是 Unreal 插件开发的骨架。你只要记住三点：

定义：用 .Build.cs 声明模块的依赖和配置。
生命周期：在 StartupModule 和 ShutdownModule 里做好初始化和清理。
加载顺序：依赖关系决定了加载顺序，没有依赖的模块顺序不确定，别做假设。

嗯，差不多就这些。下一章咱们会深入模块间的通信机制，到时候再聊。

📚 课程目录

模块系统详解：模块定义、模块生命周期、模块依赖、模块加载顺序

模块定义：.Build.cs 文件

模块生命周期：从加载到卸载

模块依赖：谁依赖谁？

模块加载顺序：谁先谁后？

避坑指南：我踩过的那些坑

总结一下