[Unity]/[UE] CommonJS 模块加载时 puer.evalScript 默认实现未使用 debugPath，导致 VSCode/V8 Inspector 调试路径丢失

[leo-zhang-git]

detail | 详细描述

问题描述

在 Unity PuerTS 的 CommonJS 模块加载链路中，ILoader.ReadFile(string filepath, out string debugpath) 返回的
debugPath 会被一路传递到 puer.evalScript(script, debugPath)，但默认的 puer.evalScript 实现没有使用这个
debugPath。

这会导致 CommonJS 模块最终以普通 eval(script) 的形式出现在 V8 Inspector / VSCode 调试器中，调试器无法稳定识别真实文
件路径，进而影响断点绑定和 sourcemap 定位。

涉及版本

我在以下两个版本/组合中都观察到了类似问题：

1. com.tencent.puerts.core 2.0.4
com.tencent.puerts.commonjs 1.1.0-pre.0

2. com.tencent.puerts.core 3.0.2
com.tencent.puerts.v8 3.0.2

相关代码

以 com.tencent.puerts.core 3.0.2 为例，ILoader 接口本身提供了 debugpath：

public interface ILoader
{
    bool FileExists(string filepath);
    string ReadFile(string filepath, out string debugpath);
}

模块加载时，puer.loadFile 会从 loader 读取 debugPath：

function loadFile(path) {
    let debugPath = [];
    var content = loader.ReadFile(path, debugPath);
    return { content: content, debugPath: debugPath[0] };
}
puer.loadFile = loadFile;

CommonJS 模块执行时，module.mjs 会把 debugPath 传给 puer.evalScript：

function executeModule(fullPath, script, debugPath) {
    if (debugPath === undefined) debugPath = fullPath;

    let wrapped = puer.evalScript(
        "(function (exports, require, module, __filename, __dirname) { " + script + "\n});",
        debugPath
    );

    wrapped(exports, createLazyRequire(fullPath), module, debugPath, dirname(debugPath));
}

但默认 puer.evalScript 实现没有使用 debugPath：

puer.evalScript = global.__tgjsEvalScript || function (script, debugPath) {
    return eval(script);
}

在 com.tencent.puerts.core 2.0.4 + com.tencent.puerts.commonjs 1.1.0-pre.0 中也有类似链路：

let wrapped = puer.evalScript(
    "(function (exports, require, module, __filename, __dirname) { " + script + "\n});",
    debugPath
)

但默认实现仍是：

puer.evalScript = global.__tgjsEvalScript || function (script, debugPath) {
    return eval(script);
}

IL2CPP 初始化路径中甚至是：

puer.evalScript = eval

这也无法消费 debugPath。

### 当前现象

当自定义 loader 返回真实文件路径时，例如：

public string ReadFile(string filepath, out string debugpath)
{
    debugpath = fullPath;
    return File.ReadAllText(fullPath);
}

debugpath 能正确传递到 CommonJS 模块执行逻辑，但最终因为 puer.evalScript 只是 eval(script)，调试器中看到的脚本路径不是
loader 返回的真实路径。

在 VSCode attach V8 Inspector 调试时，可能出现以下问题：

- CommonJS 模块显示为 eval 脚本，而不是实际文件路径
- 断点无法稳定绑定到本地 JS/TS 文件
- sourcemap 定位不稳定或失效
- 需要业务侧手动 patch puer.evalScript 才能恢复调试路径

### 当前 workaround

目前可以通过替换 puer.evalScript 并追加 sourceURL / 修正 sourceMappingURL 来规避：

puer.evalScript = function (script, debugPath) {
    if (typeof script !== 'string') {
        return eval(script);
    }

    if (debugPath) {
        var normalized = String(debugPath).replace(/\\/g, '/');

        if (/^[a-zA-Z]:\//.test(normalized)) {
            normalized = 'file:///' + normalized;
        } else if (normalized.charAt(0) === '/') {
            normalized = 'file://' + normalized;
        }

        script += '\n//# sourceURL=' + normalized;
    }

    return eval(script);
};

这样 VSCode / V8 Inspector 能够识别 CommonJS 模块对应的真实文件路径，断点和 sourcemap 也能正常工作。

### 期望行为

希望 PuerTS 默认的 puer.evalScript(script, debugPath) 能消费传入的 debugPath，例如：

