开发WebGL版Unity项目时最绕不开的一个坎就是Unity和浏览器页面之间的通信。我最初接触这个需求是做某跨平台系统的3D看房模块Unity负责渲染模型和交互前端负责页面框架和业务逻辑两边各干各的倒还省心一旦需要Unity告诉前端“用户点开了某个户型”或者前端让Unity“切换到夜景模式”问题就来了Unity跑在Canvas里像一座孤岛C#代码和JavaScript代码根本不在一个世界怎么把消息递过去我试过不少方案也踩过不少坑这篇文章就把Unity WebGL和前端通信的几种主流方式完整梳理一遍从基础的SendMessage到jslib插件再到URL传参和WebSocket中继每种方案适合什么场景、具体怎么落地、有哪些隐藏的坑都给你讲清楚。1. 整体思路拆解双向通信的本质是什么先理解一下为什么Unity WebGL和前端通信这么特殊。Unity项目发布成WebGL后整个游戏引擎会被编译成asm.js或WebAssembly跑在浏览器里的一块独立内存空间中。浏览器的JavaScript代码默认无法直接访问这块内存C#代码也无法直接调用浏览器里的DOM API两边像两个不同国家的人语言不通边界明确。通信的本质就是在这两个世界之间建立一座桥。桥的方向有两类第一类是浏览器把消息传给Unity典型场景是前端页面上有个按钮点击后触发Unity里的某个C#方法第二类是Unity把消息传给浏览器典型场景是Unity里的角色完成某个动作后需要更新页面上的数据或弹出提示框。搞清楚方向之后还要考虑消息本身是什么形式。是简单的字符串和数字还是复杂的对象和数组是一次性的指令还是需要持续交互的实时数据通信频率高不高要不要支持Unity主动推送这些问题直接决定了你该选哪种方案。我把通信方案大致分成四个梯队浏览器调用Unity官方提供的SendMessage是最直接的方式性能好、易调试。Unity调用浏览器Application.ExternalCall是老牌方案但在新版本里有不少限制jslib插件方案更灵活能从底层干预代码。页面级别的参数传递URL传参适合静态初始化localStorage适合数据读取。网络层面的通信WebSocket或HTTP请求适合高频率、双通道、跨域复杂交互。选型逻辑很简单能用SendMessage解决的不要碰jslib能用jslib解决的不要上WebSocket链路越短排查问题越容易。下面我把每种方案拆开讲。2. 基础通信直通车SendMessage完成前端调用Unity2.1 核心API与脚本挂载规范SendMessage是Unity官方提供的桥接接口使用方法非常简单。假设Unity场景里有一个GameObject叫作“NativeBridge”它上面挂了一个C#脚本脚本里定义了一个公开方法ReceiveMessagepublic class NativeBridge : MonoBehaviour { public void ReceiveMessage(string message) { Debug.Log([Unity] 收到消息: message); // 根据消息内容执行对应逻辑 } }前端JavaScript调用时写法如下// 第三个参数可以是字符串、数字也可以是不传 unityInstance.SendMessage(NativeBridge, ReceiveMessage, hello from browser);第二个参数是GameObject的名称第二个是方法名第三个是参数。需要注意的是这个方法必须是public的而且最好避免重载。Unity WebGL的SendMessage只支持单个参数参数类型可以是string、number或boolean但不支持对象、数组等复杂结构。如果需要传复杂数据前端先把数据JSON.stringify成一个字符串C#端再解析这是最通用的做法。很多人第一次用SendMessage时会遇到一个典型错误页面控制台上报“SendMessage is not defined”或者“Cannot send message to unknown object”。前者说明unityInstance对象还没拿到后者说明GameObject名字写错了或者这个对象处于未激活状态。还有一种情况经常被忽略如果GameObject在场景加载时就被SetActive(false)SendMessage同样会失败因为引擎在查找对象时默认跳过未激活的物体。所以桥接用的GameObject最好不要做显式隐藏哪怕不渲染任何东西也要保持激活状态。2.2 unityInstance对象何时拿、怎么存用过Unity 2020以后版本的人都知道加载器返回的实例已经不是全局变量了必须通过配置文件里的onProgress和onLoaded回调去拿。加载器初始化代码通常长这样var unityInstance null; function createUnityInstance(canvas, config, onProgress) { // Unity生成的配置文件里会有这个方法不同版本细节不同 } // 加载完成后保存实例 config.onLoaded function (instance) { unityInstance instance; };更稳妥的做法是封装成一个加载器模块把unityInstance暴露成一个全局Promise这样页面其他模块什么时候调用SendMessage都能保证实例已经就绪let unityReadyPromise; function loadUnity() { if (!unityReadyPromise) { unityReadyPromise new Promise((resolve, reject) { // 这里发起Unity加载加载完成后resolve(unityInstance) }); } return unityReadyPromise; } // 业务代码里这样用 loadUnity().then(instance { instance.SendMessage(NativeBridge, ReceiveMessage, ready); });我建议在项目初始化时就搭建这个Promise否则如果Unity加载没完成页面上的按钮就被用户点击了SendMessage就会落空。等真正踩过这个坑再去改代码测试成本会高出很多。2.3 SendMessage的参数极限与类型陷阱再强调一下类型问题。SendMessage支持的三种类型中最容易出问题的是数字。Unity引擎底层的判断方式是优先当作字符串只有当浏览器传入的值类型是number时才会转换。如果你写unityInstance.SendMessage(NativeBridge, SetScore, 100);C#端对应的方法是public void SetScore(int score) { }这是可行的。但如果你写的是unityInstance.SendMessage(NativeBridge, SetScore, 100);C#端方法参数是intUnity会尝试做一次类型转换通常是能成功的但如果你传的字符串是“abc”就会静默失败控制台还不一定报错。我建议在C#端统一接收string参数然后用int.TryParse去转这样不管前端传的是数字还是字符串都不会崩。顺带提一个常见问题方法名大小写敏感。JavaScript里调SendMessage传方法名必须和C#方法名严格一致Unity不会帮你做模糊匹配这个错误排查起来很隐蔽因为C#方法名习惯用Pascal命名前端工程师写JavaScript时习惯用驼峰两者一混找半天都找不出原因。3. Unity主动说话jslib插件方案正式登场3.1 为什么老方案ExternalCall不够用Unity调用浏览器方向以前有一个简单的接口叫Application.ExternalCall前端挂一个全局函数Unity里直接调Application.ExternalCall(ShowToast, hello);前端只需要在window上定义ShowToast函数即可。早期版本用得很欢但Unity 2018以后官方已经不建议在WebGL上使用ExternalCall了尤其是在使用WebAssemblyWasm时。原因有两个一是ExternalCall依赖Unity的底层桥接参数在C#和JS之间传递时性能较差二是它无法访问Unity运行时内部数据在一些需要频繁交互的场景下会因为转换开销产生卡顿。更核心的问题是ExternalCall只能单向调用一个预先定义好的全局函数不能和Unity构建产物内部做深度交互。真正被广泛接受的做法是插件方案jslib它允许你编写一个JavaScript文件让C#通过[DllImport]的方式直接调用其中的函数。虽然名字叫DllImport在这里实际上是链接到WebGL构建产物里的JavaScript代码。3.2 jslib文件的完整结构与源码级别解析jslib文件本质上是一个JavaScript模块用mergeInto或者LibraryManager的方式链接到Unity的构建产物中。Unity官方推荐使用mergeInto但新版本也支持纯ESModule风格的写法。最基础的结构长这样mergeInto(LibraryManager.library, { // 这里暴露给C#的函数 JS_ShowMessage: function (message) { // 浏览器环境里做点什么事情 window.showMessageFromUnity(UTF8ToString(message)); }, // 也可以定义主动调用C#的方法但一般用SendMessage做桥梁 });对应的C#端声明using System.Runtime.InteropServices; public class NativeBridge : MonoBehaviour { [DllImport(__Internal)] private static extern void JS_ShowMessage(string message); public void CallBrowser() { JS_ShowMessage(来自Unity的消息); } }注意[DllImport]的名字只能写“__Internal”这是Unity WebGL内部约定的特殊库名。编译时Unity构建系统会把jslib文件和C#函数做链接函数名必须严格对应不然编译期不报错运行时调用会直接失败控制台通常只会出现“Cannot find function”的相关错误。3.3 传字符串必须用UTF8ToString解码初次上手jslib的人最容易掉进编码坑。在C#端调用JS_ShowMessage传入的是一个C# string但到了JavaScript端它并不是原生字符串而是一个指向Unity内存块的指针。你直接拿这个值去做加法或者拼接字符串看到的结果会是数字而不是文字。正确做法是在JS函数体内部第一行调用UTF8ToString(ptr)把指针解码成JavaScript字符串JS_ShowMessage: function (ptr) { var message UTF8ToString(ptr); console.log(message); }反过来如果JavaScript想给C#传字符串比如用allocateUTF8分配内存var buffer allocateUTF8(some string); // 然后调用C#方法传buffer _free(buffer);这类内存管理细节官方文档上写得很简短但实际项目中踩一次就够呛忘记释放buffer会在Unity的内存堆里越积越多长时间运行后可能出现WebGL内存不足的问题。3.4 从jslib主动回调C#方法的双通道姿势jslib里也可以调用Unity里的C#方法这时并不需要反过来用DllImport而是直接借助unityInstance全局对象。比如浏览器里的某个外部JS模块想通知UnityJS_NotifyUnity: function () { unityInstance.SendMessage(NativeBridge, OnExternalEvent, something happened); }这样就把第一条链路也打通了。但这有个前提unityInstance在jslib里必须可见。如果你的项目用了模块化打包unityInstance不是全局变量jslib里就访问不到它。我建议在加载Unity时专门挂一个全局引用window.unityInstance instance;然后在jslib里统一用window.unityInstance去访问避免作用域问题。3.5 使用jslib方案需要知道的构建注意事项jslib文件要放在Assets/Plugins/WebGL目录下或者子目录里Unity构建时会自动收集。构建时启用“Linker Options”里的“Enable Exceptions”之类不会影响jslib的加载但需要确认构建产物是否支持你使用的JS特性。如果你的项目开启了代码裁剪Managed Stripping Level设为Low或Mediumjslib引用的C#方法是有可能被裁剪掉的。抑或在某些情况下函数的类名变更导致引用失效。Unity 2021以后部分旧式JS方法如UnityLoader已经被移除必须使用新的加载器API。4. 跨过边界页面级传参与数据持久化技巧4.1 URL参数实现静态初始化在Unity加载之前前端已经知道要传什么参数了这时候用URL传参是最省事的。比如同一个Unity构建想复用给多个业务场景每个场景对应不同的项目IDURL后面拼一个参数// 前端加载Unity时从地址栏取参数 const queryParams new URLSearchParams(window.location.search); const projectId queryParams.get(projectId);Unity端获取方式比较隐蔽需要通过jslib从浏览器地址栏拿然后用C#去接收。jslib里写一个函数JS_GetProjectId: function () { var params new URLSearchParams(window.location.search); var id params.get(projectId); if (id) { var buffer allocateUTF8(id); return buffer; } return 0; }C#端[DllImport(__Internal)] private static extern string JS_GetProjectId();这种方式适合启动后不再变化的数据比如项目编号、皮肤主题、楼层ID。不值得为它专门走网络请求否则Unity加载前前端还得等一个接口增加复杂度。4.2 localStorage与sessionStorage的适用场景URL传参适合一次性初始化但如果通信发生在Unity加载后比如前端页面在某个时刻把用户的权限配置写进了localStorageUnity需要读取时可以走jslib通道。localStorage的好处是不受跨域限制同源策略对同源页面无效、刷新后数据还在适合保存一些中低频更新的业务状态。在jslib里写一个读取函数即可JS_GetLocalStorage: function (key) { var value localStorage.getItem(UTF8ToString(key)); if (value) { return allocateUTF8(value); } return 0; }需要注意localStorage的容量一般限制在5MB左右尽量不要存大批量数据否则容易被浏览器清理或者写入失败。另外Unity本身的项目存档PlayerPrefs在WebGL上默认就是存在IndexedDB里的如果你需要把PlayerPrefs的数据同步给前端也可以通过localStorage做一次中转但要考虑到两者更新时机不同步的问题避免出现脏读。4.3 页面生命周期与Unity加载时机的协同我见过不少项目把URL参数和localStorage都用了结果还是出现“Unity读取到空数据”的问题。排查后才发现是前端在Unity还没加载完时就执行了写入而Unity读到的其实是写入前的旧数据。稳定的做法是在Unity加载完成的回调里通知前端前端再接下去执行数据写入。比如加载器加载结束后调用一下SendMessage通知Unity“已就绪”或者调用前端暴露的全局回调config.onLoaded function (instance) { window.unityInstance instance; // 通知其他地方Unity已经可以接收消息 window.dispatchEvent(new CustomEvent(unityLoaded)); };这样所有业务代码监听unityLoaded事件再去写入localStorage或者调用SendMessage就不会出现时序问题了。5. 终极灵活WebSocket与信号中转架构5.1 什么情况下需要WebSocket中继上面所有方案都要求Unity和前端在同一个页面里直接或者间接共享内存访问。但有的项目做不到这一点Unity构建可能被嵌在跨域的iframe里或者Unity承载在某个A页面而控制端是B页面。这种情况下页面内通信方案全部失效我建议引入WebSocket中继服务器。这种架构其实很常见前端平台是一个管理后台Unity是一个可视化播放器。管理后台下发指令“打开设备列表”通过WebSocket发给中继服务中继服务再推给Unity所在的页面Unity的jslib收到后调用C#方法执行显示逻辑。反过来Unity上报状态也通过同一个中继服务转发给管理后台。5.2 中继服务的心跳与广播设计中继服务最简单的实现是用Node.js的ws库或者用原生的WebSocket API。核心逻辑是维护一个客户端列表每个客户端上报自己的标识服务端根据标识定向转发消息。伪代码如下const ws new WebSocketServer({ port: 8080 }); const clients new Map(); ws.on(connection, (socket) { socket.on(message, (message) { const data JSON.parse(message); if (data.type register) { clients.set(data.id, socket); } else if (data.type forward) { const target clients.get(data.targetId); if (target) { target.send(JSON.stringify(data.payload)); } } }); socket.on(close, () { // 清理连接 }); });前端和Unity都作为WebSocket客户端接入。Unity端不能直接用C#自带的WebSocket类因为WebGL平台有专门限制必须通过jslib创建WebSocket。这部分代码写起来略显繁琐需要封装连接、重连、二进制消息处理等逻辑。5.3 Unity端jslib包装WebSocket的思路在jslib里创建一个WebSocket实例然后把事件映射到C#方法。一个简化的思路是JS原生WebSocket的onmessage回调里把收到的文本数据转成字符串指针然后调用C#的OnMessageReceived方法。C#端对外暴露OnConnected、OnDisconnected、OnMessageReceived三个公开方法。连接断开后在JS层做指数退避重连Unity侧只需要处理“是否在线”的状态变化。这样做的好处是C#脚本里写业务逻辑时只需要关心连接状态和数据内容不用去管浏览器API细节维护成本比较低。5.4 实时场景Unity状态上报双通道机制如果你的Unity场景里有一个模型它在持续旋转或者移动需要实时把坐标同步给前端展示要注意频率控制。WebSocket消息塞得太频繁浏览器主线程会被大量消息事件淹没导致页面卡顿。我建议Unity端在jslib的WebSocket发送函数内部做合并定时器每100毫秒批量发送一次状态帧而不是每帧发送。或者Unity侧只在上一次发送完成且状态有变化时才发送新消息。前端接收端也可以做节流比如更新DOM的频率控制在每秒10次以内数据帧再多也只取最近一帧渲染。5.5 中继架构的典型坑与容错方案WebSocket中继方案看着灵活坑也不少网络断开后自动重连的时机要配合Unity的暂停逻辑否则Unity在后台时重连会失败。多个Unity实例同时连接同一中继时消息定向channel要设计好比如约定好“clientId 消息类型”的路由规则。中继服务器重启时客户端要能自动重连否则业务就断在那里了。如果为了省服务器资源而改用轮询HTTP接口高频情况下请求开销很大而且无法做到服务端主动推送体验会差一截。中继方案的成本高于前几种但跨页面跨终端场景下基本是唯一解。我的建议是先判断业务是否真的需要跨域不要为了炫技强行上WebSocket。6. 常见问题速查通信失败排查实录这里把我在实际项目中遇到的通信问题整理成表格方便你对号入座。现象常见原因解决方案SendMessage找不到对象GameObject名称拼写错误或对象未激活检查场景层级确保桥接对象保持激活名称完全一致SendMessage方法不执行方法不是public或者方法名大小写不匹配改成public方法逐一核对大小写传中文参数乱码jslib里使用UTF8ToString未正确解码在JS函数内部先解码再使用ExternalCall不生效Unity版本较新API被废弃改用jslib插件方式jslib函数找不到函数名和C#声明不一致或者没有加__Internal检查DllImport声明和jslib函数名页面刷新后Unity状态丢失PlayerPrefs依赖IndexedDB刷新时序不对通过localStorage显式保存加载完成后恢复WebSocket频繁断连心跳机制没做好或者服务端主动断开加入心跳包间隔30秒检测一次消息顺序错乱消息发送频率太高多个通道并发在C#端加消息队列串行处理Unity加载时页面卡死消息积压渲染线程被阻塞合并高频消息节流更新较新Unity版本下旧方案失效加载器API变动升级代码到新API参考官方加载器全局示例6.1 调试技巧在浏览器控制台手动验证通信链路排查通信问题时我习惯先做一个最小验证手动在浏览器控制台执行一次SendMessage确认Unity侧有反应。这一步能快速区分问题是出在前端代码还是Unity代码。执行之前先全局搜一下window.unityInstance是否有值console.log(window.unityInstance);如果没有值说明实例保存方式有问题先修加载器。如果有值再执行window.unityInstance.SendMessage(NativeBridge, DebugLog, test);Unity侧DebugLog方法里打印一条日志如果打印出来了说明底层链路是通的剩下的问题就是业务参数或者消息格式了。这个两步排查法至今还在我的日常工作流里比翻半天代码快得多。6.2 前端工程师视角的有效协作建议Unity开发者往往只关心C#侧的问题前端工程师只关心JS侧的问题导致通信故障时双方互相甩锅。我在实践中发现最有效的办法是约定一份“通信协议文档”把消息名称、参数类型、触发时机、返回值格式都列出来。比如{ action: switchScene, sceneId: room01, transition: fade }Unity端统一接收一个字符串前端统一发送JSON字符串两边用同一种Schema校验。这样即使出了问题也能根据协议快速定位是哪一侧不符合约定。7. 工具链选型与实用封装建议7.1 官方build模板里的关键信息解读Unity在发布WebGL时会生成一个Build目录里面有Loader.js、Framework.js、Wasm文件等。如果你使用的是Unity 2020及以上的版本它不再使用传统的UnityLoader.js而是采用新的“Build Report”和“Loader”体系页面上需要自己写加载逻辑。我建议在Unity的Player Settings里开启“Compression Format”并选择Brotli可以大幅减少下载体积但要注意服务器需要配置Content-Encoding响应头否则浏览器解压不了白屏排查会很痛苦。还有一个容易忽略的点WebGL构建产物非常大动辄几十MB加载期间页面很容易在移动设备上内存不足。如果你的前端页面要支持旧机型应该在加载时设置一个loading覆盖层并监控Unity加载器提供的onProgress回调展示真实的下载进度百分比。7.2 通信代码如何抽象成一个通用模块无论你选择哪种方案我建议把通信代码单独抽象成一个模块不要在业务代码里散落SendMessage调用。Unity侧的C#可以做一个MessageDispatcher单例统一接收字符串消息再按约定分发到各个系统前端侧做一个UnityBridge的JS类封装SendMessage和事件注册。这样两个团队各自维护自己的通信层改协议时不用在几十个文件里找散落的调用点。消息格式我倾向于使用这样的JSON结构{ msgId: unique_id_001, type: command, action: showModel, data: { modelId: xxx } }msgId用于日志追踪type区分command/event/requestaction表示具体操作data放业务数据。Unity端解析时只关心action和data其他字段用于诊断非常实用。7.3 跨团队协作时如何制定通信契约在跨团队协作的项目里通信问题的根源往往不是技术实现而是双方对消息格式的理解不一致。前端给Unity传了一组经纬度坐标Unity侧却需要字符串的逗号分隔格式Unity侧发了一个数字表示房型编号前端却当成字符串在和接口对接。这类问题最好的解决办法是在项目初期就写一份“消息字典”。消息字典长这样消息名方向参数结构触发时机示例switchScene前端→UnitysceneId: string, transition?: string用户点击场景切换按钮{sceneId:room01,transition:fade}modelLoadedUnity→前端modelName: string, loadTime: numberUnity模型加载完成时{modelName:bed01,loadTime:1200}getState前端→Unity无页面刷新后请求当前状态{}把这张表共享给前后端团队双方按表里的字段名开发至少能避免一半的联调返工。8. 我个人的选型心得与建议不同的通信方案本质上是在复杂度和实时性之间做取舍。如果你只需要前端触发Unity播放一个动画SendMessage足够不要因为觉得“官方接口不够高级”而引入jslib。如果你需要Unity把日志实时推给前端控制台jslib是最合适的代码量少、链路短、几乎没有额外服务器成本。如果业务里有多页面、跨终端的强交互需求WebSocket中继虽然成本高但能保证后续扩展性。我自己在实际项目中通常这样定同一个页面内的交互优先用SendMessage加jslib组合Unity主动上报低频状态用jslib里的回调高频实时数据走WebSocket静态初始化参数走URL。这四类需求覆盖了绝大部分业务场景也是我目前见过最不容易出错的组合。最后分享一个小技巧如果Unity和前端联调时发现消息偶尔丢失先不要急着怀疑网络或者引擎而是看一看是不是Unity侧的Update循环里处理了耗时操作。WebGL是单线程模型主线程被卡住的时候所有外部消息事件都会被排队表现就是消息延迟或丢失。把耗时操作放到协程或者分开到多帧执行通信稳定性会有质的提升。这个项目做完之后我最大的体会是通信方案本身不复杂复杂的是边界条件。每个不明确的消息格式、每次隐藏的对象命名错误、每个不经意的全局变量覆盖都可能让一次简单通信变成半天联调。把边界情况在文档里写清楚把通信层封装干净后续的迭代维护会轻松得多。 
长河君 · 2026/10/17 18:34:01 · 阅读 1.2k Unity WebGL与前端通信全指南：从SendMessage到WebSocket
开发WebGL版Unity项目时最绕不开的一个坎就是Unity和浏览器页面之间的通信。我最初接触这个需求是做某跨平台系统的3D看房模块Unity负责渲染模型和交互前端负责页面框架和业务逻辑两边各干各的倒还省心一旦需要Unity告诉前端“用户点开了某个户型”或者前端让Unity“切换到夜景模式”问题就来了Unity跑在Canvas里像一座孤岛C#代码和JavaScript代码根本不在一个世界怎么把消息递过去我试过不少方案也踩过不少坑这篇文章就把Unity WebGL和前端通信的几种主流方式完整梳理一遍从基础的SendMessage到jslib插件再到URL传参和WebSocket中继每种方案适合什么场景、具体怎么落地、有哪些隐藏的坑都给你讲清楚。1. 整体思路拆解双向通信的本质是什么先理解一下为什么Unity WebGL和前端通信这么特殊。Unity项目发布成WebGL后整个游戏引擎会被编译成asm.js或WebAssembly跑在浏览器里的一块独立内存空间中。浏览器的JavaScript代码默认无法直接访问这块内存C#代码也无法直接调用浏览器里的DOM API两边像两个不同国家的人语言不通边界明确。通信的本质就是在这两个世界之间建立一座桥。桥的方向有两类第一类是浏览器把消息传给Unity典型场景是前端页面上有个按钮点击后触发Unity里的某个C#方法第二类是Unity把消息传给浏览器典型场景是Unity里的角色完成某个动作后需要更新页面上的数据或弹出提示框。搞清楚方向之后还要考虑消息本身是什么形式。是简单的字符串和数字还是复杂的对象和数组是一次性的指令还是需要持续交互的实时数据通信频率高不高要不要支持Unity主动推送这些问题直接决定了你该选哪种方案。我把通信方案大致分成四个梯队浏览器调用Unity官方提供的SendMessage是最直接的方式性能好、易调试。Unity调用浏览器Application.ExternalCall是老牌方案但在新版本里有不少限制jslib插件方案更灵活能从底层干预代码。页面级别的参数传递URL传参适合静态初始化localStorage适合数据读取。网络层面的通信WebSocket或HTTP请求适合高频率、双通道、跨域复杂交互。选型逻辑很简单能用SendMessage解决的不要碰jslib能用jslib解决的不要上WebSocket链路越短排查问题越容易。下面我把每种方案拆开讲。2. 基础通信直通车SendMessage完成前端调用Unity2.1 核心API与脚本挂载规范SendMessage是Unity官方提供的桥接接口使用方法非常简单。假设Unity场景里有一个GameObject叫作“NativeBridge”它上面挂了一个C#脚本脚本里定义了一个公开方法ReceiveMessagepublic class NativeBridge : MonoBehaviour { public void ReceiveMessage(string message) { Debug.Log([Unity] 收到消息: message); // 根据消息内容执行对应逻辑 } }前端JavaScript调用时写法如下// 第三个参数可以是字符串、数字也可以是不传 unityInstance.SendMessage(NativeBridge, ReceiveMessage, hello from browser);第二个参数是GameObject的名称第二个是方法名第三个是参数。需要注意的是这个方法必须是public的而且最好避免重载。Unity WebGL的SendMessage只支持单个参数参数类型可以是string、number或boolean但不支持对象、数组等复杂结构。如果需要传复杂数据前端先把数据JSON.stringify成一个字符串C#端再解析这是最通用的做法。很多人第一次用SendMessage时会遇到一个典型错误页面控制台上报“SendMessage is not defined”或者“Cannot send message to unknown object”。前者说明unityInstance对象还没拿到后者说明GameObject名字写错了或者这个对象处于未激活状态。还有一种情况经常被忽略如果GameObject在场景加载时就被SetActive(false)SendMessage同样会失败因为引擎在查找对象时默认跳过未激活的物体。所以桥接用的GameObject最好不要做显式隐藏哪怕不渲染任何东西也要保持激活状态。2.2 unityInstance对象何时拿、怎么存用过Unity 2020以后版本的人都知道加载器返回的实例已经不是全局变量了必须通过配置文件里的onProgress和onLoaded回调去拿。加载器初始化代码通常长这样var unityInstance null; function createUnityInstance(canvas, config, onProgress) { // Unity生成的配置文件里会有这个方法不同版本细节不同 } // 加载完成后保存实例 config.onLoaded function (instance) { unityInstance instance; };更稳妥的做法是封装成一个加载器模块把unityInstance暴露成一个全局Promise这样页面其他模块什么时候调用SendMessage都能保证实例已经就绪let unityReadyPromise; function loadUnity() { if (!unityReadyPromise) { unityReadyPromise new Promise((resolve, reject) { // 这里发起Unity加载加载完成后resolve(unityInstance) }); } return unityReadyPromise; } // 业务代码里这样用 loadUnity().then(instance { instance.SendMessage(NativeBridge, ReceiveMessage, ready); });我建议在项目初始化时就搭建这个Promise否则如果Unity加载没完成页面上的按钮就被用户点击了SendMessage就会落空。等真正踩过这个坑再去改代码测试成本会高出很多。2.3 SendMessage的参数极限与类型陷阱再强调一下类型问题。SendMessage支持的三种类型中最容易出问题的是数字。Unity引擎底层的判断方式是优先当作字符串只有当浏览器传入的值类型是number时才会转换。如果你写unityInstance.SendMessage(NativeBridge, SetScore, 100);C#端对应的方法是public void SetScore(int score) { }这是可行的。但如果你写的是unityInstance.SendMessage(NativeBridge, SetScore, 100);C#端方法参数是intUnity会尝试做一次类型转换通常是能成功的但如果你传的字符串是“abc”就会静默失败控制台还不一定报错。我建议在C#端统一接收string参数然后用int.TryParse去转这样不管前端传的是数字还是字符串都不会崩。顺带提一个常见问题方法名大小写敏感。JavaScript里调SendMessage传方法名必须和C#方法名严格一致Unity不会帮你做模糊匹配这个错误排查起来很隐蔽因为C#方法名习惯用Pascal命名前端工程师写JavaScript时习惯用驼峰两者一混找半天都找不出原因。3. Unity主动说话jslib插件方案正式登场3.1 为什么老方案ExternalCall不够用Unity调用浏览器方向以前有一个简单的接口叫Application.ExternalCall前端挂一个全局函数Unity里直接调Application.ExternalCall(ShowToast, hello);前端只需要在window上定义ShowToast函数即可。早期版本用得很欢但Unity 2018以后官方已经不建议在WebGL上使用ExternalCall了尤其是在使用WebAssemblyWasm时。原因有两个一是ExternalCall依赖Unity的底层桥接参数在C#和JS之间传递时性能较差二是它无法访问Unity运行时内部数据在一些需要频繁交互的场景下会因为转换开销产生卡顿。更核心的问题是ExternalCall只能单向调用一个预先定义好的全局函数不能和Unity构建产物内部做深度交互。真正被广泛接受的做法是插件方案jslib它允许你编写一个JavaScript文件让C#通过[DllImport]的方式直接调用其中的函数。虽然名字叫DllImport在这里实际上是链接到WebGL构建产物里的JavaScript代码。3.2 jslib文件的完整结构与源码级别解析jslib文件本质上是一个JavaScript模块用mergeInto或者LibraryManager的方式链接到Unity的构建产物中。Unity官方推荐使用mergeInto但新版本也支持纯ESModule风格的写法。最基础的结构长这样mergeInto(LibraryManager.library, { // 这里暴露给C#的函数 JS_ShowMessage: function (message) { // 浏览器环境里做点什么事情 window.showMessageFromUnity(UTF8ToString(message)); }, // 也可以定义主动调用C#的方法但一般用SendMessage做桥梁 });对应的C#端声明using System.Runtime.InteropServices; public class NativeBridge : MonoBehaviour { [DllImport(__Internal)] private static extern void JS_ShowMessage(string message); public void CallBrowser() { JS_ShowMessage(来自Unity的消息); } }注意[DllImport]的名字只能写“__Internal”这是Unity WebGL内部约定的特殊库名。编译时Unity构建系统会把jslib文件和C#函数做链接函数名必须严格对应不然编译期不报错运行时调用会直接失败控制台通常只会出现“Cannot find function”的相关错误。3.3 传字符串必须用UTF8ToString解码初次上手jslib的人最容易掉进编码坑。在C#端调用JS_ShowMessage传入的是一个C# string但到了JavaScript端它并不是原生字符串而是一个指向Unity内存块的指针。你直接拿这个值去做加法或者拼接字符串看到的结果会是数字而不是文字。正确做法是在JS函数体内部第一行调用UTF8ToString(ptr)把指针解码成JavaScript字符串JS_ShowMessage: function (ptr) { var message UTF8ToString(ptr); console.log(message); }反过来如果JavaScript想给C#传字符串比如用allocateUTF8分配内存var buffer allocateUTF8(some string); // 然后调用C#方法传buffer _free(buffer);这类内存管理细节官方文档上写得很简短但实际项目中踩一次就够呛忘记释放buffer会在Unity的内存堆里越积越多长时间运行后可能出现WebGL内存不足的问题。3.4 从jslib主动回调C#方法的双通道姿势jslib里也可以调用Unity里的C#方法这时并不需要反过来用DllImport而是直接借助unityInstance全局对象。比如浏览器里的某个外部JS模块想通知UnityJS_NotifyUnity: function () { unityInstance.SendMessage(NativeBridge, OnExternalEvent, something happened); }这样就把第一条链路也打通了。但这有个前提unityInstance在jslib里必须可见。如果你的项目用了模块化打包unityInstance不是全局变量jslib里就访问不到它。我建议在加载Unity时专门挂一个全局引用window.unityInstance instance;然后在jslib里统一用window.unityInstance去访问避免作用域问题。3.5 使用jslib方案需要知道的构建注意事项jslib文件要放在Assets/Plugins/WebGL目录下或者子目录里Unity构建时会自动收集。构建时启用“Linker Options”里的“Enable Exceptions”之类不会影响jslib的加载但需要确认构建产物是否支持你使用的JS特性。如果你的项目开启了代码裁剪Managed Stripping Level设为Low或Mediumjslib引用的C#方法是有可能被裁剪掉的。抑或在某些情况下函数的类名变更导致引用失效。Unity 2021以后部分旧式JS方法如UnityLoader已经被移除必须使用新的加载器API。4. 跨过边界页面级传参与数据持久化技巧4.1 URL参数实现静态初始化在Unity加载之前前端已经知道要传什么参数了这时候用URL传参是最省事的。比如同一个Unity构建想复用给多个业务场景每个场景对应不同的项目IDURL后面拼一个参数// 前端加载Unity时从地址栏取参数 const queryParams new URLSearchParams(window.location.search); const projectId queryParams.get(projectId);Unity端获取方式比较隐蔽需要通过jslib从浏览器地址栏拿然后用C#去接收。jslib里写一个函数JS_GetProjectId: function () { var params new URLSearchParams(window.location.search); var id params.get(projectId); if (id) { var buffer allocateUTF8(id); return buffer; } return 0; }C#端[DllImport(__Internal)] private static extern string JS_GetProjectId();这种方式适合启动后不再变化的数据比如项目编号、皮肤主题、楼层ID。不值得为它专门走网络请求否则Unity加载前前端还得等一个接口增加复杂度。4.2 localStorage与sessionStorage的适用场景URL传参适合一次性初始化但如果通信发生在Unity加载后比如前端页面在某个时刻把用户的权限配置写进了localStorageUnity需要读取时可以走jslib通道。localStorage的好处是不受跨域限制同源策略对同源页面无效、刷新后数据还在适合保存一些中低频更新的业务状态。在jslib里写一个读取函数即可JS_GetLocalStorage: function (key) { var value localStorage.getItem(UTF8ToString(key)); if (value) { return allocateUTF8(value); } return 0; }需要注意localStorage的容量一般限制在5MB左右尽量不要存大批量数据否则容易被浏览器清理或者写入失败。另外Unity本身的项目存档PlayerPrefs在WebGL上默认就是存在IndexedDB里的如果你需要把PlayerPrefs的数据同步给前端也可以通过localStorage做一次中转但要考虑到两者更新时机不同步的问题避免出现脏读。4.3 页面生命周期与Unity加载时机的协同我见过不少项目把URL参数和localStorage都用了结果还是出现“Unity读取到空数据”的问题。排查后才发现是前端在Unity还没加载完时就执行了写入而Unity读到的其实是写入前的旧数据。稳定的做法是在Unity加载完成的回调里通知前端前端再接下去执行数据写入。比如加载器加载结束后调用一下SendMessage通知Unity“已就绪”或者调用前端暴露的全局回调config.onLoaded function (instance) { window.unityInstance instance; // 通知其他地方Unity已经可以接收消息 window.dispatchEvent(new CustomEvent(unityLoaded)); };这样所有业务代码监听unityLoaded事件再去写入localStorage或者调用SendMessage就不会出现时序问题了。5. 终极灵活WebSocket与信号中转架构5.1 什么情况下需要WebSocket中继上面所有方案都要求Unity和前端在同一个页面里直接或者间接共享内存访问。但有的项目做不到这一点Unity构建可能被嵌在跨域的iframe里或者Unity承载在某个A页面而控制端是B页面。这种情况下页面内通信方案全部失效我建议引入WebSocket中继服务器。这种架构其实很常见前端平台是一个管理后台Unity是一个可视化播放器。管理后台下发指令“打开设备列表”通过WebSocket发给中继服务中继服务再推给Unity所在的页面Unity的jslib收到后调用C#方法执行显示逻辑。反过来Unity上报状态也通过同一个中继服务转发给管理后台。5.2 中继服务的心跳与广播设计中继服务最简单的实现是用Node.js的ws库或者用原生的WebSocket API。核心逻辑是维护一个客户端列表每个客户端上报自己的标识服务端根据标识定向转发消息。伪代码如下const ws new WebSocketServer({ port: 8080 }); const clients new Map(); ws.on(connection, (socket) { socket.on(message, (message) { const data JSON.parse(message); if (data.type register) { clients.set(data.id, socket); } else if (data.type forward) { const target clients.get(data.targetId); if (target) { target.send(JSON.stringify(data.payload)); } } }); socket.on(close, () { // 清理连接 }); });前端和Unity都作为WebSocket客户端接入。Unity端不能直接用C#自带的WebSocket类因为WebGL平台有专门限制必须通过jslib创建WebSocket。这部分代码写起来略显繁琐需要封装连接、重连、二进制消息处理等逻辑。5.3 Unity端jslib包装WebSocket的思路在jslib里创建一个WebSocket实例然后把事件映射到C#方法。一个简化的思路是JS原生WebSocket的onmessage回调里把收到的文本数据转成字符串指针然后调用C#的OnMessageReceived方法。C#端对外暴露OnConnected、OnDisconnected、OnMessageReceived三个公开方法。连接断开后在JS层做指数退避重连Unity侧只需要处理“是否在线”的状态变化。这样做的好处是C#脚本里写业务逻辑时只需要关心连接状态和数据内容不用去管浏览器API细节维护成本比较低。5.4 实时场景Unity状态上报双通道机制如果你的Unity场景里有一个模型它在持续旋转或者移动需要实时把坐标同步给前端展示要注意频率控制。WebSocket消息塞得太频繁浏览器主线程会被大量消息事件淹没导致页面卡顿。我建议Unity端在jslib的WebSocket发送函数内部做合并定时器每100毫秒批量发送一次状态帧而不是每帧发送。或者Unity侧只在上一次发送完成且状态有变化时才发送新消息。前端接收端也可以做节流比如更新DOM的频率控制在每秒10次以内数据帧再多也只取最近一帧渲染。5.5 中继架构的典型坑与容错方案WebSocket中继方案看着灵活坑也不少网络断开后自动重连的时机要配合Unity的暂停逻辑否则Unity在后台时重连会失败。多个Unity实例同时连接同一中继时消息定向channel要设计好比如约定好“clientId 消息类型”的路由规则。中继服务器重启时客户端要能自动重连否则业务就断在那里了。如果为了省服务器资源而改用轮询HTTP接口高频情况下请求开销很大而且无法做到服务端主动推送体验会差一截。中继方案的成本高于前几种但跨页面跨终端场景下基本是唯一解。我的建议是先判断业务是否真的需要跨域不要为了炫技强行上WebSocket。6. 常见问题速查通信失败排查实录这里把我在实际项目中遇到的通信问题整理成表格方便你对号入座。现象常见原因解决方案SendMessage找不到对象GameObject名称拼写错误或对象未激活检查场景层级确保桥接对象保持激活名称完全一致SendMessage方法不执行方法不是public或者方法名大小写不匹配改成public方法逐一核对大小写传中文参数乱码jslib里使用UTF8ToString未正确解码在JS函数内部先解码再使用ExternalCall不生效Unity版本较新API被废弃改用jslib插件方式jslib函数找不到函数名和C#声明不一致或者没有加__Internal检查DllImport声明和jslib函数名页面刷新后Unity状态丢失PlayerPrefs依赖IndexedDB刷新时序不对通过localStorage显式保存加载完成后恢复WebSocket频繁断连心跳机制没做好或者服务端主动断开加入心跳包间隔30秒检测一次消息顺序错乱消息发送频率太高多个通道并发在C#端加消息队列串行处理Unity加载时页面卡死消息积压渲染线程被阻塞合并高频消息节流更新较新Unity版本下旧方案失效加载器API变动升级代码到新API参考官方加载器全局示例6.1 调试技巧在浏览器控制台手动验证通信链路排查通信问题时我习惯先做一个最小验证手动在浏览器控制台执行一次SendMessage确认Unity侧有反应。这一步能快速区分问题是出在前端代码还是Unity代码。执行之前先全局搜一下window.unityInstance是否有值console.log(window.unityInstance);如果没有值说明实例保存方式有问题先修加载器。如果有值再执行window.unityInstance.SendMessage(NativeBridge, DebugLog, test);Unity侧DebugLog方法里打印一条日志如果打印出来了说明底层链路是通的剩下的问题就是业务参数或者消息格式了。这个两步排查法至今还在我的日常工作流里比翻半天代码快得多。6.2 前端工程师视角的有效协作建议Unity开发者往往只关心C#侧的问题前端工程师只关心JS侧的问题导致通信故障时双方互相甩锅。我在实践中发现最有效的办法是约定一份“通信协议文档”把消息名称、参数类型、触发时机、返回值格式都列出来。比如{ action: switchScene, sceneId: room01, transition: fade }Unity端统一接收一个字符串前端统一发送JSON字符串两边用同一种Schema校验。这样即使出了问题也能根据协议快速定位是哪一侧不符合约定。7. 工具链选型与实用封装建议7.1 官方build模板里的关键信息解读Unity在发布WebGL时会生成一个Build目录里面有Loader.js、Framework.js、Wasm文件等。如果你使用的是Unity 2020及以上的版本它不再使用传统的UnityLoader.js而是采用新的“Build Report”和“Loader”体系页面上需要自己写加载逻辑。我建议在Unity的Player Settings里开启“Compression Format”并选择Brotli可以大幅减少下载体积但要注意服务器需要配置Content-Encoding响应头否则浏览器解压不了白屏排查会很痛苦。还有一个容易忽略的点WebGL构建产物非常大动辄几十MB加载期间页面很容易在移动设备上内存不足。如果你的前端页面要支持旧机型应该在加载时设置一个loading覆盖层并监控Unity加载器提供的onProgress回调展示真实的下载进度百分比。7.2 通信代码如何抽象成一个通用模块无论你选择哪种方案我建议把通信代码单独抽象成一个模块不要在业务代码里散落SendMessage调用。Unity侧的C#可以做一个MessageDispatcher单例统一接收字符串消息再按约定分发到各个系统前端侧做一个UnityBridge的JS类封装SendMessage和事件注册。这样两个团队各自维护自己的通信层改协议时不用在几十个文件里找散落的调用点。消息格式我倾向于使用这样的JSON结构{ msgId: unique_id_001, type: command, action: showModel, data: { modelId: xxx } }msgId用于日志追踪type区分command/event/requestaction表示具体操作data放业务数据。Unity端解析时只关心action和data其他字段用于诊断非常实用。7.3 跨团队协作时如何制定通信契约在跨团队协作的项目里通信问题的根源往往不是技术实现而是双方对消息格式的理解不一致。前端给Unity传了一组经纬度坐标Unity侧却需要字符串的逗号分隔格式Unity侧发了一个数字表示房型编号前端却当成字符串在和接口对接。这类问题最好的解决办法是在项目初期就写一份“消息字典”。消息字典长这样消息名方向参数结构触发时机示例switchScene前端→UnitysceneId: string, transition?: string用户点击场景切换按钮{sceneId:room01,transition:fade}modelLoadedUnity→前端modelName: string, loadTime: numberUnity模型加载完成时{modelName:bed01,loadTime:1200}getState前端→Unity无页面刷新后请求当前状态{}把这张表共享给前后端团队双方按表里的字段名开发至少能避免一半的联调返工。8. 我个人的选型心得与建议不同的通信方案本质上是在复杂度和实时性之间做取舍。如果你只需要前端触发Unity播放一个动画SendMessage足够不要因为觉得“官方接口不够高级”而引入jslib。如果你需要Unity把日志实时推给前端控制台jslib是最合适的代码量少、链路短、几乎没有额外服务器成本。如果业务里有多页面、跨终端的强交互需求WebSocket中继虽然成本高但能保证后续扩展性。我自己在实际项目中通常这样定同一个页面内的交互优先用SendMessage加jslib组合Unity主动上报低频状态用jslib里的回调高频实时数据走WebSocket静态初始化参数走URL。这四类需求覆盖了绝大部分业务场景也是我目前见过最不容易出错的组合。最后分享一个小技巧如果Unity和前端联调时发现消息偶尔丢失先不要急着怀疑网络或者引擎而是看一看是不是Unity侧的Update循环里处理了耗时操作。WebGL是单线程模型主线程被卡住的时候所有外部消息事件都会被排队表现就是消息延迟或丢失。把耗时操作放到协程或者分开到多帧执行通信稳定性会有质的提升。这个项目做完之后我最大的体会是通信方案本身不复杂复杂的是边界条件。每个不明确的消息格式、每次隐藏的对象命名错误、每个不经意的全局变量覆盖都可能让一次简单通信变成半天联调。把边界情况在文档里写清楚把通信层封装干净后续的迭代维护会轻松得多。