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 再放入项目，否则引擎无法识别和加载插件模块。
安装步骤：
1.3 验证安装
在 UMG 中新建一个 Widget Blueprint，能看到并拖入 WebNative Browser 控件即说明插件加载成功（详细配置见 03-WebNativeWidget 参数配置）。
2. 第一步：创建网页
在项目任意可部署位置新建 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 服务。
3. 第二步：加载网页
3.1 创建 UMG Widget Blueprint
在 UE 编辑器的 内容浏览器（Content Browser） 中，新建一个 Widget Blueprint：
3.2 放置 WebNative Browser 控件
3.3 配置 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-平台兼容性
