UE5 WebNativeBrowser快速入门
01 快速开始
目标：10 分钟内跑通完整链路—— 安装插件、加载网页、JS → UE 发消息、UE → JS 回消息。
1. 安装插件
1.1 选择正确的包
插件包必须同时匹配三个维度：
| 维度 | 说明 | 示例 |
|---|---|---|
| Unreal Engine 小版本 | 每个 UE 小版本有独立包 | UE 5.3 |
| 目标平台 | Win64 / Linux x86_64 / Linux ARM64 | Win64 |
| 产品版本 | 插件版本号 | 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：
<!doctypehtml><htmllang="zh-CN"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width,initial-scale=1"><title>WebNativeBrowser Quick Start</title><style>html, 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></head><body><h1id="title">Hello Unreal Engine</h1><buttonid="send">发送到 UE</button><script>document.getElementById("send").addEventListener("click",()=>{WebNative.send("OnHello",{text:"来自网页的消息",time:newDate().toISOString()});});WebNative.on("HelloResult",(messageBody)=>{constresult=JSON.parse(messageBody);document.getElementById("title").textContent=result.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"按钮后，事件收到两个参数：
| 参数 | 本例值 | 说明 |
|---|---|---|
FunctionName | OnHello | 网页发送的消息名称 |
MessageBody | {"text":"来自网页的消息","time":"..."} | 对象自动序列化后的 JSON 字符串 |
蓝图中先判断FunctionName，再按业务需要解析MessageBody。
5. 第四步：从 UE 回复
调用SendMessageToJS：
FunctionName: HelloResult MessageBody: {"text":"UE 已经收到消息"}在蓝图中调用Send Message To JS节点，分别填入FunctionName与MessageBody（String 类型）：
网页的WebNative.on("HelloResult", ...)回调会收到原始字符串，在明确是 JSON 时自行调用JSON.parse()。
6. 运行效果
- 页面正常显示在三维场景中；
- 点击按钮，UE 日志收到
OnHello； - UE 回复后，网页标题变为
UE 已经收到消息。
至此，加载网页 + 双向通信的完整闭环已经跑通。
7. 常见安装问题
| 现象 | 排查方向 |
|---|---|
| 插件模块无法加载 | 包与 UE 小版本或平台不匹配，重新下载匹配的包 |
| 打包后找不到网页 | 确认网页资源已包含进包，避免写开发电脑的绝对路径 |
| Linux 无法启动 | 核对架构与 GLIBC、Vulkan/GPU 驱动、文件权限、运行时文件完整性 |
| 页面空白 | 检查InitialURL路径、CSP、跨域；用 11-疑难解答 的 DevTools 定位 |
下一步
- 需要设计稳定的消息名称和数据结构：02-双向通讯
- 需要了解 Widget 全部参数：03-WebNativeWidget 参数配置
- 使用 Vue/React 工程化接入：05-案例介绍
- 计划打包发布：08-平台兼容性