01 Quick Start
目标：10 分钟内跑通完整链路 —— 安装插件、加载网页、JS → UE 发消息、UE → JS 回消息。
插件包必须同时匹配 三个维度：
| 维度 | 说明 | 示例 |
|---|---|---|
| Unreal Engine 小版本 | 每个 UE 小版本有独立包 | UE 5.3 |
| 目标平台 | Win64 / Linux x86_64 / Linux ARM64 | Win64 |
| 产品版本 | 插件版本号 | WebNativeBrowser v1.0.0 |
⚠️ 不要把为另一个 UE 小版本构建的二进制包直接复制到当前项目，会导致模块无法加载。
请根据你的 Unreal Engine 版本选择对应插件包下载：
推荐项目级安装，目录结构如下：
YourProject/
├─ Plugins/
│ └─ WebNativeBrowser/ # 完整插件目录
└─ YourProject.uproject
⚠️ 插件目录名必须是WebNativeBrowser。无论从商店、官网还是 Git 仓库获取的压缩包或源码目录，解压后目录名不一定叫这个名字（如WebNativeBrowser-master、UEWebNativeBrowser等），请先重命名为WebNativeBrowser再放入项目，否则引擎无法识别和加载插件模块。
安装步骤：
- 关闭 Unreal Editor。
- 如果是升级：备份项目配置，完整移除旧的
Plugins/WebNativeBrowser目录（避免旧二进制或资源残留）。 - 确认插件目录名为
WebNativeBrowser（不是则先重命名），整体复制到项目Plugins下。 - 启动项目，在 Edit → Plugins 中确认 WebNative Browser 已启用，按提示重启编辑器。
- 授权：正式授权流程以购买渠道附带的授权说明为准，不要把机器码或授权文件提交到公开仓库。
在 UMG 中新建一个 Widget Blueprint，能看到并拖入 WebNative Browser 控件即说明插件加载成功（详细配置见 03-WebNativeWidget 参数配置）。
在项目任意可部署位置新建 hello.html：
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="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>
<h1 id="title">Hello Unreal Engine</h1>
<button id="send">发送到 UE</button>
<script>
document.getElementById("send").addEventListener("click", () => {
WebNative.send("OnHello", {
text: "来自网页的消息",
time: new Date().toISOString()
});
});
WebNative.on("HelloResult", (messageBody) => {
const result = JSON.parse(messageBody);
document.getElementById("title").textContent = result.text;
});
</script>
</body>
</html>开发阶段也可以先加载本地开发服务器（如 Vue/Vite、React 的 dev 地址）快速迭代；发布时建议使用构建后的静态资源或正式 HTTPS 服务。
在 UE 编辑器的 内容浏览器（Content Browser） 中，新建一个 Widget Blueprint：
- 右键
Content目录 → User Interface → Widget Blueprint。 - 弹出父类选择框，保持默认 User Widget，点击 Select。
- 命名为
UMG_Demo，双击打开进入 UMG 编辑器。
- 在 UMG 编辑器左侧 Hierarchy 面板中默认有一个 CanvasPanel（如果没有，拖一个进去作为根容器）。
- 打开右侧 Palette，搜索
Web Native Browser，将控件拖入 CanvasPanel，调整 Slot 撑满容器：
图 1-2 UMG 中放置 WebNative Browser 控件
- 在系统文件浏览器中定位
hello.html，按住 Shift + 右键 → 复制为路径（Win10/11），得到形如E:\UEProjects\YourProject\hello.html的物理路径。 - 在该路径前加
file:///前缀，并把\改为/（例如file:///E:/UEProjects/YourProject/hello.html）。 - 选中 WebNative Browser 控件，在 Details 面板 WebNative | Page 分类下，将
InitialURL填入该路径：
图 1-3 Details 面板配置 InitialURL
打开任意关卡蓝图（Level Blueprint），在 Event BeginPlay 中拉出 Create Widget 节点（Class 选 UMG_Demo），再连到 Add to Viewport：
图 1-4 Create Widget 与 Add to Viewport 蓝图节点
播放关卡后，hello.html 页面会随 UMG_Demo 一起显示到画面上：
图 1-5 播放关卡后页面在 UE 视口显示
在 WebNative Browser 控件的 Details 面板中绑定 OnMessageReceived 事件：
图 1-4 绑定 OnMessageReceived
点击"发送到 UE"按钮后，事件收到两个参数：
| 参数 | 本例值 | 说明 |
|---|---|---|
FunctionName |
OnHello |
网页发送的消息名称 |
MessageBody |
{"text":"来自网页的消息","time":"..."} |
对象自动序列化后的 JSON 字符串 |
蓝图中先判断 FunctionName，再按业务需要解析 MessageBody。
调用 SendMessageToJS：
FunctionName: HelloResult
MessageBody: {"text":"UE 已经收到消息"}
在蓝图中调用 Send Message To JS 节点，分别填入 FunctionName 与 MessageBody（String 类型）：
图 1-6 调用 SendMessageToJS 蓝图节点
网页的 WebNative.on("HelloResult", ...) 回调会收到原始字符串，在明确是 JSON 时自行调用 JSON.parse()。
图 1-8 运行效果：双向通信完整闭环
- 页面正常显示在三维场景中；
- 点击按钮，UE 日志收到
OnHello； - UE 回复后，网页标题变为
UE 已经收到消息。
至此，加载网页 + 双向通信 的完整闭环已经跑通。
| 现象 | 排查方向 |
|---|---|
| 插件模块无法加载 | 包与 UE 小版本或平台不匹配，重新下载匹配的包 |
| 打包后找不到网页 | 确认网页资源已包含进包，避免写开发电脑的绝对路径 |
| Linux 无法启动 | 核对架构与 GLIBC、Vulkan/GPU 驱动、文件权限、运行时文件完整性 |
| 页面空白 | 检查InitialURL 路径、CSP、跨域；用 11-疑难解答 的 DevTools 定位 |
- 需要设计稳定的消息名称和数据结构：02-双向通讯
- 需要了解 Widget 全部参数：03-WebNativeWidget 参数配置
- 使用 Vue/React 工程化接入：05-案例介绍
- 计划打包发布：08-平台兼容性