企业官网建设流程全解析

先说一个我自己的经历：第一次把Unity游戏构建成WebGL版本丢到浏览器里，玩家反馈"进不去"，我看后台数据，加载率直接掉了一半。最痛苦的是没有任何报错日志，控制台干干净净，连个红色感叹号都没有。后来才知道，WebGL的异常捕获和原生平台完全是两码事，如果不按浏览器的方式去接日志，你连报错都看不到。这篇文章就把我踩过的坑和最终沉淀下来的3种配置方案完整讲清楚，从原理到代码、从开发调试到线上排查，适合正在做Unity WebGL项目、或者准备把现有Unity项目搬到浏览器的开发者。

1. 先搞清楚：UnityWebGL的报错为什么总是"看不懂、抓不到"

1.1 浏览器环境与原生平台的根本差异

很多人拿到报错的第一反应是去看Unity Console，在原生平台（Windows、Android）这个思路没问题，但WebGL完全不是这么回事。Unity在WebGL平台不是跑在独立进程里，而是被编译成了WebAssembly（Wasm），跑在浏览器的JavaScript虚拟机里。这个架构带来两个直接后果：

第一，Unity的Debug.Log虽然默认会输出到浏览器控制台，但输出的格式和内容都经过了C#到JS的跨语言桥接，很多底层信息会丢。比如你在C#里输出一个Debug.Log("test")，浏览器控制台确实能看见，但如果你想拿到C#堆栈和JS堆栈的完整链路，默认配置是给不出来的。

第二，除了Unity托管代码自己的异常，还有大量JS层的运行时错误、资源加载错误、浏览器API调用失败。这些错误Unity Console根本看不见，只会显示在浏览器DevTools的Console面板里。我见过很多团队排查一天一夜，最后发现是WebGL构建产物里某个JS文件被CDN缓存了旧版本，导致的加载崩溃。

所以在WebGL下做异常捕获，思路必须从"C#统一处理"切换成"浏览器统一处理"。这就像你在自己家（原生平台）水管坏了，知道总闸在哪；到了别人家（浏览器宿主环境），先得找到别人家的水电入户点。

1.2 常见的Unity WebGL报错类型速览

从我的项目经验来看，WebGL报错集中在这么几类：

• 加载阶段错误：Unable to load file、CompileError、Aborted，这类错误集中出现在初始化WebAssembly模块、加载数据文件（.data）时。大多是CDN配置、压缩格式（gzip/brotli）、跨域访问（CORS）引起的。
• 运行时JS错误：TypeError: Cannot read properties of undefined、ReferenceError: xxx is not defined，这类通常是集成第三方JS SDK、或者调用浏览器API时机不对。
• Unity托管异常：C#层面的NullReferenceException、ArgumentException等，这类异常会出现在浏览器控制台，但堆栈经过了Wasm翻译，不是原始C#路径，格式比较怪。
• 内存问题：Out of memory、abort(Error: System.OutOfMemoryException)。WebGL有严格的内存上限（32位寻址，通常建议控制在2GB以内），资源加载过多直接崩。

这几类错误的发生时机不同、捕获方式也不同，靠单一方案根本全覆盖。

1.3 报错信息为什么会"静默丢失"

这里有个非常关键的机制：浏览器对未捕获的JS异常，默认只在Console输出一行日志，并不会主动通知你的代码。如果用户不按F12打开控制台，错误就永远看不见。更麻烦的是，Unity的Wasm模块内部发生无法恢复的错误时，会调用abort()，页面表现可能是直接卡死、白屏，也可能在Console里只输出一句Aborted(...)，原因被截断得面目全非。

我后来在排查一个移动端白屏问题时发现，游戏实际是因为Wasm内存申请失败触发了RuntimeError，整个Wasm实例直接终止，但Unity侧没有任何回调暴露给开发者，只能靠浏览器全局错误监听去接。这就是为什么要做"多层捕获"，而不是依赖Unity单方面输出。

2. 方案一：Unity侧日志回调，3分钟接入最短路径

2.1 核心原理：Application.logMessageReceived

