---
tags:
  - UE
  - Puerts
  - EasyEditorPlugin
  - 改造方案
  - TypeScript
  - 架构
created: 2026-05-31
---

# 改造方案：将业务 TS 代码嵌入插件

## 需求背景

目前 EasyEditorPlugin 将业务 TypeScript 代码放在**项目的 `Content/EasyEditorScripts/` 目录**中，插件本身只是一个薄桥接层。我们希望能够：

1. **业务 TS 代码跟随插件分发**（写在插件的 Content/Resources 目录中）
2. **项目 C++ 代码直接调用插件中的 TS 函数**（类型安全，有返回值）
3. **项目代码只需最少量的调用**（LoadModule + 少量 API 调用）

## 可行性评估

| 需求 | 可行性 | 改造量 |
|------|--------|--------|
| TS 代码嵌入插件 Content | ✅ 可行，自定义 IJSModuleLoader | 小（~50 行 C++） |
| C++ 调用插件 TS 函数 | ✅ 可行，暴露 FJsObject 获取 API | 中（~100 行 C++） |
| TS 代码热重载 | ✅ 已有基础设施，仅需调整路径 | 无需改动 |
| 运行时（非 Editor）支持 | ✅ 可行，但需创建新 Runtime 模块 | 大（架构变更） |

## 方案一：改造 EasyEditorPlugin（编辑器工具场景）

适用场景：**编辑器工具扩展**，业务代码是编辑器工具逻辑（如资产处理、关卡自动化等），不需要在打包后的游戏中运行。

### 改造点 1：自定义 IJSModuleLoader，从插件 Content 加载

#### 当前代码

```cpp
// EasyEditorPlugin.cpp InitJsEnv()
JsEnv = MakeShared<puerts::FJsEnv>(
    std::make_shared<puerts::DefaultJSModuleLoader>(TEXT("EasyEditorScripts")),
    ...);
```

**问题**：`DefaultJSModuleLoader` 只在项目 Content 目录搜索，不会搜索插件目录。

#### 改造后

新建 `PluginJSModuleLoader.h`：

```cpp
#pragma once

#include "JSModuleLoader.h"
#include "Misc/Paths.h"

class FPluginJSModuleLoader : public PUERTS_NAMESPACE::IJSModuleLoader
{
public:
    explicit FPluginJSModuleLoader(const FString& InPluginContentSubDir)
        : ScriptRoot(InPluginContentSubDir)
    {
        // 获取插件 Content 目录
        // EasyEditorPlugin 中: FPaths::ProjectPluginsDir() / "EasyEditorPlugin/Content"
        PluginContentDir = DeterminePluginContentDir();
    }

    virtual bool Search(const FString& RequiredDir, const FString& RequiredModule,
                        FString& Path, FString& AbsolutePath) override
    {
        // 搜索顺序：
        // 1. 先在插件的 Content/ScriptRoot/ 下搜索
        // 2. 再走默认的 DefaultJSModuleLoader 逻辑（项目 Content、node_modules 等）

        // 插件目录搜索
        FString PluginDir = PluginContentDir / ScriptRoot;
        if (SearchModuleInDir(PluginDir, RequiredModule, Path, AbsolutePath))
            return true;

        // 回退到默认搜索逻辑
        return DefaultLoader.Search(RequiredDir, RequiredModule, Path, AbsolutePath);
    }

    virtual bool Load(const FString& Path, TArray<uint8>& Content) override
    {
        return DefaultLoader.Load(Path, Content);
    }

    virtual FString& GetScriptRoot() override
    {
        return ScriptRoot;
    }

    static FString DeterminePluginContentDir()
    {
        // 获取当前插件自身的 Content 目录
        // 方案 A：通过 IPluginManager 查询
        TSharedPtr<IPlugin> Plugin = IPluginManager::Get()
            .FindPlugin(TEXT("EasyEditorPlugin"));
        if (Plugin.IsValid())
        {
            return Plugin->GetContentDir();
        }

        // 方案 B：手动拼路径（兼容旧版本）
        return FPaths::ProjectPluginsDir() / TEXT("EasyEditorPlugin/Content");
    }

private:
    FString ScriptRoot;
    FString PluginContentDir;
    PUERTS_NAMESPACE::DefaultJSModuleLoader DefaultLoader;

    bool SearchModuleInDir(const FString& Dir, const FString& RequiredModule,
                           FString& Path, FString& AbsolutePath)
    {
        // 尝试扩展名: .js, .mjs, .cjs, .mbc, .cbc, /index.js, package.json
        static const TArray<FString> Extensions = {
            TEXT(".js"), TEXT(".mjs"), TEXT(".cjs"),
            TEXT(".mbc"), TEXT(".cbc")
        };

        for (const auto& Ext : Extensions)
        {
            FString TestPath = Dir / RequiredModule + Ext;
            if (FPaths::FileExists(TestPath))
            {
                Path = RequiredModule + Ext;
                AbsolutePath = FPaths::ConvertRelativePathToFull(TestPath);
                return true;
            }
        }

        // 尝试目录 + index.js
        FString IndexPath = Dir / RequiredModule / TEXT("index.js");
        if (FPaths::FileExists(IndexPath))
        {
            Path = RequiredModule / TEXT("index.js");
            AbsolutePath = FPaths::ConvertRelativePathToFull(IndexPath);
            return true;
        }

        return false;
    }
};
```

