简介：这是一份完整的 Unity 工程资源，演示了如何将项目打包为 WebGL 并在网页端通过 MQTT 协议进行实时通信，适合 Unity 开发者、物联网应用开发者以及需要在浏览器端实现交互式 3D 应用的工程人员。压缩包共 2000 个文件，约 295MB，包含 C# 脚本、Shader、材质、Prefab、FBX 模型、PNG 纹理以及 WebGL 构建产物（.wasm、.js）等类型，目录结构完整覆盖 Assets、ProjectSettings、Packages、Library 与 Logs 等 Unity 标准工程目录。已有 701 人浏览学习。借助该资源可学到 Unity WebGL 导出的关键设置、MQTT 客户端与 Unity 的集成方法，包括服务器参数配置、主题订阅与消息发布机制，同时能从工程目录结构中理解 Unity 项目的依赖管理、构建输出与缓存组织方式，便于二次开发与实际部署。 来聊一个最近在项目中反复打磨的技术组合：Unity 打包 WebGL 并用 MQTT 做实时通信。
这个方案的实际需求其实很常见——你想做一个能在浏览器里直接跑的 3D 交互页面，同时还要实时获取设备或后端下发的数据。比如数字孪生大屏、远程控制面板、工业设备监控、甚至智能家居的场景联动，前端用 Unity WebGL 渲染三维场景，后端或设备端用 MQTT 协议推数据。两边一接，一个能看、能点、能实时刷新的 Web 3D 应用就立住了。
我最早接触这个组合是为了做一个设备监控面板。现场设备通过网关把状态和传感器数据上报到 MQTT Broker，我需要在一个三维场景里实时看到每台设备的运行状态、温度、位置等信息。如果只用传统 HTTP 轮询，数据量大了以后延迟和服务器压力都很头疼。换 MQTT 后，推送是实时的，带宽占用也低。再加上 Unity WebGL 能把三维场景直接嵌进网页，不用额外装插件，整个方案在浏览器端就跑通了。
这篇文章适合两类人看：一类是 Unity 开发者，想把项目导出到 WebGL 并且接入实时数据通道；另一类是前端或物联网开发者，需要在网页里呈现 3D 效果但之前没碰过 Unity 打包。我会把我踩过的坑、实测过的配置、还有代码层面的桥接方案都写出来，按正常走一遍的时间估算，从环境准备到场景里收到第一条 MQTT 消息，一个下午足够。
1. 整体方案设计：先理清数据链路和模块边界
正式开始之前，我建议先花十分钟把整个架构图画清楚，不要一上来就写代码。这个问题如果没想明白，后面很容易卡在"场景里收不到消息""浏览器控制台报错看不懂""连接总是被断"这类泥潭里。
1.1 数据链路到底怎么走
Unity WebGL 跑在浏览器沙箱里，这一点最关键。很多人按桌面端 Unity 的习惯，直接在 C# 里写 MQTT 客户端库，然后打包 WebGL，一跑就发现在浏览器里根本连不上——因为 WebGL 环境下不允许直接用 TCP 套接字，标准 MQTT 基于 TCP 的 1883 端口在浏览器端是不通的。
所以方案要调整为：MQTT.js（跑在浏览器端）作为连接 Broker 的通道，再通过一个 Bridge 把消息从 JavaScript 层转递给 Unity 的 C# 层。实际数据链路是这样：
设备 / 服务端 -> MQTT Broker -> MQTT.js（浏览器端） -> Unity 实例（C# 收到消息） -> 场景更新
反过来，Unity 场景里的操作（比如点击设备、调整参数）也可以通过 Bridge 回传，经 MQTT.js 发布到指定主题，完成双向通信。
1.2 为什么用 WebGL 而不是其他前端方案
说到网页里跑 3D，很多人会先想到 Three.js。如果是纯模型展示、简单交互，Three.js 完全够用，而且生态丰富。但如果你已经有现成的 Unity 工程，里面有复杂物理模拟、粒子系统、后期处理特效、或者已经写好的业务逻辑，想全部搬到 Three.js 重写一遍，成本会非常高。
Unity 打 WebGL 包的优势在于：渲染引擎、物理引擎、动画系统全都给你打包好了，你只需要关注业务逻辑。缺点是包体偏大、加载时间长、性能相比原生客户端有损耗。如果应用场景是"现场数据监控 + 三维可视化"，WebGL 的表现完全够看。
1.3 模块边界划分
我把整个项目拆成三层来管理：
- 表现层：Unity 场景中的各类对象（设备模型、状态灯、数据面板、摄像机控制逻辑）。
- 通信层：MQTT.js 构成，负责与 Broker 的连接、订阅、发布、重连、心跳维护。这一层完全独立，不依赖 Unity 的渲染管线。
- 桥接层：JavaScript 与 Unity 的接口转换，负责把消息从 JS 侧送入 C#，同时把 C# 侧的操作指令传回 JS。
这样拆的好处是每一层都能单独测试。先用 MQTT.js 在浏览器里确认 Broker 连接正常，再单独测 Bridge 是否能把消息送给 C#，最后才连起来看整条链路。
2. 环境准备与工程配置：体面地把项目推到浏览器里跑
Unity 打 WebGL 包的环境配置本身不复杂，但有几个细节容易被忽略，导致后面反复返工。我在这部分把步骤和理由写清楚。
2.1 Unity 版本与 WebGL 模块
建议使用 Unity 2021 LTS 或更高版本（我自己项目里用的是 2022.3 LTS）。新版本对 WebGL 的内存管理、异常处理和加载体验都有明显优化。安装时记得勾选WebGL Build Support模块，这个不装后面打包选项里根本没有 WebGL 平台。
安装完成后，在 Build Profiles 面板里确认当前平台已经切换到 WebGL。这里有个小事提醒一下：Windows 和 Mac 上打的包在浏览器里表现一致，但编译环境差异会导致生成时间不同，别用这个判断工程是否有问题。
2.2 Player Settings 里的关键配置
进入 Player Settings 的 WebGL 标签页后，我按经验调整这几个选项：
| 设置项 | 推荐值 | 说明 |
|---|---|---|
| Compression Format | Brotli | 体积压缩比最好，搭配 nginx 或 IIS 静态托管即可 |
| Code Optimization | Runtime Speed | 对游戏类项目优先保证运行时性能 |
| Enable Exceptions | Explicitly Thrown Exceptions Only | 异常信息少，但有异常能定位到错误类型 |
| Data Caching | 开启 | 首次加载后缓存数据，二次访问大幅提速 |
其中 Compression Format 是最值得注意的。如果你用 Gzip，某些服务器配置不当会出现加载白屏问题；Brotli 需要在服务器端配置好Content-Encoding头，否则浏览器无法解压。如果你没有服务器配置权限，可以先用 Disabled 跑通流程，部署时再压缩。
2.3 浏览器端 MQTT 连接的特殊前置条件
这部分是容易踩坑的重灾区。浏览器里的 JavaScript 向远端 Broker 发起 WebSocket 连接时，会先触发CORS 跨域检查。如果你的 Broker 没有正确响应预检请求，MQTT.js 会直接报连接失败，而且错误信息往往只有一行 CORS error，非常迷惑。
我当时用的是 EMQX 作为 Broker，好在它的配置界面里直接集成了跨域支持，勾选启用就行。如果用其他 Broker，需要确认支持 WebSocket 监听，同时能配置允许来源（一般设成你的部署域名或全放开）。
连接地址需要明确说清楚：浏览器里不能连mqtt://或者tcp://开头的地址，必须用ws://或wss://，也就是 MQTT over WebSocket。如果你的站点本身是 HTTPS，Broker 地址也必须用wss，否则浏览器会直接拦截混合内容。
3. MQTT 客户端实现：从 C# 到 JS 再到 Broker 的完整桥接
现在到了核心环节——代码层面如何让 Unity 场景真正接收到 MQTT 消息。我直接把能用的方案写出来，附带我实测过的代码结构。
3.1 方案选型：原生 C# 客户端还是 MQTT.js
桌面端 Unity 可以用 MQTTnet 这个库在 C# 里直接连接 Broker，这个没问题。但 WebGL 环境桥接复杂，性能也有损耗，我的建议是：WebGL 项目直接用 MQTT.js，通过 Bridge 与 Unity 交互。
原因有三个：
- 浏览器原生支持 WebSocket，MQTT.js 在 JS 环境里非常成熟，连接管理和重连逻辑完善。
- C# 侧代码量少，只需要处理来自 JS 的回调，不需要自己维护协议栈。
- 调试方便。MQTT.js 层的消息可以直接在浏览器 Network 和 Console 里看到，比 C# 内联调试直观得多。
3.2 在 Unity 工程里创建接口脚本
先定义一个 C# 脚本，作为接收消息的入口。放在相机或者一个空的 GameObject 上都行。
using System.Runtime.InteropServices; using UnityEngine; public class MqttBridge : MonoBehaviour { // 对应 JavaScript 中暴露的函数 [DllImport("__Internal")] private static extern void JsConnectMqtt(string serverUrl, string clientId); [DllImport("__Internal")] private static extern void JsSubscribeTopic(string topic); [DllImport("__Internal")] private static extern void JsDisconnectMqtt(); [DllImport("__Internal")] private static extern void JsPublishMessage(string topic, string payload); // 从 JS 调回到 C# 的回调方法 public void OnMqttMessage(string topic, string message) { Debug.Log($"MQTT message received on topic {topic}: {message}"); // 在这里把消息分发给场景中对应的设备 } }注意[DllImport("__Internal")]是 Unity WebGL 调用 JS 的固定写法，只有打包后生效。在编辑器里运行会报错，这是正常的，我用#if指令把编辑器和 WebGL 的调试逻辑区分开，避免误判。
3.3 在 HTML 模板中引入 MQTT.js 并实现 Bridge
在 Unity 打包设置里，你可以指定自定义 HTML 模板。找到WebGLTemplates目录下的index.html，在<head>中引用 MQTT.js。如果不想引入外部 CDN，可以先下载到本地再引用，这样离线部署也不受影响。
<script src="mqtt.min.js"></script> <script> var mqttClient = null; function JsConnectMqtt(serverUrl, clientId) { var options = { clientId: clientId, reconnectPeriod: 3000, connectTimeout: 10000, keepalive: 30, clean: true }; if (serverUrl.startsWith("ws://") && location.protocol === "https:") { console.warn("HTTPS 页面连接 ws 地址会被浏览器拦截，请用 wss"); } mqttClient = mqtt.connect(serverUrl, options); mqttClient.on("connect", function() { console.log("MQTT connected"); }); mqttClient.on("message", function(topic, payload) { var msg = new TextDecoder().decode(payload); // 调用 Unity 中的回调 unityInstance.SendMessage("MqttManager", "OnMqttMessage", topic + "|" + msg); }); mqttClient.on("error", function(err) { console.error("MQTT error: ", err); }); } </script>这里我用topic + "|" + msg的方式把两个参数合并成一个字符串传回 Unity，是因为 SendMessage 一次只能传一个参数。如果想做得更规范，可以在 C# 侧再拆分，或者用 JSON 格式做字段标记，看你的实际数据结构。
3.4 连接参数怎么定
MQTT 连接参数不是随手填的，每个参数背后都有实际影响：
- reconnectPeriod: 断线重连的间隔时间。设太短会高频重试给 Broker 造成压力，设太长用户会明显感觉到"卡住不动了"。我一般设 3000 到 5000 毫秒。
- connectTimeout: 连接超时时间。浏览器环境下网络抖动很常见，建议 10 到 15 秒。
- keepalive：心跳时间。这个决定 Broker 多久没收到消息后判定客户端掉线。设备数据频繁的项目可以设 30 秒，纯做控制面板的话 60 秒也能接受。
- clean: true表示每次连接都不保留旧会话。对于需要离线消息补发的场景，你要改成
false，同时 Broker 端配置对应的 session 过期时间。
3.5 在 Unity 场景里组合起来
我把 MqttBridge 脚本挂在名为 MqttManager 的空物体上，Start 里调用连接逻辑：
void Start() { #if UNITY_WEBGL && !UNITY_EDITOR JsConnectMqtt("wss://你的broker地址:8084/mqtt", System.Guid.NewGuid().ToString()); #endif } void Update() { // 可变需求下可以加一个连接状态显示 // 供 UI 或者控制逻辑查询 }连接成功后，要订阅哪些主题可以在 JS 里直接mqttClient.subscribe(topic)完成，也可以封装成 C# 方法调用。我习惯在 C# 侧统一管理主题列表，启动时循环调用JsSubscribeTopic，这样前端页面切换或者业务变更时不用改 HTML。
4. 打包实战与常见疑难杂症排查
写到这，桥接方案已经通了。但实际打包和部署还有一堆意想不到的坑。我把围绕 WebGL 打包的实战记录和排查思路在这里完整列出来，因为这些问题几乎每个人都会碰到。
4.1 打包流程与部署注意
在 Build Profiles 里点 Build，Unity 会生成一个包含index.html、Build文件夹和TemplateData文件夹的静态目录。这个目录直接扔到任意 Web 服务器即可。
我用 nginx 部署时，配置里需要注意这几行：
location /webgl-demo { alias /var/www/webgl-demo; index index.html; add_header Content-Encoding br; # 使用 Brotli 时需要 add_header Cache-Control no-cache; # 避免浏览器缓存旧包 gzip off; }如果你用 IIS，需要在 web.config 里显式添加 Brotli 或 Gzip 的 MIME 映射。否则常见的表现是：第一次访问白屏，F12 看到一堆.wasm或.data文件加载失败。
4.2 浏览器白屏或"initialization failed"
这是搜索热度很高的问题："The browser supports WebGL, but initialization failed"。出现这个提示时，浏览器本身是支持 WebGL 的，但 Unity 运行时上下文创建失败了。我从实际项目中总结出三个排查方向：
- 显卡驱动与浏览器加速：先在浏览器地址栏输入
chrome://gpu检查 WebGL 是否启用。某些电脑关闭了硬件加速后，Unity 初始化就失败。可以强制开启浏览器的"使用硬件加速"选项。 - 代理或安全软件拦截：如果部署在局域网或特殊网络环境，WebGL 初始化时下载
.wasm会被中间层拦掉导致上下文创建失败。用公司内网部署时，需要排查防火墙是否拦截了.br或.wasm文件请求。 - 内存分配失败：Unity WebGL 的初始内存如果被设置得过低，在某些设备上会初始化失败。在 Player Settings 里把 Initial Memory Size 调到 256MB 或更高，一般能缓解。
4.3 帧率与浏览器性能的拉扯
Unity 在 WebGL 上默认按显示器的刷新率渲染。如果你在场景里加载了高精度模型或大量动态灯光，帧率会很不稳定。我项目里那个监控大屏就是，设备模型加载后帧率掉到十几帧，操作起来很生涩。
后来我用了一段比较简单的控制逻辑：
// 在 Camera 挂载的脚本里 void Update() { // 如果场景不需要每帧变化，可以降低更新频率 if (Time.frameCount % 3 == 0) { // 业务相关的逻辑判断放这里 UpdateDeviceStatus(); } }更大的优化点是资源层面：不用的动态合批可以关掉，灯光的实时阴影在 WebGL 里非常消耗性能，能烘就烘，能少就少。纹理压缩格式在 WebGL 下有不同的兼容性，我最后统一用了 ASTC，移动端和桌面浏览器兼容度都很高。
4.4 Unity 与浏览器的生命周期同步
浏览器里用户随时可能切走标签页，或者浏览器自己会后台节流。MQTT 连接在后台运行一段时间后，心跳会被浏览器暂停，切回来时往往会发现连接已经断了。MQTT.js 默认的 reconnectPeriod 会自动重连，但 Unity 侧可能因为收到消息的时间差出现状态闪断。
我的处理办法是：在页面重新可见后，手动通过 Bridge 检查连接状态。可以在 index.html 里加入 visibilitychange 事件监听，如果状态异常就重新调用 JsConnectMqtt。这在做长时间无人值守的大屏项目时很有用。
5. 踩坑实录与个人经验总结
最后这部分，我挑几个让印象最深的问题讲讲，希望能帮你少走弯路。
5.1 版本统一是省事的基础
我中途升级过一次 Unity 版本，从 2021.3 到 2022.3，看起来是小版本更新，结果打包后的 API 行为和 WebGL 的 brotli 压缩策略都有变化，导致模拟器环境没问题，真机浏览器加载直接失败。后来在同一项目里固定了 Editor 版本和 WebGL 模块版本，这类低级问题再没出现过。
5.2 C# 与 JS 之间的类型边界要清楚
Unity 的 SendMessage 传给 JS 的参数最终会被转成字符串。JS 的回调传回字符串时，如果有中文或者特殊符号，注意编码格式。我遇到过设备上报的数据是 GBK 编码的中文，在浏览器端显示乱码，后来统一在设备端改成 UTF-8 就好了。跨语言的桥接，字符编码是最容易忽略的一环。
5.3 调试技巧：善用浏览器控制台
WebGL 项目在浏览器里跑的时候，Debug.Log输出的内容会原样打在浏览器控制台上。所以调试 C# 业务逻辑时，不用反复打包，直接在控制台看日志就行。我通常在关键节点加上特征明显的前缀，比如[MQTT]或[SCENE]，这样日志一刷就能很快定位问题出在通信层还是表现层。
5.4 常用问题速查
| 现象 | 可能原因 | 解决方式 |
|---|---|---|
| 浏览器控制台报 CORS error | Broker 未开启跨域支持 | 在 Broker 配置跨域允许来源 |
| 连接显示成功但收不到消息 | 订阅主题与发布主题不匹配，或 QoS 设置不一致 | 检查主题字符串，确认服务端用 QoS 0/1/2 的哪一档 |
| 过一会儿自动断线 | 心跳周期过长或浏览器后台节流 | 缩短 keepalive，开启可见性恢复重连逻辑 |
| 首次加载黑屏很久 | 压缩文件未被服务器正确解压 | 检查 Content-Encoding 配置 |
| 场景交互卡顿 | 渲染负载过高或帧率未限制 | 烘焙光照、降低阴影质量、限制场景更新频率 |
| 消息内容是乱码 | 编码格式不一致 | 全链路统一使用 UTF-8 |
5.5 如果后面还要扩展
这套 WebGL + MQTT 的骨架搭好之后，扩展方向很多。比如把场景中的设备状态与后端数据库打通，MQTT 只做实时推送；或者把 Unity 里的截图通过 MQTT 转发到移动端；再或者在同一页面嵌入多个 Unity 实例，分别订阅不同主题区域。
我个人实际操作中最大的体会是：最先跑通的方案不一定要最优雅，但通信链路一定要尽早打通，因为后面的业务全部依赖数据进来这一下。MQTT 这套链路验证通过之后，Unity 场景里的开发就可以脱离后端独立进行，联调时只需要 Mock 主题数据即可。
最后再分享一个小技巧：如果你遇到连接问题，先不要盯代码，打开浏览器的开发者工具，切到 Network 标签，过滤 WS，看 WebSocket 连接是不是正常建立、有没有收到服务端的 CONNACK 包。这一眼看明白，比盲改代码高效得多。
本文还有配套的精品资源，点击获取
