UE5像素流送Pixel Streaming这套东西我前前后后在Windows服务器上折腾了快半个月踩过的坑比文档里写清楚的问题多一倍。网上的教程大多是基于Linux或者容器化的真到了Windows单实例部署各种小毛病全冒出来了Node.js 18版本报那个node:util导出错误、coturn装完后目录是空的、打包好的工程在服务器上死活连不上8666信令端口、还有ShaderCompileWorker那个让人头皮发麻的fatal error: [file:D:\build\UE5\...]。这篇文章就是把我这半个月的实战记录整理成了一份可以直接照着做的指南。单实例部署是像素流送最基础的形态适合做内部演示、小范围测试、产品Demo不需要上K8s不需要搞集群一台Windows服务器加一个显卡就能跑。我会把一个能稳定运行的完整环境从0到1拆开讲把每一步为什么要这么做的原因也讲清楚尤其是那些文档里不会写的坑希望能帮你在部署UE5像素流送的时候少走半个月弯路。1. 像素流送单实例踩坑全景先搞懂你面对的是什么1.1 像素流送的工作链路与单实例定位像素流送的核心思想说白了就是UE引擎负责渲染画面画面被编码成视频流通过浏览器播放。用户电脑不需要安装UE也不需要高配显卡打开网页就能操作三维场景。这套系统在Windows服务器上跑起来的链路是UE打包程序输出画面信令服务器Signalling Server负责协调浏览器和UE进程建立连接WebRTC负责音视频数据实时传输如果需要多用户并发或者远程连接还会用到coturn做TURN中继。单实例就是最简单的架构一台服务器跑一个UE打包程序配一个信令服务器浏览器通过信令服务器找到UE进程然后建立WebRTC连接。没有负载均衡没有多实例管理没有资源池。这种架构对第一次接触像素流送的人最友好也是排查问题最方便的环境。因为链路短出了问题你能快速定位到底是哪一段断了。我第一周踩坑最大的感受是像素流送的问题往往不在UE本身而在UE之外的那一圈基础设施。画面渲染不出来、页面白屏、连接超时十有八九是Node.js环境的问题、certificate证书的问题、防火墙端口的问题而不是你工程蓝图写错了。1.2 为什么选择Windows服务器做单实例很多UE5像素流送的官方示例都是基于Linux和Docker跑的因为容器化部署在云端弹性好、隔离性强。但实际项目里尤其在国内团队中Windows服务器反而是常见选择UE项目很多依赖Windows平台的中间件美术和TA手上的素材、插件、第三方库往往只支持Windows服务器运维人员长期管理Windows Server对IIS、远程桌面、组策略熟悉上手UE反而比上手Linux容器快。单实例场景下Windows服务器的劣势并不明显。媒体服务器也好信令服务器也好单用户并发的情况下资源占用都很有限。而且Windows的图形栈对UE更友好DirectX 11/12跑起来直接、稳定不需要折腾显卡直通、CUDA虚拟化这些Linux下达成本很高的东西。如果你的服务器只有一块NVIDIA显卡并且只需要给几个同事做演示看效果Windows上跑像素流送比在Linux上解决显卡驱动和Vulkan兼容问题省心得多。不过Windows也有自己的麻烦路径大小写、权限模型、防火墙策略、Node.js安装在系统目录下的权限坑、服务注册的方式。这些正是后面章节要逐个处理的问题。2. 环境准备阶段的两个硬骨头Node.js 和 coturn2.1 Node.js 版本陷阱与 18 版的 node:util 报错UE5像素流送的Signalling Server是Node.js写的所以在Windows服务器上第一步就是装Node.js。这里第一个坑就来了版本别乱选更不要图新。我在第一次部署时直接装了当时最新的Node.js 20结果信令服务器启动时报错The requested module node:util does not provide an export named parse这个报错在UE5的signalling模块里很常见。原因并不复杂UE5.0到UE5.2时代的信令服务器源码依赖了Node.js某个内部模块的导出方式而Node高版本调整了模块导出策略导致代码里require(util)时拿到的对象里找不到对应的方法名。我后来把Node.js降到18 LTS版本后这个问题就消失了。确切地说UE5.2及更早版本建议使用Node.js 16或18UE5.3之后对18的支持更稳定。UE5.4之后官方对Node 18做了兼容测试但暂时不建议上20以上的版本除非你改过源码里的兼容性补丁。安装Node.js时有几个细节值得注意安装包从官网下载.msi版本不要用.zip解压版因为.msi会帮你配置系统PATH后续少很多麻烦。安装路径不要带空格和中文建议直接装到C:\nodejs后面注册服务时路径越简单越不容易出错。安装完打开CMD输入node -v验证版本。如果提示找不到命令说明PATH没生效重新登录一下服务器或手动把C:\nodejs加进系统环境变量。在国内服务器上安装完后建议立刻切换npm镜像源否则后面下载依赖包时你会等到怀疑人生npm config set registry https://registry.npmmirror.com切换完可以执行npm config get registry确认输出的是镜像地址再继续。2.2 coturn 空文件夹问题不是你以为的“没装上”第二个硬骨头是coturn。coturn是WebRTC的TURN/STUN服务器实现在像素流送里承担“打洞失败时转发音视频数据”的职责。很多教程说“内网部署不需要coturn”但如果你在Windows服务器上同时服务多台不同网络环境的客户端或者经过NAT后的客户端连不上你服务器的WebRTC端口你就会发现没有TURN服务器是真的连不上。coturn在Windows上的部署方式和Linux完全不同。Linux有apt/yum包可以直接装Windows你需要下载源码自行编译。这里就是那个“空文件夹”问题的来源很多教程让你去GitHub上下载coturn的Windows版本压缩包结果你解压后发现bin目录是空的或者只有turnadmin.exe.example没有实际的turnserver.exe。原因很直接coturn官方仓库的Windows预编译包在很长一段时间里只包含源码和示例文件真正的可执行文件需要你自己用Visual Studio编译生成。如果下载的是“source code”标签下的zip解压后当然没有exe。正确做法有两个方案一下载Release页面里明确标注为“turnserver-xxx-windows.zip”的预编译文件。如果你下载的压缩包解压后能看到turnserver.exe说明你找对了。方案二自己编译。在Windows上编译coturn需要Perl、Visual Studio Build Tools还要处理OpenSSL依赖成本比较高。如果你不是特别需要定制功能我更推荐方案一或者干脆用Docker在Windows的WSL2里跑一个coturn容器这样不用污染宿主机环境。不管你用哪种方式coturn配置文件的要点是注意监听端口和外部IP。老版本coturn配置文件里的external-ip如果填错客户端会收到一个无法访问的候选地址表现为浏览器一直转圈WebRTC连接状态始终是connecting控制台打出来的SDP里的candidate IP不对。在内网测试时external-ip可以直接填服务器内网IP公网部署时一定要填服务器的公网IP否则TURN转发地址必然不通。3. 证书与信令服务器配置浏览器端的安全一关3.1 证书的获取与格式转换为什么HTTPS会卡住整个流程像素流送在浏览器端是通过WebRTC获取媒体流的而WebRTC的getUserMedia和RTCPeerConnection在主流浏览器中都强制要求页面是安全上下文。安全上下文的概念很简单要么是https://域名要么是localhost。如果你的页面是通过http://服务器IP访问的你会发现页面加载出来了但视频区域一片黑控制台报getUserMedia() is not allowed on insecure origin或者Failed to access local media devices。这就涉及到证书。单实例部署时如果你只是内网自用最省事的方案是直接用https://localhost访问浏览器会认为localhost是安全上下文。但这样做在实际工作中几乎没用因为同事们不可能每次都通过远程桌面去服务器上的浏览器访问。更现实的方案是给服务器配一张HTTPS证书。如果你有公网域名首选免费证书方案用Certbot或者在线生成Lets Encrypt证书得到fullchain.pem和privkey.pem。像素流送信令服务器支持读取的文件格式是PEM而Windows服务器上管理员可能习惯用IIS或MMC导入PFX证书。这里注意不要直接把PFX丢给信令服务器用信令服务器需要的是纯文件形式的PEM证书不是Windows证书库里的证书。如果你没有公网域名只在内网用IP访问那可以自己生成自签名证书。生成自签名证书的工具很多我习惯用OpenSSLopenssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes注意生成时Common Name填服务器的IP或内网域名并且如果你用IP访问浏览器会提示证书无效需要在每台客户端上把证书导入受信任的根证书颁发机构否则浏览器还是会拦你。这一步经常被人忽略结果是信令服务器和UE进程都起来了其他同事访问时却被浏览器安全警告挡住然后误以为“服务挂了”。3.2 信令服务器 config 解析与常见配置项信令服务器的配置文件通常在Engine\Source\Programs\PixelStreaming\WebServers\SignallingWebServer\config.json里。核心配置项有这几个配置项默认值说明UseFrontendtrue是否提供前端页面通常保持trueUseHTTPSfalse是否启用HTTPS内网调试可以先关掉HTTPSPort443HTTPS端口HTTPPort80HTTP端口如果你没证书可以先走80ServerPort8888信令WebSocket端口PeerPort8889UE进程连接的端口LogToFilefalse是否写日志文件排查问题时建议打开新手最容易搞混的是ServerPort和PeerPort。浏览器通过ServerPort默认8888连接信令服务器UE打包程序通过PeerPort默认8889连接信令服务器。在信令服务器页面里你把鼠标放到连接状态上看到的信令服务器地址如果写的ws://localhost:8888指的是浏览器要连的信令入口。UE侧配置的-PixelStreamingURLws://服务器IP:8889才是告诉UE往哪里上报自己准备好了。有一点值得注意像素流送经过版本迭代不同UE小版本的配置文件字段名有差异。UE5.0和UE5.1时代的配置文件叫config.jsonUE5.2之后官方迁移到了config.js里面是module.exports或者JS对象。你在配置前先打开目录看一下目录里是config.json还是config.js跟着文件名配置就不会错。之前有人卡了半天说“改了配置没效果”最后发现他改的是一个没用到的json文件。3.3 启动方式与常见启动报错启动信令服务器在Windows下直接用命令行cd C:\UE5\Engine\Source\Programs\PixelStreaming\WebServers\SignallingWebServer npm install node .\Start_SignallingServer.ps1 --httpPort80 --httpsPort443第一次npm install会下载依赖如果你之前没配镜像源这里就会卡很久。启动后看到WebSocket listening to 8888这类日志说明信令服务起来了。常见的启动报错有以下几种Error: listen EADDRINUSE: address already in use :::8888说明8888端口被占用。用netstat -ano | findstr 8888看是谁占用的一般是之前残留的node进程可以用taskkill /PID 进程号 /F杀掉。Error: Cannot find module express说明没有执行npm install或者npm install失败。把node_modules目录删掉重新装一遍是最快的解决方式。TypeError: Cannot read properties of undefined (reading xxx)多数是配置文件格式问题比如把JSON文件里写了注释或者少了括号。用VSCode打开配置文件看有没有语法报错。4. Windows 服务器部署实操防火墙、端口与守护进程4.1 端口梳理与防火墙规则一轮下来端口全通才算开始像素流送在Windows服务器上需要放行的端口主要有这些端口用途连接方向80 / 443前端页面HTTP/HTTPS访问浏览器 - 服务器8888信令WebSocket浏览器 - 服务器8889UE进程连接信令服务服务器本机UE - 信令服务19303WebRTC媒体流端口浏览器 - 服务器这里最坑的是19303这个范围端口。UE像素流送默认从19303开始分配UDP/TCP端口用于媒体流而且是一个流一个端口如果你开了多个并发端口会依次往后递增。Windows防火墙如果只放行了单个端口第二个用户进来就会失败。我当时就是因为只开了19303一个端口测试第一个用户没问题第二个用户进来后一直黑屏。排查半天才发现是防火墙规则没覆盖端口范围。正确做法是在防火墙高级规则里新建一条“入站规则”协议选UDP和TCP端口范围填19303-19320或者更大比如19303-19350给未来多用户预留空间。另外如果服务器上有多个网卡或者启用了虚拟网卡UE的像素流送会选择一个网卡作为媒体流的绑定地址。有时候默认选的网卡不是对外通信的那个网卡导致客户端收到了一个错误的内网IP。这个问题可以通过启动参数强制指定-PixelStreamingIP服务器实际IP -PixelStreamingPort8889不要问为什么设了8889却还要单独指定媒体端口这是UE5像素流送的老毛病了多网卡环境下不指定IPcandidate就会飘。4.2 用 NSSM 把 Node.js 服务注册成 Windows 服务手动开CMD跑信令服务器的问题是一旦你关闭终端服务就断了。服务器上干活没人会24小时远程桌面挂着所以要把信令服务器注册成Windows服务。我推荐用NSSMNon-Sucking Service Manager这个工具。下载并解压后用管理员权限的CMD执行nssm install PixelStreamingSignaling会弹出一个图形配置窗口Application Path填C:\Program Files\nodejs\node.exeStartup Directory填C:\UE5\Engine\Source\Programs\PixelStreaming\WebServers\SignallingWebServerArguments填启动脚本的完整路径例如C:\UE5\...\Start_SignallingServer.ps1或直接填node.exe要执行的js文件。如果你在启动脚本里已经配置了端口这里就不需要再加参数。配置完成后在NSSM界面点“Install service”然后到服务管理器里把PixelStreamingSignaling设置为自动启动。用NSSM的好处不只是开机自启它的日志捕获功能也很有用。在NSSM的“I/O”标签页可以设置stdout和stderr输出到指定文件这样信令服务器日志就能持久化。排查问题时直接打开日志文件看比在CMD窗口里翻屏幕方便得多。4.3 把 UE 打包程序跑起来直接传参别用可视化快捷键像素流送打包的UE程序运行方式有讲究。在开发机上你可以通过编辑器PIE的方式直接测试像素流送但服务器上跑的是打包后的exe最好的方式是生成一个快捷方式在目标后面加启动参数C:\PixelStreaming\Windows\MyProject.exe -RenderOffScreen -PixelStreamingIP127.0.0.1 -PixelStreamingPort8889 -log几个参数的含义-RenderOffScreen离屏渲染。服务器上通常没有显示器也不希望弹出窗口这个参数强制UE在后台渲染画面。如果不加这个参数有时候服务器桌面被锁定时画面会停滞这在服务器部署时非常常见。-PixelStreamingIP指向信令服务器地址因为信令服务器和UE跑在同一台机器填127.0.0.1即可。-PixelStreamingPort因为信令服务器用8888和浏览器通信用8889和UE通信这里对应8889。-log让日志输出到一个log窗口。如果加上-log AbsLogC:\PixelStreaming\MyProject.log可以指定日志路径排查启动崩溃和端口连接问题非常关键。有一点要特别说明很多人在服务器上双击运行打包后的exe结果发现画面黑屏或者程序闪退。大概率是因为Windows的图形界面会话权限问题。如果你是通过远程桌面登录服务器再启动UE进程当远程桌面断开时有些配置下GPU渲染会随会话一并中断这时候就需要用到-RenderOffScreen或者配合虚拟显示器驱动比如虚拟显示适配器来保证无头渲染。如果没有虚拟显示器也可以用UE的Null RHI做纯逻辑跑法但那样就看不到像素流送画面了没意义。更靠谱的方案是给服务器装一个虚拟显示设备或者用注册表修改显示器分辨率的工具模拟出一个1080P显示器这样离屏渲染不会被系统挂起。5. 常见问题与排查技巧实录5.1 ShaderCompile 的 fatal error路径里藏着大坑标题里提到的那个报错我自己也遇到过好几次fatal error: [file:D:\build\UE5\Sync\Engine\Source\Programs\ShaderCompileWorker\...]这个错误看起来像是引擎源码编译出错实际上绝大多数情况下是ShaderCompileWorkerSCW缺少运行依赖或者权限不够导致的。打包好的工程里会带一个Engine\Binaries\Win64\ShaderCompileWorker.exe它在启动时会临时编译运行所需的着色器。当它以服务身份运行时经常因为工作目录不在exe所在目录导致找不到编译资源。解决方法是在你的UE项目启动快捷方式的“起始位置”里把工作目录明确设置为打包输出目录比如C:\PixelStreaming\Windows\同时确保服务器上安装对应的VC RedistributableVisual C运行库特别是2015-2022版本否则SCW启动时报缺少dll再把具体dll名查一下补上对应的运行库包。还有一点容易被忽略杀毒软件可能会拦截SCW生成的临时文件。Windows Server自带的Defender实时保护经常会把SCW生成的着色器缓存文件隔离掉导致渲染时不断报错。建议把打包输出目录和UE的缓存目录加入Defender排除列表。5.2 页面黑屏但进程在跑先看浏览器控制台和WebRTC内部状态表现信令服务器正常UE进程在任务管理器里活得好好的浏览器打开页面能显示UI但视频区域黑屏。这个时候别急着怀疑UE端先按下面顺序排查按F12打开浏览器开发者工具看Console有没有报错。如果看到Failed to set remote answer sdp或者ICE failed说明WebRTC协商出了问题。在Console里执行pc.getStats()看不到有效数据时说明连接根本没建立。在信令服务器日志中看UE进程有没有注册进来。如果信令服务器完全没有UE连接记录说明UE连接8889端口失败了。这时候检查UE启动参数里的-PixelStreamingIP和-PixelStreamingPort是否跟信令服务器配置一致。检查UE日志里有没有Pixel Streaming相关内容。如果UE启动时没有输出类似WebRTCSignalling: Connected to...的日志说明UE和信令服务器之间的WebSocket没连上。曾经有一次我折腾了很久发现是因为我同时启动了多个信令服务器实例端口冲突导致新启动的实例其实没有监听8888而浏览器访问到了旧实例。所以每次改动config后先确认旧的node进程都杀干净了再重新启动。5.3 8666 信令端口通了却连不上IP和证书混在一起出问题如果你遇到信令端口从外部访问是通的可以用telnet 服务器IP 8888验证但浏览器始终显示Disconnected多半是证书和IP的相互牵扯问题。比如你用HTTPS访问了信令服务器但信令服务器的证书CN写的是域名而你又用IP访问浏览器会认为证书无效并直接终止WebSocket连接。表面上看端口是通的实际上安全层已经把连接断掉了。处理方式有两种证书的CNCommon Name和访问地址保持一致用域名访问就用域名证书用IP访问就生成包含IP的自签名证书。前端页面通过HTTP访问信令层也用ws://而不要混wss://。注意在config里如果你开了UseHTTPSWebSocket会自动用wss这个不要和页面层的HTTP/HTTPS搞混否则会出现“页面能打开但视频连不上”的割裂情况。5.4 常见问题速查表总结了这一路上高频出现的问题和对应解法问题现象可能原因解决动作信令服务器启动报node:util导出错误Node.js版本过高卸载安装Node.js 18 LTScoturn目录没有exe下载的是源码包而非预编译包下载Release里的Windows预编译包浏览器页面显示不安全/黑屏缺少HTTPS证书或使用了HTTP非安全上下文配置证书并用HTTPS访问或用localhost第二个用户黑屏防火墙只开了单个WebRTC端口放行19303-19350端口范围远程桌面断开后画面卡住GPU渲染随会话中断使用-RenderOffScreen或虚拟显示器UE启动提示缺少dll缺少VC运行库安装VC Redistributable 2015-2022UE日志里没有信令连接记录UE连接8889失败检查启动参数和config里的PeerPort杀掉CMD后服务消失没有注册成Windows服务用NSSM注册开机自启最后再分享一个小技巧像素流送调试阶段一定要打开信令服务器的日志和UE日志两边对照着看。每次启动都看一遍“浏览器 - 信令 - UE”这条链路上每一步的日志输出基本能把80%的问题定位到具体环节。我自己后来还写了一个批处理每次重启服务时自动清理旧的日志文件把当前启动时间写进日志文件名这样排查问题的时候能快速定位是哪一次启动的日志不会在一堆重复日志里翻瞎眼。部署这套东西没有想象中难但只要把环境基础打扎实后面扩并发、加节点都会顺畅很多。