写这篇东西的起因很简单：项目组最近在做一批资产整理和批量修复的工作，每天要在编辑器里反复打开资产、右键、点菜单、跑工具，一套流程又长又容易漏。大家聊起来都在问，能不能把这些操作直接做成一个菜单，点一下就干完。正好UE5的编辑器扩展机制成熟了，我就把“给编辑器加菜单栏”这件事从头到尾捋了一遍，把我实际踩过的坑和最终能跑的代码一起写出来。
这篇文章适合谁？想给美术、策划或者自己提供编辑器快捷入口的开发者；想在编辑器里塞一批内部工具但没写过UI的TA；还有刚接触UE5 C++、想搞清楚编辑器扩展从哪入手的同学。内容不烧脑，但需要你已经会用Visual Studio编译UE5项目，并且有过写Actor或功能模块的基础。
1. 为什么要在UE5编辑器里做菜单栏扩展
1.1 编辑器扩展能解决什么实际问题
编辑器扩展最核心的价值不是“让编辑器多个入口”，而是把工作流里的重复操作固化下来。举个我自己的例子：项目有个需求，要把某一类材质球的贴图路径批量改成新目录。如果没有编辑器菜单，你得先打开某个工具窗口，选择资产列表，填一堆参数，最后点执行。如果这步操作是几个人每天轮流做的，效率和出错率都是问题。
把它做进编辑器菜单栏后，流程就变成了：选中一堆资产，点一下菜单里的“修复贴图路径”，完事。菜单背后跑的可以是纯C++逻辑，也可以调别的插件工具，甚至可以让美术同学自己去点，不需要经过程序员。这就是编辑器扩展最实在的作用——把专业操作封装成普通按钮。
1.2 为什么不直接改引擎源码解决问题
可能有人会想：非要绕一圈做扩展吗？直接改引擎源码不是更快？
改引擎源码这种事，除非你是做引擎二开的长线项目，否则强烈不建议。原因很现实：引擎版本一升级，你的改动就要从新源码里重新合；多人协作时，每个人本地改的源码冲突起来能把人逼疯；更别提把引擎源码改动提交到版本库里，拉代码慢只是小事，万一跟其他人的改动有逻辑冲突，排查成本会呈指数上涨。
而用编辑器模块扩展的方式，代码全部隔离在自己的Module或Plugin里，不碰引擎源码。引擎升级时最多改几个API调用，跟引擎源码彻底解耦。团队协作时也只提交自己的插件代码，其他人拉下来就能编译运行。这是最稳妥、最“正规军”的做法。
1.3 选型：ToolMenus还是老式FExtender
聊到加菜单栏，老玩家可能脱口而出FExtender、FToolBarBuilder。这套东西在UE4时代确实统治了很久，甚至现在很多旧的插件代码还在用。但在UE5里，官方力推的是UToolMenus系统，也就是“ToolMenus”这套UI框架。
两套东西什么区别？我从实际使用体验来对比一下。
| 对比项 | FExtender | UToolMenus |
|---|---|---|
| 内核机制 | 基于Slate事件和委托，手动组合菜单项 | 基于数据驱动的菜单注册表，支持运行时动态构建 |
| 子菜单/级联菜单 | 要手动嵌套FMenuBuilder | 天然支持路径层级，注册即生成子菜单 |
| 右键菜单扩展 | 每个地方单独绑一遍委托 | 统一的注册菜单路径，新增菜单项只加注册代码 |
| 运行时/蓝图可调 | 基本只能C++ | 部分编辑器控制台和蓝图功能能间接参与 |
| 新项目适配度 | UE5还能编译，但官方逐渐边缘化 | UE5官方推荐，社区新插件基本都是它 |
我现在的态度很明确：UE5新写代码一律用UToolMenus。为什么？因为菜单的注册和显示分离了。注册时会生成一个UToolMenu对象，我们可以从外部直接拿到这个菜单再往里加内容，老框架写起来则是一个又一个Builder回调，嵌套多了以后阅读性差很多。
2. 先把编辑器模块建起来
2.1 项目结构：模块还是插件
写编辑器扩展，第一步不是加菜单，是先确认代码放在哪。UE里两种常规做法：一是把代码放游戏项目下的Source目录里，二是独立成一个插件放到项目的Plugins目录。
我个人的建议是这样：如果这个扩展只服务当前项目，那就放在项目模块里，反正代码就那一份。如果你觉得以后可能多个项目复用，那就直接建插件。插件还能打包分发，不用碰撞项目的模块结构。
我这次演示直接用项目内模块的方式，建一个叫做EditorTools的模块。目录结构大概这样：
MyProject/ └─ Source/ ├─ MyProject/ # 游戏主模块 └─ EditorTools/ # 编辑器扩展模块 ├─ EditorTools.Build.cs ├─ Public/ │ └─ EditorTools.h └─ Private/ ├─ EditorToolsModule.h └─ EditorToolsModule.cpp看到Public/Private目录别觉得吓人，这是C++模块的常规划分。实际写菜单功能的头文件可以放Public，实现放Private就行。
2.2 Build.cs与模块声明
编辑器扩展模块和普通游戏模块最大的区别，在Build.cs里已经体现出来了。普通模块引用Core、CoreUObject、Engine这些就够了，编辑器模块至少还要引用UnrealEd、Slate、SlateCore、ToolMenus。
一个能编译的EditorTools.Build.cs长这样：
using UnrealBuildTool; public class EditorTools : ModuleRules { public EditorTools(ReadOnlyTargetRules Target) : base(Target) { PCHUsage = ModuleRules.PCHUsageMode.UseExplicitOrSharedPCHs; PublicIncludePaths.AddRange(new string[] { "EditorTools/Public" }); PrivateIncludePaths.AddRange(new string[] { "EditorTools/Private" }); PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" }); PrivateDependencyModuleNames.AddRange(new string[] { "Slate", "SlateCore", "UnrealEd", "ToolMenus", "EditorStyle", "ContentBrowser" }); } }这里解释几个关键的：
UnrealEd：编辑器核心库，GEditor这类全局对象就在这里。Slate/SlateCore：UE的UI框架。菜单虽然是ToolMenus负责，但底层还是Slate在撑。ToolMenus：我们要用的菜单系统本身。ContentBrowser：后续想操作资产的时候用。比如按目录扫描资产、右键菜单扩展，都离不开它。
闭着眼睛只加前三个也行，但等你后续想调ContentBrowser的API时，就会体验到“编译期找不到头文件”的滋味了。
2.3 Module类骨架与模块加载时机
每个模块都需要一个继承IModuleInterface的类。里面至少实现两个函数：StartupModule和ShutdownModule。听名字就知道，模块被加载时调用前者，模块被卸载时调用后者。
先看基础的骨架代码：
// EditorToolsModule.h #pragma once #include "CoreMinimal.h" class FEditorToolsModule : public IModuleInterface { public: virtual void StartupModule() override; virtual void ShutdownModule() override; };// EditorToolsModule.cpp #include "EditorToolsModule.h" #include "ToolMenus.h" #include "Modules/ModuleManager.h" IMPLEMENT_MODULE(FEditorToolsModule, EditorTools) void FEditorToolsModule::StartupModule() { // 后续注册菜单的代码都放这里 } void FEditorToolsModule::ShutdownModule() { // 退出时清理菜单 }这里面IMPLEMENT_MODULE的作用是把我们的类挂到UE的模块系统上，宏的第二参数EditorTools必须和Build.cs里的模块名以及目录名完全一致，否则编译或加载会报奇怪错误。
关于加载时机，这里有个容易踩坑的点：StartupModule甚至不需要专门指定加载时机，UE默认模块在编辑器启动时加载。但如果你要在菜单注册时依赖某些Subsystem已经初始化，最好在Build.cs的LoadPhase里仔细设置，不过通常默认的PostEngineInit阶段已经能搞定绝大多数场景。
3. 实操：用ToolMenus把菜单挂到主菜单栏
3.1 注册一个顶级菜单
现在到了重头戏，注册菜单。
UE5的主菜单栏结构是用路径表达的。主菜单栏本身是LevelEditor.MainMenu，它的下一层是各个顶级菜单，比如LevelEditor.MainMenu.File、LevelEditor.MainMenu.Edit、LevelEditor.MainMenu.Window、LevelEditor.MainMenu.Tools等等。ToolMenus的注册规则就是：你注册一个带点的新路径，它就会在对应层级挂一个新的菜单节点。
所以，如果我想在顶部菜单栏新增一个名为Tools的子菜单，但跟引擎默认那个区分开，我可以注册一个叫LevelEditor.MainMenu.CustomTools的菜单。
void FEditorToolsModule::StartupModule() { // 注册一个主菜单栏下的新顶级菜单 UToolMenu* Menu = UToolMenus::Get()->RegisterMenu("LevelEditor.MainMenu.CustomTools"); }先把代码写成这样，编译运行后你会发现顶部菜单栏多了一个叫CustomTools的菜单，点开里面是空的，什么都没有。不用慌，这是正常的，因为UToolMenu对象已经创建，只是还没往里塞内容。
菜单的显示名默认就是注册路径里最后一段，这里显示为“CustomTools”。如果你嫌它丑，后续可以考虑通过本地化目录把显示名翻译成一个顺眼的词，或者注册一个带空格的路径。总之，名字问题是最不值钱的，先把功能跑通更重要。
3.2 给菜单塞内容
空菜单没有意义。接下来的步骤：给这个菜单添加一个Section，然后在Section里挂真正的菜单项。
为什么要分Section？因为菜单一大，项目之间的分隔条可以让结构清晰。比如一个菜单里既有“资产工具”又有“窗口操作”，用两个Section分开，视觉上自然有一条分割线。
void FEditorToolsModule::StartupModule() { UToolMenu* Menu = UToolMenus::Get()->RegisterMenu("LevelEditor.MainMenu.CustomTools"); // 添加一个节，名字随便起，显示文字可以自定义 FToolMenuSection& MainSection = Menu->AddSection("MainSection", NSLOCTEXT("EditorTools", "MainSectionLabel", "我的工具")); // 添加第一个菜单项 MainSection.AddMenuEntry( "FixMaterialPath", NSLOCTEXT("EditorTools", "FixMaterialPathLabel", "修复贴图路径"), NSLOCTEXT("EditorTools", "FixMaterialPathToolTip", "批量把选中材质的贴图路径重定向到新目录"), FSlateIcon(), FToolMenuEntry::ExecuteAction(FExecuteAction::CreateLambda([]() { // 这里放真正的业务逻辑 UE_LOG(LogTemp, Log, TEXT("修复贴图路径被点击了")); })) ); }这段代码干了几件事：
AddSection：给CustomTools菜单创建一个叫MainSection的Section，显示名称叫“我的工具”。AddMenuEntry：在Section里挂一个菜单条目。FSlateIcon()：创建一个空图标，表示该项没有图标。FToolMenuEntry::ExecuteAction：封装点击后的回调函数。我这里用Lambda先打一行日志，验证功能通没通。
编译启动编辑器，点击顶部菜单栏的CustomTools，你会看到“我的工具”这个Section下面出现了“修复贴图路径”菜单项。点击之后，Output Log里打印出“修复贴图路径被点击了”。
到这里，最基础的菜单就算通了。
3.3 插入位置和菜单位置细节
有人可能会问：这个CustomTools菜单为什么正好排在菜单栏最后？它能不能跑到File前面？答案是可以的。
UToolMenu里的Section、菜单项，包括菜单本身，都支持“插入位置”。比如我想把新菜单插到“Tools”和“Window”中间，可以在注册时手动指定。实际操作起来，菜单项的插入位置通过在AddMenuEntry的参数里传FToolMenuInsert，指定InsertPosition和相对位置。
代码示例大概是：
FToolMenuSection& MainSection = Menu->AddSection("MainSection", NSLOCTEXT("EditorTools", "MainSectionLabel", "我的工具")); MainSection.AddMenuEntry( "FixMaterialPath", NSLOCTEXT("EditorTools", "FixMaterialPathLabel", "修复贴图路径"), NSLOCTEXT("EditorTools", "FixMaterialPathToolTip", "批量把选中材质的贴图路径重定向到新目录"), FSlateIcon(), FToolMenuEntry::ExecuteAction(FExecuteAction::CreateLambda([]() { // 业务逻辑 })), FToolMenuInsert("Window", EToolMenuInsertType::Before) // 插在“Window”菜单前面 );不过说实话，对自定义菜单而言，位置优先级没那么重要。菜单栏不是工具栏，“放中间还是放最后”不影响正确性。真需要排布的，通常是在做一个复杂的编辑器工具箱时才会去纠结。
3.4 Shutdown时的菜单清理
菜单注册后，如果模块卸载了，已经注册进UToolMenus的菜单会成为一个“孤儿”。编辑器不一定会崩，但下次重新加载模块时会出现重复注册，甚至菜单显示混乱。
所以ShutdownModule里做一件小事：移除自己注册的菜单。代码很简单：
void FEditorToolsModule::ShutdownModule() { if (UToolMenus::IsToolsMenuOpen()) { UToolMenus::Get()->UnregisterMenu("LevelEditor.MainMenu.CustomTools"); } }这里IsToolsMenuOpen()是为了防止编辑器退出阶段UToolMenus已经被销毁时，我们再访问一个不存在的对象。在Shutdown阶段，很多全局对象处于“正在销毁”状态，直接调用可能触发崩溃断言，加一层判断是保命的习惯。
4. 常见问题与排查实录
编辑器扩展的坑主要集中在编译、加载、生命周期三个方面。我把自己遇到过的真实问题和排查过程复盘一下，你可以直接当速查表用。
4.1 编辑器启动后菜单不显示
表现：编译成功，启动编辑器，菜单栏里啥也没有。
排查思路按顺序来：
- 确认模块确实被加载了。在C++里打断点，或者在StartupModule里加
UE_LOG(LogTemp, Log, TEXT("EditorTools loaded"))。如果日志没出来，说明模块压根没被加载。 - 如果模块加载了但菜单没出现，先确认注册路径有没有写错。
LevelEditor.MainMenu.CustomTools这样的路径，任何一段拼错都会导致注册静默失败。 - 检查是否被其他模块抢先注册了同名菜单。UToolMenus的菜单名是全局唯一的，多个模块注册同一个名字，后注册的会返回已存在的那个菜单，然后往里塞Section。如果两个模块塞的Section名也一样，菜单列表就会奇妙地合并。
这问题我在插件调试时出现过一次，原因是LoadPhase设置在BeforeProjectLoading，那时候工具菜单系统自己还没初始化，注册被吞掉了。解决办法是把模块加载阶段调整到PostEngineInit，或者直接用默认。
4.2 编译错误：找不到UToolMenus
症状：编译时报错无法打开包含文件: "ToolMenus.h"，或者UToolMenu is an undefined type。基本上你就是少加了依赖。在Build.cs里把"ToolMenus"加进PrivateDependencyModuleNames，基本能把绝大多数同名错误解决。
还有一个类似的问题是FSlateIcon找不到。这个要么是少了SlateCore依赖，要么是编辑器模块缺少EditorStyle。检查一下你的Build.cs是不是被工具更新时自动精简掉了某些依赖。
4.3 点击菜单项没反应
症状：菜单项正常显示，但点击后没有任何反馈。
最常见的原因有三种：
- 回调函数绑定的对象已经被销毁。比如Lambda里用了
this，而this指向的实例在模块卸载后还在被菜单引用。 - 操作没有跑在游戏线程。编辑器UI操作默认要求运行时切换上下文，虽然菜单的ExecuteAction一般会在正确线程触发，但如果你在里面创建了异步任务，回主线程又忘记
AsyncTask包装，极容易出现问题。 - 业务逻辑压根抛了异常但被编辑器吞了。用
ensure或者check语句来判断入口是否执行到。
最优先的排查方法还是绑一个日志，然后把业务逻辑拆成最小可跑函数，一件件排查。
4.4 模块卸载时崩溃
症状：关闭编辑器时崩溃，或者热重载时编辑器卡死。
问题往往出在没有正确清理菜单。如果你ShutdownModule里有访问UToolMenus，但UToolMenus本身已经被销毁，就会崩溃。按我上面那段代码的写法，先判断IsToolsMenuOpen()再调用Unregister，能避免90%的关闭崩溃。
另外还要留意自己创建的委托是否还被其他对象持有。比如把FExecuteAction存到了全局变量，模块卸载后委托仍被菜单系统持有，再次触发时操作一个已经被释放的对象。这种问题排查起来很隐蔽，我的习惯是：能用Lambda就地绑定就绝不存到成员变量里。
4.5 快捷速查表
| 问题 | 常见原因 | 快速修复 |
|---|---|---|
| 菜单不显示 | 依赖缺失/注册路径错误/模块未加载 | 检查Build.cs依赖，确认路径，打日志验证加载 |
| 编译报ToolMenus.h不存在 | 缺少ToolMenus模块依赖 | 加入PrivateDependencyModuleNames列表 |
| 点击无反应 | 回调未绑定/对象已销毁/线程问题 | 加日志，绑定安全对象，检查Lambda捕获 |
| 关闭崩溃 | Shutdown清理不完整，或委托悬挂 | 用IsToolsMenuOpen判断，移除菜单注册，避免存长期委托 |
| 菜单重复/被其他模块污染 | 菜单名全局唯一导致冲突 | 改用自己独特的前缀，如MyProject_前缀 |
5. 一些值得留意的细节和扩展玩法
5.1 用UI_COMMAND构建命令体系
上面的Lambda是演示用的，真正做大一点的工具，建议用FUICommandList加UI_COMMAND宏来搭命令体系。好处是很明显的：命令有唯一ID，能自动关联快捷键和图标；多个菜单项甚至工具栏按钮可以复用同一个命令；命令状态还可以被统一管理、禁用或置灰。
做一个命令的步骤大概是：
- 定义一个FUICommandList派生类或直接实例化。
- 定义命令名和友好名称。
- 在StartupModule里MappingAction。
- 在AddMenuEntry时把命令信息传进去。
代码框架大致长这样：
// 自定义命令类 class FToolsCommands : public TCommands<FToolsCommands> { public: FToolsCommands() : TCommands<FToolsCommands>( TEXT("EditorToolsCommands"), NSLOCTEXT("EditorTools", "Commands", "编辑器工具"), NAME_None, FEditorStyle::GetStyleSetName()) {} TSharedPtr<FUICommandInfo> FixMaterialPath; virtual void RegisterCommands() override { UI_COMMAND(FixMaterialPath, "修复贴图路径", "批量把选中材质的贴图路径重定向到新目录", EUserInterfaceActionType::Button, FInputChord()); } };然后在StartupModule里：
FToolsCommands::Register(); auto& Commands = FToolsCommands::Get();把Command绑定到回调后，AddMenuEntry时直接传它的CommandInfo，这样菜单项能和快捷键、工具栏联动，比每次手写Lambda清晰多了。
5.2 动态菜单与子菜单
如果你的菜单项要根据当前选中的资产动态变化，ToolMenus提供了OnGetContent之类的动态Builder机制。简单理解就是：每次下拉菜单时，框架询问你“现在有哪些菜单项”，你根据上下文返回。这样就能实现“选中的是材质的菜单显示材质工具，选中的是贴图就显示贴图工具”的效果。
子菜单的注册同样不复杂。注册一个父菜单后，继续注册它下面一层的菜单，路径自然形成层级。比如LevelEditor.MainMenu.CustomTools.SubTools就是一个子菜单路径。
动态子菜单是编辑器工具里比较高级的玩法，但对刚入门的人来说，建议先把静态菜单跑通，再研究动态。不然一串动态生成逻辑混在一起，出了问题很难定位。
5.3 后续还能往哪扩展
菜单栏只是编辑器扩展的一小块。我后面可能会再写一篇“给编辑器添加工具栏按钮”的续篇。两者用的核心API非常像，菜单项换到工具栏里，新菜单变成新按钮，逻辑几乎能平移。
另外，如果你想做资产右键菜单，扩展点是ContentBrowser.AssetContextMenu这一类的路径。如果你想把菜单和某个EditorSubsystem联动，还可以在Subsystem里完成业务逻辑，菜单入口只负责触发。这样业务和UI分离，后续想把同一套工具迁移成后台批处理，会非常方便。
最后说点实在话
我最早做编辑器扩展的时候，也想过一步到位，直接做一个完整的工具集，把所有资产操作都塞进去。结果光菜单注册就折腾了一整晚，最后发现是依赖少了一个，白白浪费了时间。后来我把路子改成“最小可用”的思路：先什么都不要，只做一个菜单、一个菜单项、一个日志输出，确认管线通了，再去填充业务逻辑。这个习惯到现在都在用，几乎没再被编辑器扩展的启动流程坑过。
还有一个建议是：尽量把菜单名和Section名加上自己的项目缩写前缀。比如MyProject_MainTools。这样就算别的插件也注册了类似的菜单，也不会撞车。编辑器插件越装越多，这个习惯能救你不少命。
最后，工具最终是给人用的。菜单做好以后，建议找美术或者策划小伙伴试用一下，看看命名清不清楚，入口位置好不好找。他们觉得好用，这个工具的维护价值才真正体现出来。