#### 修改 InitJsEnv()

```cpp
void FEasyEditorPluginModule::InitJsEnv()
{
    SourceFileWatcher = MakeShared<puerts::FSourceFileWatcher>(
        [this](const FString& InPath) { /* 同上 */ });

    // 使用自定义 Loader，从插件 Content/BusinessScripts/ 加载
    JsEnv = MakeShared<puerts::FJsEnv>(
        std::make_shared<FPluginJSModuleLoader>(TEXT("BusinessScripts")),
        std::make_shared<puerts::FDefaultLogger>(), -1,
        [this](const FString& InPath) { /* 同上 */ });
}
```

#### 插件目录结构变为

```
EasyEditorPlugin/
├── Content/
│   └── BusinessScripts/           ← TS 业务代码（随插件分发）
│       ├── Main.ts                 ← 入口
│       ├── commands/
│       │   ├── AssetCommands.ts
│       │   └── LevelCommands.ts
│       ├── ui/
│       │   ├── MenuSetup.ts
│       │   └── DetailPanel.ts
│       └── utils/
│           └── helpers.ts
├── Source/
│   └── ...
└── EasyEditorPlugin.uplugin
```

---

### 改造点 2：暴露 JsEnv，支持 C++ 类型安全调用 TS

#### 问题

```cpp
class FEasyEditorPluginModule {
private:
    TSharedPtr<puerts::FJsEnv> JsEnv;   // ← 外部无法访问
};
```

外部 C++ 只能通过 `Eval` 执行 JS 字符串，无类型安全、无返回值。

#### 改造：公开 JsEnv 访问和 FJsObject 获取

在 `EasyEditorPlugin.h` 中新增：

```cpp
class FEasyEditorPluginModule : public IModuleInterface
{
public:
    // ===== 新增 API =====

    /**
     * 从 JS 全局作用域获取一个函数/对象，返回 FJsObject 用于类型安全调用
     * 示例：
     *   auto& Mod = FModuleManager::LoadModuleChecked<FEasyEditorPluginModule>("EasyEditorPlugin");
     *   FJsObject MyFunc = Mod.GetJsExport("myBusinessFunction");
     *   int32 Result = MyFunc.Func<int32, int32, FString>(42, TEXT("hello"));
     */
    FJsObject GetJsExport(const FString& Name) const;

    /**
     * 从 JS 模块（已 require 的）中获取一个导出
     * 示例：
     *   FJsObject Handler = Mod.GetJsModuleExport("commands/AssetCommands", "handleAsset");
     *   Handler.Action(TEXT("/Game/MyAsset"));
     */
    FJsObject GetJsModuleExport(const FString& ModuleName, const FString& ExportName) const;

    /**
     * 获取底层的 IJsEnv 接口（高级用法）
     */
    TSharedPtr<puerts::FJsEnv> GetJsEnv() const { return JsEnv; }

    // ===== 原有 API =====
    std::function<void()> OnJsEnvPreReload;
    std::function<void(const FString&)> Eval;
    FSimpleMulticastDelegate OnJsEnvCleanup;
    TSparseArray<TUniquePtr<FAutoConsoleCommand>> TsConsoleCommands;

private:
    // ...
};
```