这是Unity官方提供的最基础的日志回调接口。只要在游戏启动时注册监听，Unity的所有日志输出（Log、Warning、Error、Exception、Assert）都会同步到你的C#方法里。代码很简单：

using UnityEngine; public class UnityLogCatcher : MonoBehaviour { [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterSceneLoad)] private static void Register() { Application.logMessageReceived += HandleLog; } private static void HandleLog(string logString, string stackTrace, LogType type) { if (type == LogType.Error || type == LogType.Exception || type == LogType.Assert) { // 沉淀到本地缓存，或者通过jslib传给JS层 Debug.Log($"[UnityLogCatcher] {type}: {logString}\n{stackTrace}"); } } }

注意[RuntimeInitializeOnLoadMethod]的使用，它保证这段代码在场景加载后自动执行，不需要手动挂载到某个GameObject上。如果你用的是老版本Unity，或者想把监听挂到特定对象，也可以写Awake。

2.2 从C#把日志递交给JS层

如果在浏览器环境，光是C#内部打印一遍意义不大。很多项目希望把Unity日志统一交给JS层的监控体系，这时候要挂一个jslib插件做桥接。

首先在Assets/Plugins/WebGL/目录下新建一个WebGLLogBridge.jslib文件：

mergeInto(LibraryManager.library, { PushUnityLog: function (logString, stackTrace, type) { var msg = UTF8ToString(logString); var stack = UTF8ToString(stackTrace); if (typeof window !== 'undefined' && window.__unityLogBridge) { window.__unityLogBridge(msg, stack, type); } } });

然后在C#侧声明外部方法并调用：

using System.Runtime.InteropServices; using UnityEngine; public class UnityLogBridge { [DllImport("__Internal")] private static extern void PushUnityLog(string logString, string stackTrace, int type); public static void Push(string logString, string stackTrace, LogType type) { #if UNITY_WEBGL && !UNITY_EDITOR PushUnityLog(logString, stackTrace, (int)type); #endif } }

这样，当C#层出现Exception时，HandleLog回调里调用UnityLogBridge.Push(...)，日志就会通过jslib桥接到浏览器全局的window.__unityLogBridge函数里。这个函数你可以自由定义，比如统一上报或者弹窗展示。

注意：jslib的mergeInto、UTF8ToString这些API在Unity 2020+都还兼容，但Unity 2023起官方推荐使用LibraryManager.library的新式写法或Unity Built-in JS API，老接口依然能用，后续大版本升级再适配即可。

2.3 方案一的边界在哪里

这个方案的优势是接入快、纯C#代码搞定，拿到的是Unity托管层的日志和字符串堆栈，对大部分代码层面的问题够用。

但它有两个明显缺陷：

• 捕获不到JS层错误。比如你的项目调用了第三方JS SDK，SDK内部抛异常，Unity的logMessageReceived完全无感。
• 拿不到完整的浏览器运行时堆栈。C#堆栈经过Wasm编译后，stackTrace字符串往往是"at UnityEngine.MonoBehaviour..."这种，虽然能定位到大致代码，但和浏览器DevTools里的原生态JS堆栈不是一回事。

如果你只做开发期自测，方案一足够。但如果是线上项目，想靠它做用户报错收集，你会发现漏网率非常高。

3. 方案二：浏览器全局监听，把JS层的漏网之鱼捞回来

3.1 核心原理：window.onerror与unhandledrejection

在浏览器里，要捕获全局未处理异常和未处理的Promise异常，标准做法是监听两个事件：window.onerror（或window.addEventListener('error')）和unhandledrejection。前者捕获同步异常和资源加载错误，后者捕获异步Promise里抛出的错误。

这段代码可以直接放在构建产物index.html的<head>里，或者单独抽一个error-catch.js文件加载：

(function () { function normalizeMessage(message, source, lineno, colno, error) { return { type: 'js_error', message: message, source: source + ':' + lineno + ':' + colno, stack: error && error.stack ? error.stack : '', url: location.href, ua: navigator.userAgent, time: Date.now() }; } window.addEventListener('error', function (event) { var payload = normalizeMessage( event.message, event.filename, event.lineno, event.colno, event.error ); // 交给统一上报函数 if (window.__reportError) { window.__reportError(payload); } }); window.addEventListener('unhandledrejection', function (event) { var reason = event.reason; var payload = { type: 'unhandledrejection', message: reason && reason.message ? reason.message : String(reason), stack: reason && reason.stack ? reason.stack : '', url: location.href, ua: navigator.userAgent, time: Date.now() }; if (window.__reportError) { window.__reportError(payload); } }); })();

这段代码的价值在于：它监听的是浏览器运行时层面，不管错误来自Unity的Wasm层还是第三方SDK，只要在页面里抛出来、没有被捕获，都能被记录。

3.2 怎么拿到更完整的Wasm堆栈

浏览器DevTools里，Wasm函数通常显示成wasm-function[123]:0x1a2b3c这种没有语义的形式。要想还原成有意义的函数名，需要在构建Unity项目时开启"Debug Symbols"，并配合Unity生成的.symbols.json文件做映射。这个后面第5章会讲实操。

关键点是：event.error.stack里，Wasm堆栈虽然不美观，但包含了十六进制的函数偏移地址，这些数据是后续符号还原的基础。所以这里收集原始堆栈时一定不要截断，尽量存全。很多上报平台默认只截取前几十行，WebGL项目如果要还原符号，得把这个限制去掉或者调大。

3.3 把方案一和方案二串起来

理想状态是：C#层的异常通过jslib桥接传到JS，JS层的异常由全局监听兜底，两边都汇总到同一个window.__reportError函数。

在index.html或单独的JS文件里定义：

window.__reportError = function (payload) { // 这里是统一出口：可以打点、可以远程上报、可以在页面上绘制一个泡 console.error('[GlobalErrorCatcher]', payload); // 上报到你的日志服务 if (navigator.sendBeacon) { var blob = new Blob([JSON.stringify(payload)], { type: 'application/json' }); navigator.sendBeacon('/api/logs/error', blob); } else { fetch('/api/logs/error', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }); } };

同时修改world里的jslibPushUnityLog方法，让它把C#日志也转换成__reportError格式调出去：

PushUnityLog: function (logString, stackTrace, type) { var msg = UTF8ToString(logString); var stack = UTF8ToString(stackTrace); if (window.__reportError) { window.__reportError({ type: 'unity_error', message: msg, stack: stack, url: location.href, ua: navigator.userAgent, time: Date.now() }); } }

这样Unity C#异常和JS异常就统一走一条链路了。

注意：navigator.sendBeacon在页面卸载（unload）时会保证发出请求，这是它比fetch更适合做崩溃日志上报的原因。不过sendBeacon对Payload大小有上限，一般建议不超过64KB。如果堆栈非常大，建议先压缩或截断，再用fetch保底。

4. 方案三：构建期注入上报脚本，线上问题不再靠用户截图

4.1 核心思路：改造构建产物index.html

前两个方案都是"运行时接入"，但WebGL项目的构建产物是自动生成的，每次重新Build都会被覆盖。方案三的思路是：把上报逻辑固化到构建流程里，每次Build后自动注入。

具体有两种做法：

做法一：手动改index.html。在文件里加入全局异常捕获脚本，这种方法一劳永逸，但每次构建完都得改一次，容易漏。

做法二（更推荐）：写一个Node脚本，在构建后处理阶段自动修改index.html。核心步骤是：

1. Unity构建完成后，生成目录Build/，其中index.html是入口文件。
2. 用Node读取index.html字符串，在<head>标签后插入上报脚本内容。
3. 写回文件。

这个脚本可以放在项目的BuildPipeline里调用Unity的IPostprocessBuildWithReport接口来实现自动化。不必引入复杂的构建工具链，一段Node脚本就够。

4.2 远程上报的Payload设计

线上报错收集的价值，取决于你收集到的上下文够不够。我目前的Payload大致长这样：

{ "type": "unity_error", "message": "NullReferenceException: Object reference not set to an instance of an object", "stack": "at ExampleClass.DoSomething (Int32 id) [0x0001a] in ...", "url": "https://game.example.com/index.html", "ua": "Mozilla/5.0 ... Chrome/124.0", "timestamp": 1715000000000, "project": "webgl-demo", "version": "1.0.3", "level": "error" }

字段设计建议：

• url和ua帮你判断是哪个入口、哪个浏览器出的问题，WebGL的浏览器兼容性问题很常见，这两项必填。
• version帮助你定位是不是某个发布版本才出现的问题。
• project当多个项目共用一套日志服务时区分来源。
• level可按LogType的Error、Exception、Assert区分严重程度。

4.3 线上环境还需要注意的事

线上上报会暴露一个问题：上报请求跨域。如果你的游戏部署在game.example.com，日志服务在log.example.com，那么上报接口必须支持CORS，否则请求发不出去。

另外一个容易踩的坑是：上报接口本身挂掉或者请求超时，不能阻塞游戏主流程。所以上报必须做异步和容错处理，一般用navigator.sendBeacon，天然异步，不阻塞页面；用fetch时记得加.catch(() => {})，避免上报失败又产生新的JS错误，形成错误嵌套。这个坑我真实遇到过，上报接口超时直接滚雪球，控制台刷了几百行错误。

5. 高频报错速查表与排查技巧实录

5.1 我遇到过的经典报错和处理方式

下面是我在Unity WebGL项目里实际遇到过的报错，整理成一个速查表，遇到直接可以对照着查：

我在本地调试时最高频的其实是第二类CompileError，尤其在低版本Chrome和部分国产浏览器上，Wasm编译兼容性参差不齐。遇到这种，我是直接引导用户升级浏览器，同时把构建产物里的Wasm做分层加载，先出可交互的加载页，再拉Wasm包，体验上会好很多。

5.2 为什么我捕获到的堆栈是乱码（符号映射问题）

第一次把方案三的上报数据拉到后台时，我看到的堆栈长这样：

at wasm-function[1427]:0x10235e at wasm-function[31]:0x8ab2c1 at wasm-function[258]:0x1a3f5b

完全没有函数名，根本没法定位。原因在于Unity WebGL默认不做符号保留，要把Wasm堆栈映射回可读的C#函数名，需要先开启构建选项里的Debug Symbols，然后拿到Build/xxx.symbols.json文件。

拿到symbols文件后，写一个简单的映射工具，把堆栈里的十六进制地址和函数名对应起来。如果只是偶尔排查几次，手动在同目录下用脚本查也行。如果是线上长期监控，建议接第三方日志平台，他们对Wasm符号还原的支持比自研来得省事。

这里推荐一个折中做法：本地调试时，用Unity的Development Build+Auto Connect Profiler跑，看到的是可读堆栈；线上环境收集原始十六进制堆栈不截断，然后保留构建记录和symbols文件，出了线上问题再批量还原。这个流程我用了小半年，效率比对着十六进制堆栈发呆高得多。

5.3 调试组合拳：一套开发期联调的完整流程

综合三个方案，我日常开发期的调试流程是这样的：

• 本地跑Unity Editor时，直接用Console看C#日志，此时方案一不启用也无所谓，因为Editor自带日志窗口。
• 冲一次WebGL构建做联调时，打开浏览器DevTools，正式加载方案一的jslib桥接 + 方案二的全局监听。这个时候报错既能看到Unity日志，也能看到JS侧的完整调用栈。
• 准备发版时，跑构建期注入脚本（方案三），让每次构建产物都自动带上线上上报能力。

这套组合拳打通后，我后来接到线上反馈基本不再需要用户开DevTools截图，后台能直接看到错误堆栈、浏览器版本、执行到哪个关卡。尤其是在做一些营销页H5游戏时，跨团队协作的时候直接把日志链接丢给前端负责人，省掉大量"复现不了、本地正常"的循环沟通。

最后分享一个小技巧：在Unity WebGL中，如果你用了第三方JS SDK（比如统计SDK、广告SDK），SDK自己可能也会捕获并吞掉错误，导致你的全局监听拿不到。遇到这种情况，可以在DevTools的Source面板里给SDK的catch地方打断点，或者在集成SDK时主动关闭SDK的"自动上报错误"选项，把错误统一交给自己的上报体系来处理。这是我被广告SDK坑了一整天后总结出来的，希望对你有用。