5.2 编辑器 API 的不稳定面：常见坑速查

「稳定」与「不稳定」API 的分界

经验法则：

相对稳定	相对不稳定
Asset Registry 公开接口	编辑器内部窗口/面板布局类
Editor Scripting / Editor Utility Library	FLevelEditorModule 内部成员
Subsystem（EditorSubsystem 等）	FAssetEditorManager 的私有结构
UToolMenus 公共注册接口	旧 FUICommand 的注册路径
FScopedTransaction	编辑器 Toolbar 的直接操作

记法：UE 文档/示例里出现的公开 API 相对稳；源码里 private、Internal、无中文档的接口，升级引擎大版本时大概率要改。

1. 取编辑器对象时机

// 编辑器启动早期模块里拿 GEditor 可能是空的
if (GEditor) { ... }   // 别假定非空

StartupModule 里太早做的初始化，挪到第一个 Tick 或 PostEngineInit 后。

2. FAssetData.GetAsset() 是同步加载

GetAsset() 内部可能触发 LoadPackage（同步加载，可能卡一下）。分批处理或用 LoadPackageAsync。工具处理大量资产时这是主要卡顿源。

3. 编辑器中 GetWorld() 的含义

编辑器模式下的 World 与 PIE 世界不同。工具代码里 GEditor->GetEditorWorldContext().World() 是编辑器世界；直接 GetWorld() 在某些上下文里返回的是 PIE 世界——批量检查时可能扫错世界。

4. 模块加载顺序

编辑器模块之间的加载顺序不固定。StartupModule 里调别的编辑器插件的 API，可能那模块还没加载。防御做法：FModuleManager::LoadModulePtr<...>() 判空，或挪到 PostEngineInit。

5. 通知（Notification）的线程

FNotificationInfo 必须在游戏线程调用。后台线程完成后，用 AsyncTask(ENamedThreads::GameThread, ...) 切回去再通知。

6. 蓝图编辑器脚本的权限边界

EditorUtilityWidget 的蓝图节点不能访问任意 C++ 私有 API；遇到「蓝图没有这个节点」的需求，写个 C++ 蓝图函数库导出（见 4.4）。

7. 资产保存的路径

SaveAsset 要求传完整 ObjectPath（/Game/X.Y）。拼字符串时注意 " 包名."对象名"——漏 ObjectName 会失败。

8. 编辑器退出时的崩溃

模块 ShutdownModule 里解绑委托/清空 TSharedPtr 的顺序不对，编辑器关闭时崩溃。原则：先解绑所有委托，再清成员。

9. PIE 中工具表现不一致

编辑器世界与 PIE 世界的数据是分开的。工具若「在 PIE 运行时也起作用」（某些 EUW 行为），需要显式判断当前是否 PIE 并选择目标世界。

10. 蓝图热重载

工具运行中热重载蓝图可能导致 Slate 上的 UObject 引用失效。按钮回调里永远 IsValid 检查（if (MyObject && MyObject->IsValidLowLevel())）。

「Epic C++ 代码规范」（https://www.wanxiangyundang.top/read/unreal-engine-5-8-docs/epic-cplusplus-coding-standard-c21c）：写代码前读一遍，命名/结构能少走弯路
引擎大版本升级时，先跑一遍编译——90% 的破坏性改动编译期就暴露了

编辑器 API 的不稳定是常态而非异常。把「适配层」当基础设施写：每个外部引擎 API 都通过项目内的 helper 调用。升级时改 helper 一处，而不是全项目改 N 处。这个模式的价值会在第一次引擎大版本升级时体现。

心得：工具代码的架构原则和游戏代码不同——工具更需要「可丢弃、可重写」。为工具做厚重的抽象/设计模式经常是浪费。但适配层和日志这两样必须有，它们是工具能长期跑下去的地基。