#### 实现（`EasyEditorPlugin.cpp`）

```cpp
FJsObject FEasyEditorPluginModule::GetJsExport(const FString& Name) const
{
    if (!JsEnv.IsValid())
    {
        UE_LOG(Puerts, Error, TEXT("JsEnv is not valid when getting export '%s'"), *Name);
        return {};
    }

    // 通过 Eval 机制获取全局变量
    // 实际实现需要利用 Puerts 的内部 API
    // 方案见下方"实现细节"
}

FJsObject FEasyEditorPluginModule::GetJsModuleExport(
    const FString& ModuleName, const FString& ExportName) const
{
    if (!JsEnv.IsValid())
    {
        return {};
    }

    // 需要从模块缓存中查找
    // 方案见下方"实现细节"
}
```

#### 实现细节：如何从 JsEnv 中获取 JS 对象

**核心问题**：`FJsEnv` 的 `FJsEnvImpl` 成员是私有的，没有公开的 "通过名称获取 JS 变量" API。需要通过以下方式实现：

**方案 A：通过 `puerts::FJsEnv` 包装器暴露新方法**

需要在 Puerts 的 `FJsEnv` 中新增一个方法：

```cpp
// 在 JsEnv.h 中新增
class JSENV_API FJsEnv
{
public:
    // ... 现有 API ...

    /**
     * 获取全局作用域中的一个值
     * @param Name 全局变量/函数名
     * @return 包装了该 JS 值的 FJsObject，如果不存在或类型不对则返回空
     */
    FJsObject GetGlobalValue(const FString& Name);
};
```

实现（在 `JsEnvImpl.cpp` 中）：

```cpp
FJsObject FJsEnv::GetGlobalValue(const FString& Name)
{
    if (!GameScript) return {};

    auto Impl = static_cast<FJsEnvImpl*>(GameScript.get());
    auto Isolate = Impl->MainIsolate;
    auto Context = Impl->DefaultContext.Get(Isolate);

#ifdef THREAD_SAFE
    v8::Locker Locker(Isolate);
#endif
    v8::Isolate::Scope IsolateScope(Isolate);
    v8::HandleScope HandleScope(Isolate);
    v8::Context::Scope ContextScope(Context);

    auto Global = Context->Global();
    auto V8Name = FV8Utils::ToV8String(Isolate, Name);
    auto MaybeValue = Global->Get(Context, V8Name);

    v8::Local<v8::Value> Val;
    if (MaybeValue.ToLocal(&Val) && Val->IsObject())
    {
        return FJsObject(Context, Val.As<v8::Object>());
    }

    return {};
}
```

但这种方式需要 **修改 Puerts 源码**（在 `JsEnv.h` 和 `JsEnvImpl.cpp` 中增加代码），对于已经安装的 Puerts 插件不太方便。

**方案 B：在 EasyEditorPlugin 中注入 JS 辅助函数（推荐，无需修改 Puerts）**

思路：在 `InitJsEnv()` 时，向 JS 全局注入一个 `__eep_getExport` 函数，同时在 C++ 中存储引用。

```cpp
// EasyEditorPlugin.cpp

// 存储注入的 JS 辅助函数
static FJsObject G_GetExportFunc;

void FEasyEditorPluginModule::InitJsEnv()
{
    // ... 创建 JsEnv ...

    JsEnv->Start(TEXT("Main"));

    // Main.ts 执行后，获取注入的辅助函数引用
    // Main.ts 中需要暴露:
    //   global.__eep_getExport = (name) => { ... return eval(name); }
    //   global.__eep_getModuleExport = (moduleName, exportName) => { ... }
}
```

