UE5 WebNativeBrowser快速入门

01 快速开始目标10 分钟内跑通完整链路—— 安装插件、加载网页、JS → UE 发消息、UE → JS 回消息。1. 安装插件1.1 选择正确的包插件包必须同时匹配三个维度维度说明示例Unreal Engine 小版本每个 UE 小版本有独立包UE 5.3目标平台Win64 / Linux x86_64 / Linux ARM64Win64产品版本插件版本号WebNativeBrowser v1.0.0⚠️ 不要把为另一个 UE 小版本构建的二进制包直接复制到当前项目会导致模块无法加载。下载地址请根据你的 Unreal Engine 版本选择对应插件包下载UE 5.1 插件包UE 5.2 插件包UE 5.3 插件包UE 5.4 插件包UE 5.5 插件包UE 5.6 插件包UE 5.7 插件包UE 5.8 插件包1.2 安装到项目推荐项目级安装目录结构如下YourProject/ ├─ Plugins/ │ └─ WebNativeBrowser/ # 完整插件目录 └─ YourProject.uproject⚠️插件目录名必须是WebNativeBrowser。无论从商店、官网还是 Git 仓库获取的压缩包或源码目录解压后目录名不一定叫这个名字如WebNativeBrowser-master、UEWebNativeBrowser等请先重命名为WebNativeBrowser再放入项目否则引擎无法识别和加载插件模块。安装步骤关闭Unreal Editor。如果是升级备份项目配置完整移除旧的Plugins/WebNativeBrowser目录避免旧二进制或资源残留。确认插件目录名为WebNativeBrowser不是则先重命名整体复制到项目Plugins下。启动项目在Edit → Plugins中确认WebNative Browser已启用按提示重启编辑器。授权正式授权流程以购买渠道附带的授权说明为准不要把机器码或授权文件提交到公开仓库。1.3 验证安装在 UMG 中新建一个 Widget Blueprint能看到并拖入WebNative Browser控件即说明插件加载成功详细配置见 03-WebNativeWidget 参数配置。2. 第一步创建网页在项目任意可部署位置新建hello.html!doctypehtmlhtmllangzh-CNheadmetacharsetutf-8metanameviewportcontentwidthdevice-width,initial-scale1titleWebNativeBrowser Quick Start/titlestylehtml, body{margin:0;min-height:100vh;background:transparent;}body{display:flex;flex-direction:column;justify-content:center;align-items:center;gap:32px;color:#f5f5f5;font-family:-apple-system,Segoe UI,Microsoft YaHei,sans-serif;}h1{font-size:64px;margin:0;text-align:center;color:#ffffff;}button{font-size:32px;padding:16px 48px;border:none;border-radius:8px;background:#2d8cf0;color:#fff;cursor:pointer;}button:hover{background:#57a3f3;}/style/headbodyh1idtitleHello Unreal Engine/h1buttonidsend发送到 UE/buttonscriptdocument.getElementById(send).addEventListener(click,(){WebNative.send(OnHello,{text:来自网页的消息,time:newDate().toISOString()});});WebNative.on(HelloResult,(messageBody){constresultJSON.parse(messageBody);document.getElementById(title).textContentresult.text;});/script/body/html开发阶段也可以先加载本地开发服务器如 Vue/Vite、React 的 dev 地址快速迭代发布时建议使用构建后的静态资源或正式 HTTPS 服务。3. 第二步加载网页3.1 创建 UMG Widget Blueprint在 UE 编辑器的内容浏览器Content Browser中新建一个Widget Blueprint右键Content目录 →User Interface → Widget Blueprint。弹出父类选择框保持默认User Widget点击Select。命名为UMG_Demo双击打开进入 UMG 编辑器。3.2 放置 WebNative Browser 控件在 UMG 编辑器左侧Hierarchy面板中默认有一个CanvasPanel如果没有拖一个进去作为根容器。打开右侧Palette搜索Web Native Browser将控件拖入CanvasPanel调整 Slot 撑满容器3.3 配置 InitialURL在系统文件浏览器中定位hello.html按住 Shift 右键 → 复制为路径Win10/11得到形如E:\UEProjects\YourProject\hello.html的物理路径。在该路径前加file:///前缀并把\改为/例如file:///E:/UEProjects/YourProject/hello.html。选中 WebNative Browser 控件在 Details 面板WebNative | Page分类下将InitialURL填入该路径3.4 在关卡中显示 Widget打开任意关卡蓝图Level Blueprint在Event BeginPlay中拉出Create Widget节点Class 选UMG_Demo再连到Add to Viewport播放关卡后hello.html页面会随UMG_Demo一起显示到画面上4. 第三步接收 JS 消息在 WebNative Browser 控件的 Details 面板中绑定OnMessageReceived事件点击发送到 UE按钮后事件收到两个参数参数本例值说明FunctionNameOnHello网页发送的消息名称MessageBody{text:来自网页的消息,time:...}对象自动序列化后的 JSON 字符串蓝图中先判断FunctionName再按业务需要解析MessageBody。5. 第四步从 UE 回复调用SendMessageToJSFunctionName: HelloResult MessageBody: {text:UE 已经收到消息}在蓝图中调用Send Message To JS节点分别填入FunctionName与MessageBodyString 类型网页的WebNative.on(HelloResult, ...)回调会收到原始字符串在明确是 JSON 时自行调用JSON.parse()。6. 运行效果页面正常显示在三维场景中点击按钮UE 日志收到OnHelloUE 回复后网页标题变为UE 已经收到消息。至此加载网页 双向通信的完整闭环已经跑通。7. 常见安装问题现象排查方向插件模块无法加载包与 UE 小版本或平台不匹配重新下载匹配的包打包后找不到网页确认网页资源已包含进包避免写开发电脑的绝对路径Linux 无法启动核对架构与 GLIBC、Vulkan/GPU 驱动、文件权限、运行时文件完整性页面空白检查InitialURL路径、CSP、跨域用 11-疑难解答 的 DevTools 定位下一步需要设计稳定的消息名称和数据结构02-双向通讯需要了解 Widget 全部参数03-WebNativeWidget 参数配置使用 Vue/React 工程化接入05-案例介绍计划打包发布08-平台兼容性