.Net 常见问题

以下默认使用 Windows 操作系统打包构建，不使用多线程，不开启 AOT。 ​

1. 微信开发者工具相关​
   • 需使用最新版本的 Stable 微信开发者工具，并在右上角 “详情 -> 本地设置” 中勾选 SWC 编译：​

   

   • 需要开启 wasm experimental feature，enable之后重启开发者工具生效（请保证开发者工具完全退出）：

   

   • 微信开发者工具目录，需要打开 wasm exception handling，在 package.nw/package.json 添加​：

   

   

   • 完成后需要重启电脑

   • 如果项目较大，开发者工具崩溃，请增加开发者工具内存限制

   ​

2. iOS解析wasm出错
   • 确保开启高性能模式。在未开启情况下，微信不支持部分DotNet Wasm 特性
3. System Cryptography 模块出错，Unsupported Platform / AES / MD5
   • 由于浏览器沙盒环境限制和其他安全风险，从 .NET5 runtime 开始，大部分的加密模块 API 没有 BCL 的默认实现，具体参考微软相关文档 。 更多不支持的 API 请参考 github文档。
   • 我们以 Plugin 的形式，增补了部分常用的 Crypto 实现，在微信转换工具 SDK 中。原则上，引擎本身不会添加 BCL 的默认 Crypto 实现，开发者在明确了解安全风险的前提下，也可以根据需要，仿照现有实现增加自己的 Crypto Plugin。
   • MD5 可以使用 SDK 中 JS interop 实现： WeChatWASM.WebMD5.GetMD5Bytes(buffer)，以下为示例代码：

   

   • AES 可以使用 SDK 中 JS interop 实现: WeChatWASM.WebAES，但我们仍然推荐不要在客户端使用对称加密/解密。
4. BinaryFormatter 未实现
   • .NET8 中，相关接口评估为高风险，请选择更换其他序列化方式，参考：BinaryFormatter 将在 .NET 9 中删除、已过时的序列化方法及建议。
   • 已知 LitJson.JsonMapper.ToJson 这个接口序列化后会把 int 转为 string，导致后续反序列化无法区分类型，推荐使用 Newtonsoft.Json。
5. SIMD相关
   • 目前默认不勾选 SIMD。勾选 SIMD 后构建会出现 iOS 早于16.4 (未确定具体小版本) 无法正确解析 Wasm 的情况， 这是 iOS 本身的兼容性问题。
6. DLL存在，但是构建时报错找不到文件，无法完成Copy
   • 检查是否文件路径太长，超出系统限制，参考微软文档：最大路径长度限制，可以更换目录，或设置系统支持长路径
7. Rider/Visual Studio 调试无法debug Editor
   • Visual Studio 需要手动选择

   

   • Rider 需要手动选择

   

8. Emscripten 工具链相关
   • 报错目录在，例如 WeixinMiniGameSupport\BuildTools\DotNetWithWasm-win-x64\packsMicrosoft.NET.Runtime.Emscripten.3.1.34.Cache.win-x64\8.0.0\tools\emscripten\cache\sysroot\lib\wasm32-emscripten ，可执行文件为 wasm-ld、wasm-opt 等, 错误为 __undefined symbol: __[some_cpp_mangled_symbol] 。
     • 先检查本地是否已经安装过 Emscripten 工具链，并有环境变量遗留，例如 EM_CONFIG、EM_SDK 等。需要删除所有相关环境变量，以免 DotNet Wasm 编译命中旧版本库，因版本不匹配导致奇怪的编译失败。
     • 如果编译环境为 Linux 或者 Mac 并遇到此类问题，可以先执行空命令验证是否出错，例如 WeixinMiniGameSupport/BuildTools/DotNetWithWasm/packs/Microsoft.NET.Runtime.Emscripten.3.1.34.Sdk.linux-x64/8.0.0/tools/bin/wasm-opt，如果有复现 undefined symbol，考虑 remove 已安装的 emscripten/binaryen 相关工具链，或更改 LD_LIBRARY_PATH 确保命中正确库。
9. Browser.mainLoop.scheduler is not a function
   • 错误指向为首场景加载不成功，排查首个加载 Scene 中是否有额外逻辑，尽量延后复杂逻辑，异步加载到首场景加载完毕后。
   • 可能有 dll 加载问题导致这个 error，可以参考11，开启 MONO LOG 辅助排查问题。

   