但这形成了一个鸡生蛋蛋生鸡的问题 —— 在 Main.ts 执行前无法获取引用。

**方案 C：使用 Puerts 的 JIT stub 机制（最务实）**

在 EasyEditorPlugin 的绑定代码中注册可被 `require()` 调用的 C++ 函数：

```cpp
// 在 EasyEditorPlugin.cpp 的 AutoRegisterForEEP 中新增绑定：

struct FEasyEditorBridge
{
    static puerts::Function GetGlobalFunction;
    static FJsObject GetGlobalObject;

    // 注册到 Puerts binding
};
```

然后在 Main.ts 中：

```typescript
// 将需要暴露给 C++ 的函数注册到 global 对象
import { MyBusinessLogic } from './business/BusinessLogic';

(global as any).__exports = {
    processAsset: MyBusinessLogic.processAsset,
    validateLevel: MyBusinessLogic.validateLevel,
    // ...
};
```

C++ 侧通过 Eval 获取：

```cpp
FJsObject FEasyEditorPluginModule::GetJsExport(const FString& Name) const
{
    // 利用 Eval 机制代理
    // 实际方案：在 V8 中执行 "__exports[Name]"，捕获结果
    // 但当前 Eval 是 void 返回的...

    // 需要改造 Eval 为有返回值的版本，见下文
}
```

**方案 D：改造 Eval 为有返回值的版本（最小侵入）**

```cpp
// 在 EasyEditorPlugin.h 中
class FEasyEditorPluginModule
{
public:
    // 替代原来的 void Eval，使用可返回值的版本
    std::function<FJsObject(const FString&)> EvalWithReturn;
};
```

在 `InitJsEnv()` 中注册对应的 C++ 绑定：

```cpp
// 利用 Puerts 的 FV8Utils 实现有返回值的 Eval
// 在 C++ 侧: 持有 v8::Isolate 和 v8::Context，直接 eval 并封装结果
```

**方案 E：最简单且实用的方案 —— 通过 Console 命令 + 注册回调**

不暴露 JsEnv，而是让项目 C++ 注册一个回调，TS 通过 `EasyEditorPlugin.AddConsoleCommand` 或其他绑定来调用它：

```cpp
// 项目 C++ 代码中使用 EasyEditorPlugin
void FMyProjectModule::StartupModule()
{
    auto& EEP = FModuleManager::LoadModuleChecked<FEasyEditorPluginModule>("EasyEditorPlugin");

    // 在 JS 环境就绪后注册
    EEP.OnJsEnvCreated.AddLambda([this]() {
        // 告诉 TS 侧：C++ 准备好了
        EEP.Eval(TEXT("if (global.__onCppReady) global.__onCppReady()"));
    });
}
```

但这种模式是 **TS 调用 C++**，而非用户需求的 **C++ 调用 TS**。

---

### 推荐的 C++ → TS 调用方案总结

| 方案 | 侵入性 | 类型安全 | 需要修改 Puerts | 推荐度 |
|------|--------|---------|----------------|--------|
| A: 扩展 FJsEnv::GetGlobalValue | 低 | ✅ | ❌ 需要 | ⭐⭐⭐ |
| B: 注入 JS 辅助函数 | 中 | ✅ | 不需要 | ⭐⭐ |
| C: require() 注册 | 中 | ✅ | 不需要 | ⭐⭐ |
| D: Eval 改造成有返回值 | 低 | ❌ 需手动转换 | 不需要 | ⭐⭐ |
| E: 回调注册 | 低 | ❌ | 不需要 | ⭐（反向模式） |

**最佳实践：方案 C（PUERTS_MODULE addon）+ 方案 A（扩展 FJsEnv）**

在实际项目中，建议**对 Puerts 做少量扩展**（fork 或 patch），因为 Puerts 本身设计就预留了扩展点。

---

## 方案二：基于 Puerts 创建自己的 Runtime 插件（运行时代码场景）

如果业务代码需要在**打包后的游戏**中运行（Gameplay 逻辑、AI、战斗系统等），EasyEditorPlugin 的 Editor-only 限制是致命的。

