企业官网建设流程全解析

在Unity所有发布平台里，WebGL是我认为最需要重新学习“异常处理”思维的一个。以前做Windows或Android端，异常直接打在Console窗口，变量值、堆栈、调用链一目了然；一旦切到WebGL，你会发现Console经常一片安静，浏览器控制台倒是抛出一堆看不懂的错误，甚至整个页面直接白屏。这背后不是Unity出了问题，而是WebGL平台本身的运行机制决定了异常捕获必须换一套玩法。

这篇博文就是要解决这件事。我会从UnityWebGL的报错产生原理讲起，把C#层和JavaScript层的异常分别会流向哪里拆清楚，然后给出3种我已经在实际项目里验证过的异常捕获配置方案：第一套适合开发期快速定位，第二套适合联调和轻度生产环境，第三套适合正式上线后的远程监控。看完之后，你能拿到可直接抄走的代码模板、构建配置参数和一份常见报错排查速查表，省掉自己从头踩坑的时间。

1. 为什么WebGL平台的报错总让人摸不着头脑

1.1 编译目标和运行环境的基本差异

先明确一个基础认知：Unity WebGL不是把C#代码直接跑在浏览器里，而是先把C#编译成IL，再由IL2CPP转成C++，最后通过Emscripten编译成WebAssembly（wasm）。这个过程中的每一层转换都会影响异常信息的形态。

在Windows平台，Unity的Mono或IL2CPP运行时可以直接抛出托管异常，异常对象的类型、Message、StackTrace都结构清晰。但在WebGL平台，C#异常要先穿过IL2CPP转换成C++层的处理，再通过Emscripten的运行时与JavaScript环境交互。很多底层错误到了浏览器这边就变成了一个不痛不痒的RuntimeError，或者干脆被浏览器安全模型吞掉。

更麻烦的是，浏览器本身有几套独立的错误机制：window.onerror能捕获未处理的JavaScript异常，unhandledrejection能捕获Promise异常，而WebAssembly运行时内部的异常不一定走这两个通道。所以你在浏览器控制台看到的报错，可能跟你游戏里实际的问题根本不沾边。

1.2 异常信息的三种最终去向

我在实际项目里观察下来，WebGL项目的异常最终会流向三个地方：

第一，Unity Console窗口。前提是你在构建时勾选了Development Build，并且代码里有Debug.LogError等输出。这种情况下C#层的异常会通过Console窗口展示，但堆栈信息可能被压缩，行号对应的是C++转换后的位置而不是原始C#代码。

第二，浏览器DevTools的Console面板。这部分包含两类信息：Unity通过jslib或者Emscripten打印的日志，以及浏览器运行时抛出的原生JavaScript错误。实际开发中，WebAssembly的崩溃、加载失败、内存溢出等问题只能在这里看到。

第三，玩家/用户看到的页面表现。比如点击按钮没反应、画面卡死、白屏。这类是最终用户能感知的“异常”，但它们没有具体的报错文本，需要我们去主动捕获底层异常才能反推原因。

所以我很早就得出一个结论：在WebGL平台，只依赖Unity Console或只依赖浏览器控制台都不够，必须把两条链路全都接进来，才有可能还原一个错误的完整面貌。

1.3 常见报错类型与现象速查

在你开始设计捕获方案之前，建议先对WebGL常见的异常类型有个整体印象。我用一张表整理一下，方便你排查时对照参考：

当你写好了异常捕获配置，其实做的是三件事：把隐藏的C#异常捞出来、把JS异常接进来、把所有信息统一整理到一个可控的出口。

2. 动手之前：先把异常捕获的整体思路理顺

2.1 捕获链路的两端：C#日志与JS运行时

在设计方案之前，你得先理解异常捕获链路的两端。

一端是Unity C#运行时。Unity自身提供了一个静态事件Application.logMessageReceived，所有通过Debug.Log、Debug.LogWarning、Debug.LogError输出的日志都会进入这个回调。这是C#层异常捕获最容易接入的入口，但它只能捕获被日志打出来的信息，捕获不了被Unity内部吞掉的错误。