10. Lua 插件相关 / C 插件相关
    • 目前编译c Plugin的规则下，所有后缀为 .c 的文件会被采集进入 emscripten 编译链路，如果 Plugin 中有把 .c 文件当作头文件 include 的情况，需要按需重命名为正确后缀 .h，否则可能遇到类似 wasm-ld duplicate symbol: xxxx /Library/Bee/artifacts/WeixinMiniGame/PlayerBrowserWasm/PlayerBrowserWasm.gen.csproj 的错误
    • xLua相关，报错为 undefined symbol 来源为 xlua.c

    

    解决方法为 xlua_webgl 勾选目标平台 WeixinMiniGame

    

    • xLua 相关，构建完成后执行报错 Can not find System.MonoType

    

    报错原因为：Mono 运行时 MonoType 被识别为一个“dummy类”。在 Mono 运行时中，MonoType 类用于判断当前程序是否运行在 Mono 运行时上。然而，在 DotNet Wasm 解决方案中使用的运行时环境中，并没有这个 MonoType 类，因此无法找到它，从而导致报错。 解决方法为：注释掉 xLua 中 LuaEnv.cs 脚本中关于 MonoType 的代码。

    

11. 如何开启MONO LOG帮助排查dll加载问题
    • 可以手动在 Code/wwwroot/_framework/blazor.boot.json 添加参数，开启 MONO LOG，并在Browser console中定位问题dll

    

    开启 LOG 后，可能看到如下的 log：

    

    以上的 log 说明 DOTween.Modules.dll 不存在，这与 DoTween 的 asmdef 生成策略相关。 * 如果有其他 log 无法定位问题排查请到开发者论坛或官方群

12. WebGL 1 支持相关
    • DotNet Wasm 没有侵入渲染的改动，built-in 渲染管线可以选择 WebGL1。但例如 URP（Universal Render PipelineA series of operations that take the contents of a Scene, and displays them on a screen. Unity lets you choose from pre-built render pipelines, or write your own. More info
      See in Glossary）存在不兼容 WebGL1 的情况，推荐使用 WebGL2。
13. [1.2.0 已支持非 Wasm Exception Handling] Exception Handling 相关
    • DotNet Wasm默认为 Wasm Exception，自团结1.2.0版本起可以手动切换到 Cxx Exception。由于部分第三方插件没有支持 wasm exception，此时需要切换。
    • Publishing Settings -> Enable Exceptions 这个选项与 DotNet Wasm 无关。
    • iOS 15.2 以前版本不支持 Wasm Exception，DotNet Wasm 游戏会加载失败，Cxx Exception 有更好的兼容性，但因为改变了所有开启异常函数的调用链路，因此可能引入额外性能损耗。需要根据项目做具体的 profile 分析。
14. TypeLoadException: VTable setup of type xxx failed
    • 请检查 Managed Stripping Level 是否开的太高，Managed Code Strip 开到 Low 或 Minimal 即可。该选项主要服务于 IL2CPP，使得 DLL 生成的 cpp 代码减少从而尽可能减少 Wasm 体积。由于 DotNet Wasm 是解释执行，即便不去做额外 Strip，相应的 IL 也只会作为 bytes 存储而不会展开，对内存影响微乎其微。
15. 手机如何连接 Unity Profiler 进行性能分析 / Development 导出的 Wasm 过大无法上传微信？
    • 需使用本地的 wxsdk，需要把 Git 版本移除并将 sdk clone 到本地，并从 Package Manager 手动添加​
    • 更改如下文件，增加参数将 debug symbol 分出 wasm（仅对小游戏生效，目的是减少 wasm 体积使得手机可以预览，添加后浏览器中无法使用 native debugger）​

    

    • WXSDK 选择 Development Build 并且 Auto connect Profiler​
    • 手机需要禁用移动数据（仅安卓），并确保和 Editor 在同一网段​
    • Editor 所在设备防火墙策略需要正确配置，以免无法连接​
    • 关闭微信开发者工具，以免 Editor 错误识别​
    • 打开 Editor 中的 Window -> Analysis -> Profiler 面板，等待自动连接​

16. Argument_CultureInvalidIdentifier 多语言

    

    • i18n相关，NET8 wasm加载多语言的data会让包体膨胀，默认不开。InvariantGlobalization 目前设为 true，也就是默认 culture default 不变的模式，可以在 Library\Bee\artifacts\WeixinMiniGame\PlayerBrowserWasm\PlayerBrowserWasm.gen.csproj 更改。更改后会引入 dat，需要关注导出产物大小​。
    • 具体的，需要找到 csproj 中 InvariantGlobalization key，手动更改为 false，并在这个下方手动添加一行 <WasmIcuDataFileName>icudt_[xxx].dat</WasmIcuDataFileName> ，具体需要根据加载的语言选择dat文件，参考 Wasm 全球化相关文档​。
    • 注意手动更改csproj的情况下，在改动引擎编译选项或者选择Clean Build的时候csproj会被覆盖​

    

17. 个别工程打包 development 出现 Build failed
    • 出现两个 Error，并且 binlog 包含 SyntaxError: function abort(what) already defined，此时找到如下目录的 Error.js 注释掉红框定义：

    

更多 DotNet 相关问题可前往技术交流社区。