此时正确的做法是：**直接基于 Puerts 创建自己的 Runtime 插件**。

### 插件骨架

```
MyBusinessPlugin/
├── MyBusinessPlugin.uplugin
├── Content/
│   └── BusinessScripts/              ← TS 业务代码
│       ├── Main.ts                    ← 入口
│       ├── combat/
│       ├── ai/
│       └── ui/
└── Source/
    └── MyBusinessPlugin/
        ├── MyBusinessPlugin.Build.cs
        ├── Public/
        │   └── MyBusinessPluginModule.h
        │   └── BusinessAPI.h           ← 公开给项目 C++ 的 API
        └── Private/
            ├── MyBusinessPluginModule.cpp
            └── MyBinding.cpp            ← PUERTS_MODULE 注册
```

### .uplugin

```json
{
    "FriendlyName": "MyBusinessPlugin",
    "Modules": [{
        "Name": "MyBusinessPlugin",
        "Type": "Runtime",               // ← Runtime！可在打包游戏中运行
        "LoadingPhase": "Default"
    }],
    "Plugins": [{
        "Name": "Puerts",
        "Enabled": true
    }]
}
```

### Build.cs

```csharp
PublicDependencyModuleNames.AddRange(new string[] {
    "Core",
    "CoreUObject",
    "Engine",
    "JsEnv"           // ← 依赖 Puerts 的 JsEnv
});
```

### `MyBusinessPluginModule.h`

```cpp
#pragma once

#include "CoreMinimal.h"
#include "Modules/ModuleManager.h"
#include "JsEnv.h"
#include "JsObject.h"

class FMyBusinessPluginModule : public IModuleInterface
{
public:
    virtual void StartupModule() override;
    virtual void ShutdownModule() override;

    // 公开给项目 C++ 的 API
    FJsObject GetExport(const FString& Name) const;
    TSharedPtr<puerts::FJsEnv> GetJsEnv() const { return JsEnv; }

private:
    TSharedPtr<puerts::FJsEnv> JsEnv;
    void InitJsEnv();
    void UnInitJsEnv();
};
```

### `MyBusinessPluginModule.cpp`

```cpp
#include "MyBusinessPluginModule.h"
#include "JSModuleLoader.h"
#include "Misc/Paths.h"
#include "Interfaces/IPluginManager.h"

void FMyBusinessPluginModule::StartupModule()
{
    InitJsEnv();
}

void FMyBusinessPluginModule::ShutdownModule()
{
    UnInitJsEnv();
}

void FMyBusinessPluginModule::InitJsEnv()
{
    // 获取插件 Content 目录
    TSharedPtr<IPlugin> Plugin = IPluginManager::Get()
        .FindPlugin(TEXT("MyBusinessPlugin"));
    FString PluginContent = Plugin.IsValid()
        ? Plugin->GetContentDir()
        : FPaths::ProjectPluginsDir() / TEXT("MyBusinessPlugin/Content");

    // 创建自定义 ModuleLoader，从插件 Content/BusinessScripts/ 加载
    auto Loader = MakeShared<FPluginJSModuleLoader>(
        PluginContent / TEXT("BusinessScripts"));

    JsEnv = MakeShared<puerts::FJsEnv>(
        Loader,
        MakeShared<puerts::FDefaultLogger>(),
        -1,  // debugPort, -1 = 禁用调试
        nullptr,
        FString(),
        nullptr, nullptr);

    // 启动业务代码入口
    JsEnv->Start(TEXT("Main"));
}

void FMyBusinessPluginModule::UnInitJsEnv()
{
    JsEnv.Reset();
}

FJsObject FMyBusinessPluginModule::GetExport(const FString& Name) const
{
    // 实现同方案一的讨论
    // 推荐方式: 对 Puerts 做 patch，给 FJsEnv 加 GetGlobalValue
}
```

### `BusinessAPI.h` — 给项目 C++ 的调用接口

