Unity 2021.3.4f1构建WebGL项目失败报错排查求助

问题背景 #

• 构建对象为仅使用2D刚体、碰撞体组件的基础2D游戏。

报错明细 #

报错1 #

编译路径 D:\Downloads\Unity Game Engine\projects\speedrun\Library\Bee\artifacts\WebGL\il2cppOutput\UnityClassRegistration.cpp 失败，核心错误输出：

"D:/Downloads/Unity Game Engine/Unity Hub Editor/2021.3.4f1/Editor/Data/MonoBleedingEdge/bin/mono" 不是可识别的内部或外部命令、可运行程序或批处理文件。
对应调用栈：

UnityEditor.BuildPipeline:BuildPlayer (UnityEditor.BuildPlayerOptions)
Unity.Play.Publisher.Editor.PublisherBuildProcessor:OpenBuildGameDialog (UnityEditor.BuildTarget) (at Library/PackageCache/com.unity.connect.share@4.2.3/Editor/PublisherBuildProcessor.cs:178)
Unity.Play.Publisher.Editor.PublisherWindow:OnWebGLBuildTargetSet () (at Library/PackageCache/com.unity.connect.share@4.2.3/Editor/PublisherWindow.cs:748)
Unity.Play.Publisher.Editor.PublisherWindow:OnCreateABuildClicked () (at Library/PackageCache/com.unity.connect.share@4.2.3/Editor/PublisherWindow.cs:509)
Unity.Play.Publisher.Editor.PublisherWindow/<>c__DisplayClass75_0:b__0 () (at Library/PackageCache/com.unity.connect.share@4.2.3/Editor/PublisherWindow.cs:627)
UnityEngine.GUIUtility:ProcessEvent (int,intptr,bool&)

报错2 #

错误表现与报错1完全一致，仅编译失败文件为同路径下的 UnityICallRegistration.cpp。

报错3 #

抛出 BuildFailedException 异常：Incremental Player build failed!（增量播放器构建失败）
对应调用栈：

UnityEditor.Modules.BeeBuildPostprocessor.PostProcess (UnityEditor.Modules.BuildPostProcessArgs args) (at <36f62d8e760b48f7af5d32916f997ce1>:0)
UnityEditor.WebGL.WebGlBuildPostprocessor.PostProcess (UnityEditor.Modules.BuildPostProcessArgs args) (at /Users/bokken/buildslave/unity/build/PlatformDependent/WebGL/Extensions/Unity.WebGL.extensions/BuildPostprocessor.cs:158)
UnityEditor.Modules.DefaultBuildPostprocessor.PostProcess (UnityEditor.Modules.BuildPostProcessArgs args, UnityEditor.BuildProperties& outProperties) (at <36f62d8e760b48f7af5d32916f997ce1>:0)
UnityEditor.PostprocessBuildPlayer.Postprocess (UnityEditor.BuildTargetGroup targetGroup, UnityEditor.BuildTarget target, System.Int32 subtarget, System.String installPath, System.String companyName, System.String productName, System.Int32 width, System.Int32 height, UnityEditor.BuildOptions options, UnityEditor.RuntimeClassRegistry usedClassRegistry, UnityEditor.Build.Reporting.BuildReport report) (at <36f62d8e760b48f7af5d32916f997ce1>:0)
UnityEditor.BuildPipeline:BuildPlayer(BuildPlayerOptions)
Unity.Play.Publisher.Editor.PublisherBuildProcessor:OpenBuildGameDialog(BuildTarget) (at Library/PackageCache/com.unity.connect.share@4.2.3/Editor/PublisherBuildProcessor.cs:178)
Unity.Play.Publisher.Editor.PublisherWindow:OnWebGLBuildTargetSet() (at Library/PackageCache/com.unity.connect.share@4.2.3/Editor/PublisherWindow.cs:748)
Unity.Play.Publisher.Editor.PublisherWindow:OnCreateABuildClicked() (at Library/PackageCache/com.unity.connect.share@4.2.3/Editor/PublisherWindow.cs:509)
Unity.Play.Publisher.Editor.<>c__DisplayClass75_0:b__0() (at Library/PackageCache/com.unity.connect.share@4.2.3/Editor/PublisherWindow.cs:627)
UnityEngine.GUIUtility:ProcessEvent(Int32, IntPtr, Boolean&)

故障原因 #

三个报错为连锁触发关系，根因如下：

• 核心问题是命令行调用阶段无法定位Unity自带的mono可执行文件。Unity编辑器安装路径D:\Downloads\Unity Game Engine\包含空格，il2cpp编译环节解析路径时出错，直接导致前两个cpp文件编译失败。
• 单文件编译失败中断了增量构建流程，最终抛出增量播放器构建失败的异常。
• 触发打包的入口是com.unity.connect.share插件的一键构建功能，该插件4.2.3版本对带空格的安装路径存在兼容缺陷，会放大路径解析问题。

修复方案 #

按优先级依次尝试：

1. 解决路径空格问题
   • 关闭Unity编辑器，将2021.3.4f1版本编辑器移动到无空格、无中文的路径下，例如D:\Unity\Editor\2021.3.4f1\。
   • 打开Unity Hub，在安装列表中重新定位该版本编辑器的存储位置，同时将项目也移动到无空格、无中文的路径下，构建输出目录同样避开空格和中文字符。
   • 重新打开项目后先验证构建。
2. 清理缓存绕开插件兼容问题
   • 关闭Unity，删除项目根目录下的Library、Temp、Obj缓存文件夹。
   • 重新打开项目后，不要使用Share插件的一键构建入口，走原生菜单File > Build Settings切换WebGL平台，手动触发构建，避开插件的路径兼容bug。
   • 构建前进入Edit > Preferences > External Tools，确认WebGL相关构建工具路径全部正确关联。
3. 版本补丁修复
   • 2021.3.4f1是该LTS分支的早期版本，存在已知的il2cpp路径解析bug，可通过Unity Hub升级到2021.3分支最新的补丁版本，升级前务必备份项目。
   • 升级完成后重新导入项目，先做一次空场景构建验证环境正常，再进行完整项目打包。

内容的提问来源于stack exchange，提问作者fourarms