另外还有一个Application.logMessageReceivedThreaded，功能基本相同，但会在非主线程调用，UI操作需要小心线程问题。

另一端是JavaScript运行时。浏览器原生提供了window.onerror和unhandledrejection这两个全局事件，可以拿到未处理的JS异常。此外还有Emscripten的Module对象提供了onAbort、onRuntimeInitialized等回调，WebAssembly初始化失败时能在这里看到原因。

比较理想的做法是，两条链路都打通，并且把日志尽量统一成同一种格式，这样无论是查本地还是查线上，你面对的都是同一套日志语言。

2.2 日志分级与格式化：先把信息整理干净

捕获异常的第一步不是写捕获代码，而是定日志格式。很多项目在各种日志回调里print了一堆东西，结果排查时根本无法区分哪条是崩溃前的关键日志，哪条是普通信息。

我个人的建议是至少保留四个级别：Info、Warn、Error、Fatal。每个级别对应不同的显示颜色和上报策略。在C#里直接用Debug.Log、LogWarning、LogError天然对应前三级，Fatal可以用LogError加自定义标识来实现。

格式上，我习惯统一成这样的结构：

[时间戳] [级别] [场景/模块] 日志内容

比如[2025-03-10 14:22:31] [Error] [LoginPanel] NullReferenceException: 用户名输入框未初始化。别小看这个细节，当你有几千条日志要筛选时，带时间戳和模块名的日志会让排查效率翻倍。

2.3 本地调试时最高效的观测姿势

本地调试阶段，我的经验是：Unity Console窗口优先，浏览器控制台次之，游戏内日志面板仅在需要模拟生产环境时才打开。

为什么不是优先用浏览器控制台？因为Unity Console里的日志格式经过Unity引擎格式化，堆栈信息更直观，而且双击可以直接定位到脚本代码。但你在Unity编辑器里看到的Console日志并不代表WebGL运行时就完全一致，尤其是WebGL特有的JS错误，编辑器预览模式下根本不会出现。

所以我的本地调试流程通常是：先用Unity编辑器把C#层逻辑调通，再构建一个Development Build放到浏览器里跑，同时打开浏览器DevTools的Console面板，与Unity Console对照着看。这个流程下，90%以上的问题都能在开发阶段暴露出来。

3. 三种可落地的异常捕获配置方案

3.1 方案一：C#日志回调+游戏内日志面板

这是成本最低、见效最快的一套方案，适合中小型项目在开发期和测试期使用。

核心思路是：通过Application.logMessageReceived把所有C#日志集中到一个全局容器里，然后在游戏场景里做一块简单的日志UI，平时隐藏，按快捷键或点按钮时弹出。

先写一个最简版本的日志管理器：