```cpp
#pragma once

#include "CoreMinimal.h"
#include "JsObject.h"

namespace BusinessAPI
{
    // 获取插件的 JsEnv
    TSharedPtr<PUERTS_NAMESPACE::FJsEnv> GetBusinessJsEnv();

    // 获取 JS 导出函数
    PUERTS_NAMESPACE::FJsObject GetExport(const FString& Name);

    // 便捷调用封装
    inline int32 ValidateLevel(const FString& LevelPath)
    {
        auto Func = GetExport(TEXT("validateLevel"));
        if ( /* Func is valid */ )
        {
            return Func.Func<int32, FString>(LevelPath);
        }
        return -1;
    }
}
```

### 项目 C++ 调用方式

```cpp
// 项目 C++ 代码 —— 极简调用
void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();

    // 加载插件（自动启动 TS 业务逻辑）
    FModuleManager::Get().LoadModule("MyBusinessPlugin");

    // 调用 TS 函数
    auto Func = BusinessAPI::GetExport(TEXT("onGameStart"));
    Func.Action(this);   // 传递 UObject，自动转换为 TS 侧 UE 类型
}
```

---

## 热重载支持

无论方案一还是方案二，热重载都是可用的。只需确保 `FSourceFileWatcher` 监听的是正确的目录：

```cpp
// 插件 Content 目录下的 BusinessScripts/
FString WatchDir = PluginContentDir / TEXT("BusinessScripts");
SourceFileWatcher = MakeShared<puerts::FSourceFileWatcher>(
    [this](const FString& InPath) {
        if (JsEnv.IsValid()) {
            TArray<uint8> Source;
            if (FFileHelper::LoadFileToArray(Source, *InPath)) {
                JsEnv->ReloadSource(InPath,
                    puerts::PString((const char*)Source.GetData(), Source.Num()));
            }
        }
    });
```

---

## 改造清单

### 最小改造（编辑器工具，方案一）

| 步骤 | 文件 | 改动 |
|------|------|------|
| 1 | 新建 `PluginJSModuleLoader.h` | 自定义模块加载器，从插件 Content 搜索 |
| 2 | `EasyEditorPlugin.cpp:InitJsEnv()` | 切换为 `FPluginJSModuleLoader` |
| 3 | `EasyEditorPlugin.h` | 添加 `GetJsEnv()` 和 `GetJsExport()` |
| 4 | 插件 `Content/BusinessScripts/` | 移入 TS 业务代码 |
| 5 | (可选) Puerts `JsEnv.h/cpp` patch | 添加 `GetGlobalValue()` 方法 |

### 完整改造（Runtime 支持，方案二）

| 步骤 | 文件 | 改动 |
|------|------|------|
| 1 | 创建新插件 `MyBusinessPlugin` | `.uplugin`, `Build.cs`, 目录结构 |
| 2 | `PluginJSModuleLoader.h`（复用） | 自定义模块加载器 |
| 3 | `MyBusinessPluginModule.h/cpp` | 模块实现，参考 EasyEditorPlugin |
| 4 | `BusinessAPI.h` | 公开 C++ 调用 API |
| 5 | 插件 `Content/BusinessScripts/` | 移入 TS 业务代码 |
| 6 | Puerts `JsEnv.h/cpp` patch | 添加 `GetGlobalValue()` 方法 |
| 7 | 项目 `.uproject` | 添加插件依赖 |

---

## 注意事项

1. **线程安全**：FJsObject 在 `THREAD_SAFE` 模式下自动加锁，但建议所有 TS 调用都在 GameThread 进行
2. **JsEnv 生命周期**：确保在 `ShutdownModule()` 中正确销毁 JsEnv，避免 V8 isolate 泄漏
3. **GC 联动**：参考 EasyEditorPlugin 的地图卸载时 GC 处理，避免 "GC Memory Leak" 断言
4. **模块解析**：自定义 `IJSModuleLoader` 需要正确实现 `Search` 和 `Load` 两个方法
5. **Puerts 版本**：不同 Puerts 版本的 V8 API 可能不同（V8 8.x vs 11.x），注意 `V8_MAJOR_VERSION` 条件编译