简介这是一套基于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 开始协商然后所有信令消息都按房间号转发到对应客户端。有一个教训信令服务器如果只跑在localhostUnity 客户端和浏览器是连不上的必须绑定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.dllLinux 对应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?roomdemo页面加载后会自动发起连接。正常情况下几秒内就能看到 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 或 VP9Chrome 支持但 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强制 H264profile-level-id 设为 42e01f视频有画面但点击没反应DataChannel 未建立或消息格式不对检查 DataChannel readyState确认 JSON 字段名一致点击位置偏移使用像素坐标而非归一化坐标改用 0-1 归一化坐标Unity 端乘以实际分辨率键盘输入无响应KeyCode 映射表不完整用 event.code 物理键名映射不要用数字 keyCode画质差、马赛克码率设置过低或网络拥塞提高码率或根据丢包率调整自适应策略连接数多时全部卡顿同一 sender 推流给多路人带宽不足对每个 viewer 单独设置码率或部署多路 sender5. 基于这套架构还能做的扩展项目跑通之后我一直觉得这套 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 本身而是工程化。媒体通道、数据通道、信令状态机、坐标映射、编码兼容性每一个环节都可能出问题而且问题之间还会互相干扰。但只要把架构理清了先跑通最小链路再逐步加功能整个项目会非常稳定。我做这个项目最深的感受是能把“打开即用”做出来背后一定藏着一堆不起眼的细节处理而把这些细节讲清楚比直接甩一个源码包给读者有价值得多。本文还有配套的精品资源点击获取