1. 在默认实现中根据 debugPath 追加 //# sourceURL=...
2. 或者通过其他官方推荐方式把 debugPath 传递给底层 eval / V8 Inspector
3. 同时避免破坏用户自定义的 global.__tgjsEvalScript

也就是说，对于通过 ILoader.ReadFile(..., out debugpath) 返回的真实路径，CommonJS 模块执行时调试器应能看到对应的脚本路
径。

### 疑问

请问默认 puer.evalScript 忽略 debugPath 是有意设计吗？

如果不是，是否可以在默认实现中基于 debugPath 自动追加 sourceURL，或者提供一个官方推荐的方式来处理 CommonJS 模块调试路
径？

[chexiongsheng]

il2cpp代码是https://github.com/Tencent/puerts/blob/master/unity/upms/core/Runtime/Resources/puerts/init_il2cpp.mjs#L93
你说的puer.evalScript = eval是哪里看到的？
puer.evalScript = global.__tgjsEvalScript || function (script, debugPath) {
return eval(script);
}
eval路径是fallback，不是默认。默认是前面那个。

[leo-zhang-git]

il2cpp代码是https://github.com/Tencent/puerts/blob/master/unity/upms/core/Runtime/Resources/puerts/init_il2cpp.mjs#L93 你说的puer.evalScript = eval是哪里看到的？ puer.evalScript = global.__tgjsEvalScript || function (script, debugPath) { return eval(script); } eval路径是fallback，不是默认。默认是前面那个。

我这里表述确实不够准确， puer.evalScript = eval 是我在本地另一个项目的 PuerTS 2.0.4 包里看到的

我这里想反馈的核心其实是本地实际调试现象：

在 Unity Editor + V8 + VSCode attach 调试 PuerTS CommonJS 模块时，如果不额外处理 puer.evalScript(script, debugPath)，VSCode 断点无法正常绑定。

我这边 attach 成功后跟踪调试器里显示的脚本文件，发现业务模块没有显示为 loader 返回的真实文件路径，而是显示成类似：

VMxxx.json

或类似的 VM eval 脚本名。

因此 VSCode 里打在本地 TS/JS 文件上的断点不会生效。

但如果我在业务侧加一个 workaround，替换 puer.evalScript，把传入的 debugPath 转成 file:///... 并追加到脚本末尾：

//# sourceURL=file:///...

同时修正相对的：

//# sourceMappingURL=...

之后 VSCode 就能正常识别文件路径，断点也能命中。

也就是说，我这边不是单纯从 fallback 源码推断问题，而是遇到了实际现象：

1. CommonJS 模块执行时传入了 debugPath
2. loader 返回的 debugPath 是真实磁盘路径
3. VSCode attach 成功
4. 但调试器中脚本显示为 VMxxx.json，不是实际文件路径
5. 本地断点无法绑定
6. 手动在 puer.evalScript 中基于 debugPath 追加 sourceURL 后，断点恢复正常

所以我想确认的是：

• 当前 Unity V8 backend 注入的 global.__tgjsEvalScript 是否预期会把 debugPath 反映到 V8 Inspector 的 script URL？
• 如果预期会，那么我这边显示为 VMxxx.json 是否说明当前 CommonJS wrapper eval 场景下没有正确走到这个逻辑，或者 source
  map / debugPath 格式还有额外要求？
• 如果预期不会，那是否建议官方在 CommonJS 模块执行时基于 debugPath 追加 sourceURL，或者提供一个推荐的处理方式？

[chexiongsheng]

应该和加不加//# sourceURL没关，而是和URL有没包含file:有关，早期的vscode配套的调试器是支持没有file:的路径的，后面的版本要求加了。

[leo-zhang-git]

应该和加不加//# sourceURL没关，而是和URL有没包含file:有关，早期的vscode配套的调试器是支持没有file:的路径的，后面的版本要求加了。

我本地测试把ILoader.ReadFile(..., out debugpath)改为返回file:格式，仍然无法正常命中本地断点

[leo-zhang-git]

应该和加不加//# sourceURL没关，而是和URL有没包含file:有关，早期的vscode配套的调试器是支持没有file:的路径的，后面的版本要求加了。

我修改源码让fallback路径下也消费debugPath后，也能够成功断点了，看起来问题更像是我本地环境下global.__tgjsEvalScript没有成功注入？