简介：这是一套基于Unity与WebRTC实现远程画面共享与远程控制的完整项目源码，面向Unity开发者、音视频通信初学者及远程协作类应用实践者，解决跨平台实时媒体流传输与交互控制的技术落地问题。资源包共2000个文件，主体为547份Markdown文档（含技术说明与配置指南）、143个文本配置文件、103个JSON配置项、86个Unity元数据及29个C#脚本，辅以预制体、Shader、音频与工程配置文件，全面覆盖客户端逻辑、信令交互、媒体设备管理与UI控制模块；压缩包大小为211.04MB。已有502人学习下载，开箱即用，无需从零搭建底层协议栈——项目已预置局域网部署所需的Web服务器启动脚本、浏览器端访问入口及完整的输入设备适配方案，可直接运行验证远程投屏、鼠标键盘指令转发等核心功能，是理解Unity WebRTC集成路径与远程控制架构设计的高实用性参考范例。 做数字孪生项目的时候，客户提了个让我印象很深的需求：控制室里那台跑 Unity 的工控机上，三维场景渲染得再炫都没用，他们想坐在会议室里，用一台普通笔记本打开浏览器，就能看到现场设备的实时运行状态，甚至直接远程操纵场景里的设备。刚开始我第一反应是上商业远程桌面，但授权费、部署方式、还有能不能嵌进我们自己 Web 系统里，都是问题。后来我转向 WebRTC 这条路，把 Unity 画面以超低延迟推给浏览器，再把浏览器的鼠标键盘事件传回 Unity，做成了一套远程画面共享+远程控制的完整方案。这篇博文就把这套 WebRTC-Unity 项目源码的整体设计、核心模块、打开即用的操作步骤和我在实际调试中踩过的坑全部理一遍，给正在做同样事情的人一份可以直接抄作业的参考。
项目适合三类人：一是数字孪生、虚拟仿真、远程运维方向的技术负责人，需要把 Unity 内容展示到 Web 端；二是做远程评审、远程培训工具，希望浏览器的操作能直接驱动 Unity 场景；三是研究 WebRTC 在 Unity 端落地、想找一个能直接跑起来的开源参考的开发者。项目源码本身是整套的，Unity 工程、信令服务器、Web 页面三件套都齐了，改改配置就能用。
1. 项目整体设计与核心思路
1.1 先搞清楚它到底解决什么问题
常规的 Unity 远程展示方案，无非就那几条路。第一条是直接把 Unity 画面用 RTSP/RTMP 推到流媒体服务器，再在网页上播放，这条路的问题是延迟基本在 3 到 10 秒，做展示可以，做远程控制完全不行，你鼠标点下去，画面三秒后才反应，谁用谁崩溃。第二条是用投屏软件把整个桌面投出去，像向日葵、ToDesk 这类工具，但这对商业软件依赖太重，而且它们偏重“整个桌面”的远程操作，想嵌入到自己的业务系统里，灵活度不够，授权也不便宜。第三条是做 Unity WebGL，让用户直接在浏览器里加载整个场景，这条路对复杂场景完全不现实，一个稍微像样的数字孪生项目，WebGL 包动辄几百兆，加载慢不说，工控机上的硬件资源也没法直接复用。
这套 WebRTC-Unity 项目的思路是：Unity 跑在性能足够的本地设备上，负责重型渲染和业务逻辑，画面通过 WebRTC 实时推流，浏览器端只做“显示+输入采集”。视频流的延迟可以压到 1 秒以内，实测局域网环境下操作反馈在 100 到 200 毫秒，人基本感觉不到明显滞后。浏览器端不需要安装任何插件，Chrome、Edge 打开网页就连上了，真正做到了“打开即用”。
1.2 为什么选 WebRTC 而不是其他实时传输方案
WebRTC 天生就是为实时音视频通信设计的，浏览器原生支持，不用装任何插件，这是它最大的优势。它内部有完整的音视频引擎，包括采集、编码、网络拥塞控制、抖动缓冲、丢包重传这些机制，这些能力如果自己从零实现，没有几年的积累根本做不出来。而且 WebRTC 支持 P2P 直连，局域网环境下，Unity 和浏览器之间可以直接通信，视频流不经过服务器中转，延迟和带宽成本都降下来了。
更重要的是，WebRTC 的 DataChannel 提供了可靠的、低延迟的双向数据通道，这个通道可以用来反向传鼠标键盘事件，把远程控制的链路也打通了。音视频走媒体通道，控制指令走数据通道，两个通道并行，互不干扰，这在架构上非常干净。对比一下，如果只用 WebSocket 传控制指令，视频还得另走一套推流链路，两套系统的状态同步和延迟协调就是个大麻烦。
WebRTC 也并不是没有缺点。它必须有一个信令服务器来做连接协商，因为 Unity 和浏览器之间要先交换 SDP、ICE Candidate 这些连接信息，才能建立起 P2P 通道。另外，如果用户分布在不同的内网，NAT 穿透失败，就需要 TURN 服务器做中继，这会增加延迟和带宽成本。这些在实际部署时都要考虑进去，但总体说，在“Unity 画面共享+远程控制”这个场景下，WebRTC 是当前最合理的方案。
1.3 项目整体架构和一个完整的连接流程
整个项目分三个部分：Unity 客户端、信令服务器、浏览器页面。Unity 客户端负责采集渲染画面送给编码器，同时接收控制指令并注入到引擎；信令服务器是 Node.js 写的，只负责转发连接协商消息，不碰媒体数据；浏览器页面负责接收视频流显示，采集用户的鼠标键盘操作，通过 DataChannel 发回给 Unity。
一个完整的连接流程大概是这样的：
- 浏览器打开页面，向信令服务器发送“我请求加入房间 demo”。
- 信令服务器把这个请求转发给正在监听房间的 Unity 客户端。
- Unity 客户端创建 PeerConnection，生成 SDP Offer，把自己的媒体信息（分辨率、编码格式等）通过信令服务器传给浏览器。
- 浏览器收到 Offer 后创建 PeerConnection，设置远端 SDP，生成 Answer 回传，同时双方开始交换 ICE Candidate，尝试 NAT 穿透。
- 连接建立成功后，Unity 的视频流自动在浏览器里播放，DataChannel 也同时打开。
- 浏览器监听鼠标移动、点击、键盘事件，把归一化坐标和按键信息通过 DataChannel 发到 Unity。
- Unity 解析控制消息，把它转成引擎内的输入事件，驱动场景里的相机、设备或其他交互逻辑。
这里面最容易出错的就是信令交互的顺序和 ICE 状态的判断，后面我会在实操部分详细说。
2. 核心模块实现与关键技术细节
2.1 Unity 端画面采集：RenderTexture 为主，别一根筋用屏幕截图
画面上行是整个远程控制的基础，画面都出不来，后面全白搭。Unity 端画面采集有几种做法，我实践中建议用 RenderTexture 方案而不是直接截屏。
具体做法是在场景里加一个专门的采集相机，或者复用主相机，把渲染目标指向一张 RenderTexture，然后在每帧或者按固定频率，通过Texture2D.ReadPixels把 RenderTexture 的内容读回到 CPU 内存，转成 WebRTC 编码器需要的 I420 格式，送给 native 层的编码器。这样做的优势是只采集 Unity 的 Game 视图内容，不会把编辑器窗口、桌面任务栏这些无关内容传出去，对画面隐私和带宽控制都更友好，而且可以随时调整输出分辨率，不用管桌面缩放。
要注意ReadPixels是主线程操作，很吃性能。我实测下来，1080p 分辨率下每帧这么做一次，大概要占主线程 5 到 8 毫秒，30fps 时压力还能接受，但到了 4K 分辨率就非常危险，一帧可能吃掉 20 毫秒以上，直接把渲染帧率拉垮。所以项目里默认是 1080p 30fps，同时做了一个动态帧率控制：根据 DataChannel 反馈回来的网络统计信息，网络拥堵时自动把推流帧率降到 15fps，把码率降下来，保证操作响应优先。
如果要在远程画面里显示鼠标光标，我不建议直接采集 Unity 里的系统光标，那样会有额外性能损耗，而且光标在 Unity 里本来就有延迟。更好的做法是用 DataChannel 把光标坐标同步到浏览器端，让浏览器在视频画面上叠加一个本地光标元素，这样光标移动非常跟手，观感反而更好。
2.2 WebRTC 连接管理：PeerConnection、SDP、ICE 的状态机要理清
WebRTC 连接管理是整个项目里最容易把自己绕晕的部分。简单说，Unity 端和浏览器端各有一个 PeerConnection 对象，它们需要交换三次关键信息：SDP Offer、SDP Answer、ICE Candidate。SDP 里带着媒体能力，ICE Candidate 里带着网络路径信息。
我这边的实践是：Unity 端用 C++ 封装了一套 WebRTC Native 接口，C# 层通过 P/Invoke 调用。核心回调就几个：OnIceCandidate、OnConnectionStateChanged、OnDataChannelMessage。Unity 端创建好 PeerConnection 后，设置一个本地的视频源，然后创建 Offer，通过信令服务器发给浏览器；浏览器拿到 Offer 后创建 Answer 发回来，Unity 再设置远端 SDP，连接就进入 ICE 探测阶段。
ICE 状态是整个调试过程中要重点盯的东西。当conectionState变成connected，说明 P2P 通道已经打通，视频流才会开始传输。如果一直停在checking，说明 NAT 穿透可能失败，需要检查 STUN 配置，或者是不是要走 TURN。还有一点很重要：多个 ICE Candidate 的到达顺序是不确定的，所以代码里一定要先判断SetRemoteDescription是否已经完成，再处理AddIceCandidate，否则 Chrome 会直接报错。
编码器配置上，项目默认走 H264。需要显式配置profile-level-id为42e01f，也就是约束基线模式，这是浏览器兼容性最好的档位。很多踩坑帖里说的“Codec not supported”问题，多半就是编码器配置了 H265 或 Profile 太高，Chrome 不认。
2.3 控制指令回传：DataChannel 上的协议设计
远程控制不是只传视频就完了，关键是把用户操作回传给 Unity。DataChannel 协议我设计成了 JSON 格式，简单直观，出问题也好排查。几个核心消息类型：
- 鼠标移动：
{"type":"mousemove","x":0.35,"y":0.62}，这里存的不是绝对像素，而是归一化坐标，浏览器窗口大小变化不影响准确性，Unity 端再乘以屏幕宽高还原成实际坐标。 - 鼠标点击：
{"type":"mousedown","button":0,"x":0.35,"y":0.62}，button 对应左键、中键、右键。 - 键盘事件：
{"type":"keydown","code":"KeyW","keyCode":87}，code用的是浏览器标准物理键名，比数字 keyCode 稳定，Unity 端需要做一张映射表。 - 滚轮事件：
{"type":"wheel","deltaY":120,"x":0.35,"y":0.62}。
Unity 端收到这些消息后，解析 JSON，再统一注入到引擎的输入系统里。这里有个 Unity 的坑：你不能直接去改Input类的内部状态，常见的做法是自己维护一份输入状态字典，然后在Update里根据字典状态去驱动场景里的相机移动或者对象交互；如果项目用的是 UGUI 的 EventSystem，可以用PointerEventData模拟点击穿透到 UI 上。
坐标换算是我踩过最深的坑之一。浏览器端 canvas 的尺寸和 Unity Game 视图的尺寸不一致时，如果直接用像素坐标传回去，点击位置一定漂移。所以必须统一用归一化坐标，发送前用canvas.getBoundingClientRect()把鼠标位置转成 0 到 1 之间的比例值，Unity 端再乘上Screen.width和Screen.height。
2.4 信令服务器：代码量不大，但别写成单点炸弹
信令服务器看起来简单，就是转发 SDP 和 ICE，但其实挺容易出问题的。我使用的是 Node.js 加ws库，总共不到 150 行。它维护一个房间表，每个房间最多允许一个 Unity sender 和多个 viewer。当浏览器发来join消息，服务器先看这个房间有没有 sender 在线，有就通知 sender 开始协商，然后所有信令消息都按房间号转发到对应客户端。
有一个教训：信令服务器如果只跑在localhost，Unity 客户端和浏览器是连不上的，必须绑定0.0.0.0，并且监听地址要填局域网 IP 而不是回环地址。而且如果部署到公网，信令服务器必须启用 TLS，也就是 WSS，否则浏览器在 HTTPS 页面下会阻止访问非加密的 WebSocket。还有个容易被忽视的点，就是 CORS 跨域配置，浏览器页面如果和信令服务器不在一台机器上，跨域请求会被浏览器拦截，需要配置Access-Control-Allow-Origin。
信令服务器不转发媒体数据，所以带宽压力不大，但它承担了所有客户端的连接状态管理，一旦挂了，所有正在看画面的浏览器都会断开。生产环境里，建议给信令服务器加一个简单的房间 token 认证，防止任意设备加入你的房间。项目源码里已经预留了这个接口，默认是关闭的，需要改一个环境变量就能开启。
3. 打开即用：从零到跑通的完整实操
3.1 环境准备：先装齐这几样，免得后面来回折腾
整个项目对环境要求不高，但版本要对上，我前后测试下来最稳的组合是：Unity 2021.3 LTS 或更新版本（推荐 LTS，稳定不容易出幺蛾子）、Node.js 16 及以上、Chrome 或 Edge 最新版、Windows 10/11 或 Ubuntu 20.04 都行。
Unity 工程里的 Native 插件是按平台编译的，Windows 对应Plugins/x86_64/webrtc_plugin.dll，Linux 对应libwebrtc_plugin.so，源码的预编译版本已经放在对应目录里了。如果你是自己根据源码编译插件，一定注意是要给 Unity 用，而不是给 Node 用，这两者的 ABI 不一样，混了必崩。目录结构上，项目根目录下分server/、UnityProject/、web/三块，web 目录是静态页面，也可以直接塞进 server 里自动托管。
3.2 启动信令服务器：一条命令的事，但端口和 IP 要看清
信令服务器启动非常简单，打开终端，进入server目录，执行：
cd server npm install npm run start默认监听 8000 端口，可以通过PORT环境变量改。启动成功后，浏览器访问http://localhost:8000会看到一个简单的状态页，显示“Signaling server is running”之类的提示。
这里必须强调一个细节：Unity 客户端和浏览器端要访问的信令服务器地址，不要用127.0.0.1，要用这台机器的局域网 IP，比如192.168.1.100。我的经验是直接在源码里搜索SIGNALING_SERVER_URL这个配置项，改成实际 IP，然后重新生成 Unity 配置或者浏览器页面 URL，避免开发时来回填错。
3.3 打开 Unity 工程和 Web 页面：跑通第一个画面
用 Unity Hub 打开UnityProject目录，第一次打开会自动解决依赖包，等待编译完成。然后打开Scenes/Boot.unity场景，点编辑器上的 Play 按钮。Unity 控制台如果出现“WebRTC sender started, waiting for viewer...”的日志，说明 Unity 端已经就绪，正在等待浏览器接入。
浏览器端打开http://<信令服务器IP>:8000?room=demo，页面加载后会自动发起连接。正常情况下，几秒内就能看到 Unity 的实时画面，然后你用鼠标在场景里拖拽相机，或者按键盘 W、A、S、D 控制角色移动，画面会实时跟着动。如果一切正常，说明这条“Unity 推流 + 浏览器控制”的链路已经完整跑通了。
3.4 局域网和公网部署的配置差异
局域网环境最简单，所有设备在一个网段，STUN 穿透基本都能成功，延迟也低。公网部署就复杂一些，你需要一台有公网 IP 的云服务器跑信令和 TURN 服务，Unity 客户端跑在工控机上，主动往外连信令服务器，浏览器用户也连同一个信令服务器，信令层打通后，媒体流能不能 P2P 直连要看双方 NAT 类型，不通就走 TURN 中继。
公网部署的传输延迟一般会多 50 到 100 毫秒，如果用户和设备分布在不同的城市，尽量把 TURN 部署在中间位置或者就近的云节点上。另外，浏览器端在 HTTPS 页面下访问非加密 WebSocket 会被阻止，所以公网环境信令服务器必须启用 TLS，可以用 Nginx 反向代理来终结 TLS，再转发到本地的 Node.js 服务。
3.5 常用配置项说明：一个表格说清楚
项目里的核心配置项基本集中在server/config.js和 Unity 场景里的WebRTCConfig组件上，我把常用参数整理了一下：
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 信令服务器端口 | 8000 | 局域网内自定义端口时注意防火墙放行 |
| STUN 服务器 | stun:stun.l.google.com:19302 | 如果内网使用，可以填内网 STUN 或直接不填 |
| TURN 服务器 | 无 | 公网部署建议配置，否则部分网络连不通 |
| 视频分辨率 | 1920x1080 | 带宽不足可以降到 1280x720 |
| 推流帧率 | 30fps | 网络差会自动降到 15fps |
| 视频码率 | 4 Mbps | 项目会自动根据丢包率调整 |
| 房间名 | demo | 浏览器 URL 里的 room 参数 |
这些参数可以根据实际网络条件和业务场景调整，不要照搬，尤其是码率和分辨率，内网千兆环境可以开 2K 甚至 4K，公网 500Kbps 上行的场景，老老实实用 720p 加 1.5Mbps 码率。
4. 常见故障与排查技巧实录
4.1 黑屏、Codec not supported 的真相
我在调试过程中遇到最多的一个问题，就是浏览器里视频区域黑屏，控制台还打出一行日志：Codec not supported ... ignoring this track。这行日志翻译过来就是：远端发来的媒体轨道里带的编码格式，浏览器不支持，所以直接忽略了。
这个问题八成出在编码器配置上。项目在推 H265 或者 H264 Profile 太高时，Chrome 会直接忽略轨道。解决办法是在 Unity 端编码器配置里强制指定 H264，并且把profile-level-id设为42e01f。如果你要用 VP8 或 VP9，Chrome 支持，但 iPhone 上的 Safari 对 VP8 支持并不好，所以跨平台场景我建议同时提供 H264 和 VP8 两路编码，让浏览器根据能力自己选。
如果是 iOS Safari 黑屏，还要检查 WebRTC 是否在该 Safari 版本里被限制，以及页面是不是 HTTPS。Safari 对 getUserMedia 这类接口要求安全上下文，不是 HTTPS 的话媒体能力都会受限。
4.2 延迟高、画面卡顿的定位思路
延迟高先别急着调代码，先分清楚是“采集端卡”还是“网络卡”。Unity 编辑器里按 F12 调出 Profiler，看主线程 CPU 占用是否长期在 90% 以上，如果是，优先看ReadPixels这一步的耗时。一个有效优化是把读回操作从每帧执行改成定时执行，并且可以错开渲染帧，比如渲染 60fps、推流 30fps，减少主线程压力。
网络侧的延迟可以通过浏览器地址栏输入chrome://webrtc-internals查看，这是一个非常好用的 WebRTC 调试面板，里面能看到jitter、packetLoss、bitrate、RTT这些指标。如果packetLoss长期高于 5%，说明网络不稳，系统会自动调低码率；如果RTT很高，看是不是走了 TURN 中继，P2P 直连的局域网 RTT 应该在几毫秒级别。
还有一个小技巧：Unity 端的推流不要一直跑满帧率和码率，我习惯做一个自适应逻辑，根据浏览器端反馈的接收码率和丢包率，动态调整发送端的编码参数，这样在网络抖动时能快速响应，不会一直卡到断线。
4.3 画面出来了，但远程控制没反应
如果浏览器里能看到 Unity 画面，但鼠标点击没反应，优先检查 DataChannel 是否建立成功。WebRTC 的媒体通道和 DataChannel 是独立的，媒体通了不代表数据通道也通了，在浏览器端控制台执行：
pc.getDataChannels().forEach(dc => { console.log(dc.label, dc.readyState); });如果readyState不是open，说明 DataChannel 协商有问题。常见原因是双方创建 DataChannel 的时机不一致，最好在 Offer 创建之前就先把 DataChannel 建好，这样 SDP 里会带上 DataChannel 的协商信息，避免后续重新协商。
如果 DataChannel 是 open 状态但控制还是没反应，就要看消息协议是不是对得上。Unity 端解析 JSON 失败时，控制台一般会打日志，先看有没有JSON parse error之类的输出。另一个常见问题是坐标偏移，鼠标点击的位置明显不在按钮上，大概率是归一化坐标换算出了问题。
4.4 常用排查速查表
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 页面一直 connecting | 信令服务器连不上、URL 填错、CORS 跨域 | 检查信令服务器状态页，确认 WebSocket 地址和端口 |
| 出现 Codec not supported | 编码器用了 H265 或不兼容 Profile | 强制 H264，profile-level-id 设为 42e01f |
| 视频有画面但点击没反应 | DataChannel 未建立或消息格式不对 | 检查 DataChannel readyState，确认 JSON 字段名一致 |
| 点击位置偏移 | 使用像素坐标而非归一化坐标 | 改用 0-1 归一化坐标，Unity 端乘以实际分辨率 |
| 键盘输入无响应 | KeyCode 映射表不完整 | 用 event.code 物理键名映射，不要用数字 keyCode |
| 画质差、马赛克 | 码率设置过低或网络拥塞 | 提高码率，或根据丢包率调整自适应策略 |
| 连接数多时全部卡顿 | 同一 sender 推流给多路人，带宽不足 | 对每个 viewer 单独设置码率，或部署多路 sender |
5. 基于这套架构还能做的扩展
项目跑通之后，我一直觉得这套 WebRTC-Unity 架构的想象力远不止远程看画面。有几个扩展方向我试过或者正在验证的，值得说一下。
第一个是文件传输。WebRTC 的 DataChannel 本来就是可靠传输通道，完全可以在 Unity 和浏览器之间互相传文件。热词里提到的“node webrtc 文件传输”其实就是指这个方向，我自己在信令服务器上加了文件传输的扩展，浏览器端拖一个文件到页面上，通过 DataChannel 分包发到 Unity 端，Unity 端收到后落盘到指定目录。这个功能非常实用，比如远程给终端设备下发配置文件，或者从工控机拉取运行日志，不用再搭一套 FTP 服务，一条数据通道全搞定。
第二个是多用户协同。目前项目是一个 sender 对应多个 viewer，但 viewer 之间是没有互动的。如果在信令服务器上增加房间内消息广播，再在浏览器端增加标注图层，就能实现多人同时看画面、每个人都可以在画面上画圈标注，评审场景下非常高效。Unity 端甚至可以接收这些标注指令，把标记点绘制到三维场景里，实现远程指导。
第三个是 VR/AR 设备的远程渲染。热词里有“pico4开发unity”，这个方向跟 WebRTC 远程渲染思路很像：头显设备渲染能力有限，复杂场景在云端服务器渲染，视频流通过 WebRTC 推到头显里，用户的头动数据通过 DataChannel 传回云端重新计算视角。这个方案在 5G 加边缘计算的场景下已经有人在做了，延迟控制在 50 毫秒以内，体验会非常接近本地渲染。
第四个是结合 Node 生态做业务闭环。信令服务器本身就是 Node.js，完全可以在里面集成数据库、用户鉴权、操作日志、权限管理。例如，给不同的用户分配不同的控制权限，有的用户只能看画面，有的用户可以操作，所有远程操作都记录到数据库里，方便审计。这些都是在现有架构上做加法，不需要改动 WebRTC 传输链路。
最后再分享一个我反复强调的体会：这套 WebRTC-Unity 远程控制方案，真正的难点不是 WebRTC 本身，而是工程化。媒体通道、数据通道、信令状态机、坐标映射、编码兼容性，每一个环节都可能出问题，而且问题之间还会互相干扰。但只要把架构理清了，先跑通最小链路，再逐步加功能，整个项目会非常稳定。我做这个项目最深的感受是，能把“打开即用”做出来，背后一定藏着一堆不起眼的细节处理；而把这些细节讲清楚，比直接甩一个源码包给读者，有价值得多。
本文还有配套的精品资源，点击获取