using System; using System.Collections.Generic; using UnityEngine; public class LogCapture : MonoBehaviour { public static LogCapture Instance { get; private set; } public List<LogEntry> Logs = new List<LogEntry>(); public int MaxLogCount = 500; public event Action<LogEntry> OnLogAdded; private void Awake() { if (Instance != null && Instance != this) { Destroy(gameObject); return; } Instance = this; DontDestroyOnLoad(gameObject); Application.logMessageReceived += HandleLog; } private void OnDestroy() { Application.logMessageReceived -= HandleLog; } private void HandleLog(string logString, string stackTrace, LogType type) { LogEntry entry = new LogEntry { Timestamp = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"), Message = logString, StackTrace = stackTrace, LogType = type }; Logs.Add(entry); if (Logs.Count > MaxLogCount) { Logs.RemoveRange(0, Logs.Count - MaxLogCount); } OnLogAdded?.Invoke(entry); } } public class LogEntry { public string Timestamp; public string Message; public string StackTrace; public LogType LogType; }

这个管理器的关键点是DontDestroyOnLoad，保证切换场景时日志不会丢。MaxLogCount限制数量，避免运行时间长了之后内存增长失控。OnLogAdded事件可以给UI面板做实时刷新。

日志面板可以单独做一个Canvas，挂在同一个物体上。面板里用一个ScrollView显示最近的日志，Error以上标红，Warning标黄，Info保持白色。我还会加一个复制按钮，一键把日志拷贝到剪贴板，方便发给同事或贴到问卷里。

不过这套方案有个天然短板：它只能捕获C#层打印出来的日志，捕获不了浏览器JS层面的异常，也捕获不了WebAssembly崩溃。所以它适合当“游戏内自查”的工具，但撑不起完整的问题排查。

3.2 方案二：jslib插件打通JS与C#双向通道

当浏览器控制台不断抛JS错误，而Unity Console里一片安静时，你就需要方案二了：通过.jslib插件模板建立一个C#与JavaScript之间的双向通信通道。

Unity官方支持在Plugins文件夹下放.jslib文件，里面可以写JavaScript函数，通过[DllImport("__Internal")]暴露给C#调用。反过来，JS也能调用Unity的SendMessage或者CallFunction来触发C#方法。

先看一个最基础的.jslib模板：

mergeInto(LibraryManager.library, { JSLog: function (level, messagePtr) { var message = UTF8ToString(messagePtr); var prefix = ""; if (level === 0) prefix = "[INFO]"; else if (level === 1) prefix = "[WARN]"; else if (level === 2) prefix = "[ERROR]"; console.log(prefix + " " + message); }, InstallJSErrorHook: function () { window.onerror = function (msg, source, line, col, error) { var message = "[JS_ERROR] " + msg + " at " + source + ":" + line + ":" + col + "\n" + (error && error.stack ? error.stack : ""); Module.SendMessage("GlobalObject", "OnJSError", message); return false; }; window.addEventListener("unhandledrejection", function (event) { var reason = event.reason; var message = "[JS_PROMISE_ERROR] " + (reason && reason.stack ? reason.stack : reason); Module.SendMessage("GlobalObject", "OnJSError", message); }); Module.onAbort = function (what) { Module.SendMessage("GlobalObject", "OnFatalError", "WebAssembly Abort: " + what); }; } });

对应C#端的声明：

using System.Runtime.InteropServices; using UnityEngine; public class JSBridge : MonoBehaviour { [DllImport("__Internal")] private static extern void JSLog(int level, string message); [DllImport("__Internal")] private static extern void InstallJSErrorHook(); public void Awake() { #if UNITY_WEBGL && !UNITY_EDITOR InstallJSErrorHook(); #endif } public void OnJSError(string message) { Debug.LogError(message); } public void OnFatalError(string message) { Debug.LogError("[FATAL] " + message); } }

这里有几个细节很容易踩坑。

第一，jslib函数的参数传递。字符串不能直接传，必须用UTF8ToString转换指针。反过来，从JS调C#时，用Module.SendMessage传字符串可以直接传，Unity会自动转换。

第二，编译条件必须加UNITY_WEBGL && !UNITY_EDITOR。因为jslib方法在编辑器里没有对应实现，直接调用会报EntryPointNotFoundException。

第三，window.onerror回调里要return false，否则部分浏览器会认为错误已被处理，不再打印原始日志，反而影响排查。

这套方案真正解决了C#和JS两边日志割裂的问题。我在一个上线项目里用这套方案，线上玩家反馈“卡死了”，后台日志能看到最后一条C#日志，同时也能看到玩家浏览器抛出的JS异常，很多时候就能拼出完整的事故现场。

3.3 方案三：生产环境级上报体系

前两套方案解决的都是“本地能看到异常”，但做上线项目，你需要的是“即使没有开发者在场，也能把异常收集回来”。这就需要引入生产环境级的远程上报体系。

整体架构分三层：

第一层是Unity C#日志统一出口。沿用方案一的LogCapture，但把OnLogAdded的回调里加一段上报逻辑，根据日志级别决定是否上报。我一般只上报Error和Fatal，Warn和Info在本地保留即可，否则上报量会很大。

第二层是JS全局错误捕获。沿用方案二的jslib安装逻辑，但在JS端把捕获到的信息同时上报给远端服务，或者统一交给后端接口转发。我建议在JS端直接上报，路径更短，而且可以带上浏览器类型、版本、页面URL、用户操作路径等WebGL开发更需要关注的上下文。

第三层是上报通道。最简单的做法是Unity发HTTP请求到自己的后端，后端记录日志后写入日志系统或数据库。也可以接入第三方错误监控平台，它们通常提供了JavaScript SDK，可以直接上报。很多团队会在WebGL构建里集成Sentry，我实际用下来也不错，但要注意在jslib插件的资源加载阶段提前初始化，避免早期错误丢失。

下面是JS端上报的片段：

function reportError(level, message, stack) { var payload = { level: level, message: message, stack: stack, userAgent: navigator.userAgent, url: location.href, timestamp: Date.now() }; fetch("https://your-backend-api.example.com/log", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload), keepalive: true }).catch(function () {}); }

keepalive属性很关键，它保证页面在崩溃或刷新前发出的请求尽量能被送达。WebGL游戏很多是单页应用，玩家卡死后可能直接刷新页面，如果不加keepalive，上报请求很可能被中断。

还有一点是隐私合规。如果你要上报用户ID、设备信息、操作路径，务必确认自己符合相关隐私政策，建议上报前做脱敏或者明确告知用户。

这套体系一旦跑起来，线上问题就不再需要靠运气发现。我在项目里会额外做一个“日志仪表盘”，按错误类型分组展示，每周看一下Top错误排行，很多隐藏的兼容性问题就能提前暴露。

3.4 三种方案的选型建议

光看方案容易晕，我直接按项目类型给你参考：

实际项目中，方案一和方案二往往可以合并使用：保留游戏内日志面板方便测试人员反馈时截图，同时开启jslib捕获JS错误。等产品稳定后，再决定是否正式部署方案三的完整上报链路。

4. 实战阶段：配置过程中的常见问题与排查

4.1 日志面板有输出但浏览器控制台为空

这个问题我遇到太多次了。游戏内日志面板正常滚动，但打开浏览器DevTools却什么日志都没有，尤其当你在自己电脑上调试时，还以为是浏览器缓存了旧版本。

最常见的原因是构建参数的设置。打开Player Settings，确认Scripting Backend选择的是IL2CPP，然后在Compression Format里，如果选了Brotli或Gzip，浏览器控制台的JS报错信息可能因为压缩变形而变短或丢失行号。本地调试时我习惯把Compression Format设为Disabled，发布时再启用压缩。

另外一个原因是Development Build没有被勾选。非开发构建默认会剥离大量调试信息和Console日志，所以浏览器控制台看不到是正常的。这也是为什么我强烈建议所有WebGL测试构建都勾选Development Build。

4.2 构建产物打开白屏，资源加载失败

白屏在WebGL项目里非常让人头疼，因为没有报错弹窗，玩家只会说“打不开”。但白屏的根源基本都可以在浏览器Network面板里找到线索。

先打开DevTools的Network面板，刷新页面，看有几个请求是红色或者状态码异常的。最常见的是403，通常是服务器没有正确配置wasm或data文件的MIME类型。.wasm文件需要配置为application/wasm，.data文件通常是application/octet-stream，如果你用Nginx托管，一定要在配置里加上。

另外一个高发点是CORS跨域问题。如果你把WebGL构建放在一个域名，而资源或API请求指向另一个域名，浏览器会拦截请求，控制台会出现CORS错误。解决方案是在服务器响应头里加Access-Control-Allow-Origin，或者把所有请求都改为同域。

白屏还有一个容易忽略的因素是WebAssembly内存分配失败。WebGL构建默认分配的内存大小可以在构建时配置，如果游戏场景比较大，或者运行时动态加载了较多资源，内存不足就会导致Wasm初始化失败。出现这种情况时，可以尝试在Player Settings里降低最大内存或改用64位构建，并在代码层面优化资源释放。

4.3 堆栈信息、符号映射与发布版本排错

线上版本最难受的问题是没有调试符号。打包出来的wasm是编译后的二进制，你只能拿到一个WebAssembly地址，根本看不出对应哪个C#方法。

Unity官方提供了解析wasm堆栈的方法。构建时勾选Player Settings里的“Debug Symbols”相关选项，会生成符号文件。再配合浏览器DevTools的Source Map或者Unity的Symbol Server功能，可以把wasm地址映射回C#函数名。

不过这个映射过程比较繁琐，我之前就被坑过。后来我发现一个更实用的思路：不要只依赖堆栈信息，而是在代码的关键路径上主动打日志。尤其是网络请求开始/结束、资源加载完成、场景切换前后，这些节点一旦异常，日志可以帮你确定问题发生的阶段，比单纯偶发崩溃后看一堆堆栈有效得多。

发布版本还要注意一个细节：URL参数对日志级别的影响。我在项目里做了一个按URL参数控制日志上报级别的功能，例如?logLevel=info可以开启所有日志上报，?logLevel=error只上报错误。这样当线上玩家反馈问题时，可以让TA把带参数的URL分享给你，通过这个参数临时开启详细日志，定位问题后再恢复，不用重新打包。

4.4 一些容易被忽略的浏览器侧因素

WebGL项目跑在浏览器里，就要尊重浏览器的规则。我踩过几个记忆深刻的坑，写出来提醒你。

第一，移动端浏览器的兼容性差异很大。ISO Safari对WebAssembly的支持和桌面Chrome不完全一致，尤其在低内存设备上更容易崩溃。我建议在测试覆盖列表里同时包含iOS Safari和Android Chrome，它们的行为差异比你想象中更大。

第二，浏览器的自动播放策略会影响音频初始化。如果项目在启动时自动播放背景音乐，而浏览器还没发生用户交互，音频不会正常播放，相关的异常也可能被静默吞掉。解决方案是让音频系统在用户第一次点击后再初始化，或者在初始化时捕获NotAllowedError。

第三，GPU显存限制。WebGL上下文默认使用显存，多个WebGL页面同时打开时，可能因为显存耗尽导致所有页面都崩溃。这个问题在监控平台里几乎看不到，只能靠代码层面对纹理和Framebuffer做及时释放，以及引导用户不要同时开太多重负载页面。

第四，不要忽略浏览器版本。WebGL2已经是主流，但部分旧版浏览器只支持WebGL1。如果你的项目用了WebGL2专属特性，又碰到玩家浏览器不支持，页面不会直接报错，而是各种奇怪的渲染异常。构建时勾选合适的Graphics APIs，并在启动时做特性检测，信息要尽早暴露。

写在最后的一点经验

这三套配置方案的核心思路其实就一句话：在WebGL世界里，你的异常信息来源是双通道的，必须把C#和JavaScript两边都接上，才能拿到完整的问题画面。方案一帮你快速解决C#逻辑问题，方案二帮你补上JS层的信息盲区，方案三让你在线上版本里也能持续监控。

我个人做项目时还有一个习惯：每次处理完一个WebGL线上的疑难杂症，都会顺手把问题现象、排查链路、最终原因整理成一篇简短的记录放在团队知识库里。几个月下来就能形成一份非常宝贵的问题库，后来遇到类似报错，基本不用重新排查，直接翻记录就能对上。这部分投入看起来不起眼，却是提升团队排障效率最快的方式。

最后再分享一个小技巧：构建完WebGL后，建议先把产物放到任意一个静态服务器上，而不是用Unity的Build And Run直接打开。独立托管方式更接近线上用户的访问环境，Network请求、CORS策略、压缩格式的行为都和正式部署一致，很多在编辑器预览里发现不了的问题，在独立服务器上跑一遍就能暴露出来。把这个步骤养成习惯，你的WebGL版本稳定性会明显上一个大台阶。