UniApp与H5双向通信完整方案：web-view桥接、postMessage与evalJS实战

做混合开发的人，基本都绕不开 UniApp 和 H5 之间的通信问题。我在实际项目里接手过不少类似需求，最常见的场景就是：App 壳子里嵌了一个 H5 页面，需要把原生页面的用户信息传进去，H5 页面操作完以后再把结果回传给 App 层做后续处理。这个流程听起来简单，真做起来，通信时机、平台差异、数据序列化、回调丢失这些问题，一个接一个冒出来。

这篇文章我不讲虚的，直接把 UniApp 与 H5 双向通信的完整链路拆开讲透。你会看到一整套可复用的通信协议设计、完整的代码实现、联调验证方式，以及我在多个平台上踩过的坑和最终采用的绕坑方案。不管你是刚开始接触 uni-app 的 web-view，还是已经被通信问题折磨过一阵子，这篇文章都能帮你少走不少弯路。

1. 通信场景梳理：先搞清楚双向通信到底在解决什么问题

1.1 核心需求拆解：什么是双向通信

先明确一下这里说的“双向通信”是什么意思。UniApp 编译产物分三种形态：App（原生壳）、小程序、H5 网页。我们讨论的场景特指UniApp 通过 web-view 组件承载一个外部 H5 页面，此时产生了一条“UniApp 容器 -> H5 页面”的链路，以及一条“H5 页面 -> UniApp 容器”的链路。双向，就是指这两条链路都要打通。

如果你做的是纯 H5 项目，页面之间跳转传参用 URL query 就够了，不涉及“双向”这个概念。但一旦 H5 被嵌进 App 的 web-view 里，它就变成了一个“寄生页面”，它需要知道自己在哪里、宿主是谁、宿主给了它什么数据；同时它产生的操作结果，又必须安全地送回宿主。这就要求通信不是单向的“喂数据”，而是双方的协议协同。

1.2 常见业务场景与数据方向

我把实际项目里高频出现的通信场景列在下面，你在设计代码结构之前，先对号入座看看自己属于哪种：

UniApp -> H5 方向（下行数据）

• 用户登录态传递：App 登录之后拿到 token，H5 内部请求接口时需要在 header 里带上。
• 基础信息注入：设备信息、App 版本号、当前语言、个性化配置参数。
• 业务指令下发：比如从原生页面点击某个按钮，要求 H5 自动滚到某个位置，或者触发某个 H5 内部函数。

H5 -> UniApp 方向（上行数据）

• 页面操作结果回报：H5 内完成了某项操作，比如领取成功、填写表单并校验通过，需要通知原生跳转到下一个原生页面。
• 数据持久化需求：H5 想把某个值存到 App 本地存储里，下次打开还能读。
• 调起原生能力：H5 需要调用 App 的分享、定位、拍照等功能，但不能直接操作原生 API，只能先发消息给容器，让容器去调原生能力。

1.3 别指望一套方案吃遍所有平台

我在项目里吃过最大的亏，就是默认“这套 evalJS 方案在 App 端能用，在小程序端也一定能用”。实际情况完全不同：UniApp 的 web-view 在 App 端有完整的 plus 桥接能力，到了小程序端就变成了受限的 组件，通信通道基本只能靠小程序侧的业务逻辑自己去处理。所以在设计通信方案前，必须确认你的目标运行平台是什么。通常我的做法是：以 App 端为完整双向通信基线，H5 端做降级兼容，小程序端单独做通道适配。

2. 通信环境搭建：web-view 组件的正确打开方式

2.1 web-view 基础用法与参数说明

通信的前提是 H5 页面被正确加载到 web-view 容器里。UniApp 官方提供的是web-view组件，我日常用的基础结构长这样：

<template> <view class="container"> <web-view :src="webViewSrc" @message="handleMessage"></web-view> </view> </template>

对应的 script 部分：

export default { data() { return { webViewSrc: '' } }, onLoad(options) { // 通常 H5 地址是由上一个页面传递过来，或者从接口动态获取 const targetUrl = options.url || 'https://example.com/h5-page' this.webViewSrc = this.buildUrl(targetUrl, this.buildQueryParams()) }, methods: { buildQueryParams() { // 这里先把能通过 URL 传的参数处理一下 return { token: 'user_token_xxxx', appVersion: '1.2.0', platform: 'app' } }, buildUrl(url, params) { const query = Object.keys(params) .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(params[key])}`) .join('&') return url + (url.includes('?') ? '&' : '?') + query }, handleMessage(event) { // H5 通过 postMessage 传来的数据会在这里收 console.log('收到 H5 消息：', event.detail.data) } } }

2.2 src 属性动态绑定与加载时机

这里有一个容易踩的细节：web-view 的 src 一旦在页面加载期间被修改，页面会重新加载。所以不要在 H5 已经加载完成后频繁改变 src 去“传参”，这是错误做法。正确的做法是在初始化时就把参数拼进 URL，H5 页面在自身脚本里解析 URL。

另外，web-view在 App 端是原生组件层级，它天然会覆盖同层普通组件。你要在 web-view 上浮一个原生按钮或弹窗，层级关系会非常难调。我的经验是：能不覆盖就不覆盖，需要交互时通过通信让 H5 自己渲染 UI，而不是强行盖原生组件。

2.3 关于 H5 地址的常见限制

H5 地址必须是网络 URL，不是本地 HTML 文件路径。开发阶段你可能会想把 HTML 文件放在static目录下然后直接引用，我在实际项目里试过，App 端 web-view 加载本地 HTML 时经常出现路径解析异常，特别是在打包后。稳妥方案是：开发时用本地服务跑 H5（比如 Vite dev server 指向局域网地址），正式环境用线上 CDN 地址。

提示：web-view 的 src 地址如果是 HTTPS，尽量保证页面内容也是 HTTPS，不要混用 HTTPS 页面加载 HTTP 资源，否则会出现混合内容被浏览器拦截，H5 页面白屏且控制台看不出明显报错。

3. UniApp 下发数据到 H5：evalJS 方案全解析

3.1 evalJS 在哪一步执行

URL 传参解决了“初始化时的静态参数传递”，但实际开发中大量场景是动态下发指令。比如用户登录状态变更了，App 端希望立刻通知 H5 页面；或者原生页点击了一个按钮，要求 H5 跳转到指定 tab。这种场景必须绕过 URL，用代码动态执行 H5 内的 JavaScript 函数。

在 UniApp App 端，使用plus.webview获取到 web-view 对应的原生 webview 实例，然后调用它的evalJS方法：

// 先找到当前页面的 webview const currentWebview = this.$scope.$getAppWebview() // 获取页面内所有子 webview，web-view 组件对应的就是它内部创建的那个 const childWebviews = currentWebview.children() if (childWebviews && childWebviews.length > 0) { const wv = childWebviews[0] wv.evalJS(`window.receiveMessageFromApp && window.receiveMessageFromApp(${JSON.stringify(payload)})`) }

这段代码里我做了两件事：检查window.receiveMessageFromApp是否已定义，然后调用它并传入 JSON 字符串。很多教程只写wv.evalJS("...")就完了，但实际上 H5 页面可能还没加载完，函数还不存在，此时执行 evalJS 会静默失败。加一层存在性判断，至少不会报错，配合日志你能看到状态。

3.2 可靠执行的前提：H5 桥接代码就绪

evalJS 的最大痛点就是时序。我在实际项目联调时不止一次遇到这种场景：App 页面 onLoad 后就立刻想给 H5 发送数据，但 H5 页面此时还在加载 JS 资源，你 evalJS 一个根本不存在的方法，什么反馈都没有。这个问题没有银弹，只能靠“双方约定就绪信号”来解决。

约定流程是：H5 页面脚本执行完毕后，自动通过后文要讲的 postMessage 机制向 App 端发送一条__H5_READY__消息。App 收到__H5_READY__后，再统一执行待发的消息队列。这一套机制，我后面的完整案例里会实打实写出来。

3.3 复杂数据的序列化细节

evalJS 要传复杂对象，参数字符串的转义是关键。直接拼接对象转 JSON 会出问题，比如JSON.stringify后的字符串里有双引号、换行符，拼接成 JavaScript 代码时会把语法搞坏。我推荐的方案是：在 H5 端定义函数接收的是 JSON 字符串，然后在 H5 内部自己 parse。

例如 UniApp 端这样发：

const dataStr = JSON.stringify({ orderId: 'A12345', items: [{ id: 1, name: '测试商品' }], remark: '多行备注\n换行内容' }) wv.evalJS(`window.receiveMessageFromApp(${JSON.stringify(dataStr)})`)

注意这里我JSON.stringify(dataStr)，这样最终拼接进去的 JS 代码里会是一个合法的字符串字面量，不会有断行问题。H5 端这样收：

window.receiveMessageFromApp = function (dataStr) { try { const data = JSON.parse(dataStr) console.log('收到 App 数据：', data) // 业务逻辑处理 } catch (e) { console.error('解析失败：', e) } }

3.4 数据下发失败时的日志排查

evalJS 没有直接回调告诉你执行成没成功。我的排查习惯是：在 H5 的receiveMessageFromApp函数内部，收到数据后再给 App 回一条__ACK__消息表示“已送达”。这样 App 端就能区分“消息根本没发出去”和“发出了但 H5 没处理”这两种情况。

4. H5 回传数据到 UniApp：postMessage 机制详解

4.1 正向使用：uni.postMessage 还是不使用

在 H5 页面内，如果你想给容器回传数据，官方提供的是uni.postMessage接口。但你得注意一个很误导人的点：在 App 端 web-view 里，H5 自己引入的“uni 对象”并不一定是 UniApp 框架的完整实现，很多时候你直接在 H5 项目里调用uni.postMessage根本不生效。

我用的标准做法是：H5 端不依赖 uni SDK，而是通过postMessage这个 Web 原生 API，向父窗口发送消息。UniApp App 端 web-view 容器可以捕获到来自子页面的postMessage事件。把数据包装成协议格式发送：

// H5 页面内的发送函数 function sendMessageToApp(type, payload) { const message = { type: type, payload: payload, timestamp: Date.now() } // 优先使用 uniapp 注入的桥接 API if (window.uni && typeof window.uni.postMessage === 'function') { window.uni.postMessage({ data: message }) } else { // 降级：原生 web 的 postMessage window.parent.postMessage(message, '*') } }

两个分支都保留的原因很简单：有的场景 H5 被运行在 uni-app 官方 web-view 环境里，框架会注入桥接对象；但有些第三方 webview 或者纯浏览器环境，没有 uni 对象，就只能走标准 postMessage。

4.2 App 端接收 H5 回传数据的方式

在 UniApp 页面中，web-view 组件的@message事件是官方推荐方式。代码我在前面已经写过了：

handleMessage(event) { // event.detail.data 可能是数组，取决于 H5 端发送格式 const data = event.detail.data console.log('H5 回传：', data) }

但这里也有一个大坑：App 端 web-view 的message事件，并不是 H5 每次postMessage都会触发。实际上，如果 H5 内使用了uni.postMessage，消息会先被 uni-app 框架收集，然后在特定时机（比如页面后退、分享、支付回调等）统一派发，不是实时派发。

如果你需要“即发即收”的实时通道，光靠 @message 不够，需要用到另一种通信方式：URL 拦截。

4.3 通过 URL 拦截实现即时通信

这是一种野路子，但非常稳定：H5 端通过创建隐藏的 iframe 或者直接改变window.location.href，跳转到一个自定义 scheme 的 URL，比如：

window.location.href = 'uniwebview://bridge?data=' + encodeURIComponent(JSON.stringify(message))

App 端 web-view 的拦截逻辑：

// 在 App 端监听 URL 变化 const wv = childWebviews[0] wv.addEventListener('loaded', () => { // 具体拦截事件根据平台不同，常用的有 overrideUrlLoading })

在 5+ App 的 webview 里，你通常需要在plus底层注册overrideUrlLoading事件去捕获自定义 scheme。但这样写起来比较底层，而且不同版本的 HBuilderX 壳子行为会有差异。我更推荐的做法是：优先使用 @message 通道做业务消息，如果确实需要即时返回，再用隐藏 iframe + URL scheme 拦截作为辅助通道。

4.4 H5 主动调起原生能力

通信最终是为了业务。H5 内一个按钮触发分享，它不可能直接唤起 App 的分享面板，只能给 App 发送一条type: 'SHARE'的消息。App 收到后调用原生分享 API，再把分享结果回给 H5。这是一个典型的请求-响应模式。所以双向通信不能只做“单向发完不管”，还要有“应答机制”，我后面会展示完整的协议设计。

5. 完整实践：一个稳用的双向通信骨架

5.1 通信协议设计

为了统一两条链路，我设计了一套很轻量的协议，你可以直接抄：

每一条消息都是一个 JSON 对象，结构如下：

{ "type": "H5_READY", "payload": {}, "msgId": "uuid-xxx", "timestamp": 1670000000000 }

约定三件事：

• 所有消息必须带type，用来区分消息用途。
• 请求类消息带msgId，应答消息里必须带上对应的msgId，方便请求方对账。
• H5_READY类型比较特殊，是 H5 初始化完成后主动上报的启动信号。

5.2 UniApp 端完整代码骨架

UniApp 页面里我维护一个消息队列和一个回调映射表：

export default { data() { return { webViewSrc: '', pendingMessages: [], // 存储 H5 ready 前需要发送的消息 callbackMap: {}, // msgId -> callback h5Ready: false } }, methods: { handleMessage(event) { const messages = Array.isArray(event.detail.data) ? event.detail.data : [event.detail.data] messages.forEach(msg => this.dispatchMessage(msg)) }, dispatchMessage(msg) { if (!msg || typeof msg !== 'object') return switch (msg.type) { case 'H5_READY': this.h5Ready = true this.flushPendingMessages() break case 'ACK': // 收到 ACK 后，把对应的回调取出执行 const ackCallback = this.callbackMap[msg.msgId] if (ackCallback) { ackCallback(msg.payload) delete this.callbackMap[msg.msgId] } break case 'SHARE': // 演示：收到 H5 的分享请求 this.handleNativeShare(msg) break default: console.log('未处理的消息类型：', msg.type) } }, sendMessageToH5(type, payload, callback) { const msg = { type, payload, msgId: this.genMsgId(), timestamp: Date.now() } if (callback) { this.callbackMap[msg.msgId] = callback } if (!this.h5Ready) { this.pendingMessages.push(msg) return } this.executeSend(msg) }, executeSend(msg) { const currentWebview = this.$scope.$getAppWebview() const childWebviews = currentWebview.children() if (!childWebviews || childWebviews.length === 0) return const wv = childWebviews[0] const dataStr = JSON.stringify(msg) wv.evalJS(`window.receiveMessageFromApp(${JSON.stringify(dataStr)})`) }, flushPendingMessages() { while (this.pendingMessages.length > 0) { const msg = this.pendingMessages.shift() this.executeSend(msg) } }, genMsgId() { return 'msg_' + Date.now() + '_' + Math.floor(Math.random() * 10000) } } }

5.3 H5 端完整代码骨架

H5 页面里的桥接代码，我单独封装成一个bridge.js，可以复制到任意项目使用：

// bridge.js (function () { if (window.__bridgeInited) return window.__bridgeInited = true const callbacks = {} function genMsgId() { return 'h5_' + Date.now() + '_' + Math.floor(Math.random() * 10000) } function postMessageToApp(msg) { const message = Object.assign({}, msg, { msgId: msg.msgId || genMsgId() }) if (window.uni && typeof window.uni.postMessage === 'function') { window.uni.postMessage({ data: message }) } else { window.parent.postMessage(message, '*') } } window.receiveMessageFromApp = function (dataStr) { let msg try { msg = JSON.parse(dataStr) } catch (e) { console.error('[bridge] 消息解析失败', e) return } if (typeof window.onAppMessage === 'function') { window.onAppMessage(msg) } // 如果真的是一条请求，H5 必须回 ACK if (msg.type !== 'ACK') { postMessageToApp({ type: 'ACK', msgId: msg.msgId, payload: { received: true } }) } } window.sendToApp = function (type, payload, callback) { const msg = { type, payload, msgId: genMsgId() } if (callback) { callbacks[msg.msgId] = callback } postMessageToApp(msg) } // H5 初始化完成后自动上报 window.addEventListener('DOMContentLoaded', function () { setTimeout(function () { postMessageToApp({ type: 'H5_READY', payload: { page: location.href } }) }, 0) }) })()

5.4 联调验证流程

做完上面的骨架，联调时我习惯按这个顺序验证：

1. 打开 App 进入 web-view 页面，观察控制台有没有 H5_READY 消息。
2. H5 页面确认收到 H5_READY 的 ACK，说明下行通道可用。
3. App 端调用sendMessageToH5发送一条业务消息，观察 H5 端有没有打印日志。
4. H5 端调用sendToApp回传一条消息，观察 App 端 handleMessage 是否触发。
5. 验证 H5 发消息后收到的 ACK 是否带上了原 msgId。

这五个步骤走通，基本可以确认通信链路没大问题。剩下的就是业务层的兼容和数据格式问题。

6. 高频踩坑实录：通信失效的排查路径与解法

6.1 H5_READY 迟迟不来，消息全部丢失

这是最典型的启动时序问题。H5_READY 没上报，App 端队列里的消息就一直不发，等 H5_READY 到了才发现已经错过了业务时机。排查路径：

• 先确认 H5 页面是否成功加载，web-view 的 src 地址能不能在浏览器直接打开。
• H5 控制台确认 bridge.js 是否加载执行。
• 检查 H5_READY 的 postMessage 是否被浏览器安全策略拦截。
• 如果页面是通过 HTTPS 加载，但 web-view 容器校验了域名白名单，也可能导致消息被忽略。

我碰到过一次比较隐蔽的情况：H5 页面用了较新的浏览器 API，在低版本 WebView 上脚本直接报错中断，导致 bridge.js 根本没执行。后来我在 bridge.js 里加了错误捕获，即使页面其他脚本挂了，桥接代码也要先跑完。

6.2 postMessage 能收到，但 uni.postMessage 方式不稳定

很多朋友写 H5 页面时，直接在业务代码里import uni from '@dcloudio/uni-h5'，然后调用uni.postMessage，结果发现 App 端有时候能收到，有时候收不到。原因就是 uni 对象的 postMessage 在 App web-view 里表现有一点依赖注入时序。

我在项目里已经彻底放弃在 H5 里依赖 uni SDK 的通信方式，统一改为window.parent.postMessage(message, '*')或者自建桥接。你如果只能使用 uni.postMessage，那你必须确保 uni SDK 的初始化已经完成，且消息发送时 web-view 容器已经触发了 message 监听。这条路限制多，不如自建桥接稳。

6.3 evalJS 执行报错，但没有错误反馈

evalJS 的执行结果无法直接获取。我的做法是在 H5 端把收到的消息都写入一个window.__lastMessage变量，同时在页面里显示最近一次消息的内容，方便联调时看一眼就知道有没有收到。生产环境可以去掉，但联调阶段这招非常好用。

6.4 Android 和 iOS 的差异

我实际测试中，Android 端的 plus.webview 获取 childWebviews 时机比较早，onLoad 时就能拿到；iOS 端偶尔要等 web-view 组件 ready 之后才能拿到。我的建议是用setTimeout延迟获取或者在plusready后再初始化桥接对象，不要惯性认为两个平台行为一致。

6.5 H5 重新加载导致消息混乱

web-view 的 src 变化会导致页面重新加载，此时 H5 内部状态全部清空。如果 App 端已经建立了长连接或者缓存引用，必须同步重置桥接状态。我的做法是：在 H5 内部通过sessionStorage存一份会话标识，重新加载后上报消息里带上会话标识，App 端判断是同一个会话还是新会话，避免误接消息。

6.6 消息长度超过 URL 限制

使用 URL 传参时，如果参数里有一个很长的 base64 字符串或者 JSON 串，很容易触发浏览器 URL 长度上限，导致页面直接无法访问。这种情况必须走 postMessage 通道。我一般约定：静态短参数走 URL，动态长数据走 postMessage。

7. 性能与安全：双向通信的上限设计与防护

7.1 高频消息场景不要频繁 evalJS

如果 H5 页面上有个实时进度条，需要 App 端频繁推送进度值，我的建议是：不要在 App 的 setInterval 里不断 evalJS。一方面 webview 执行 JS 有开销，另一方面 H5 端频繁被 JS 打断会影响渲染帧率。更好做法是：App 端按帧合并数据，比如每秒最多推送 10 次，或者把数据放在一个共享缓冲里，让 H5 自己通过定时器去主动拉取。这就把“推”模式变成“拉”模式，压力小很多。

7.2 通信安全：别让任意 H5 都能控制你的原生层

这是很多人忽略的点。web-view 加载的 H5 页面一旦被劫持，它发过来的消息就能控制 App 做各种敏感操作。所以我强烈建议：

• 在 App 端维护一份可信域名白名单，web-view 加载 src 前校验。
• 所有从 H5 收到消息，都必须做type白名单校验，不在列表内的直接忽略。
• 需要执行敏感操作的消息（比如调起支付、读取通讯录），必须二次确认来源，不要盲目相信消息本身。

我自己的项目里，还会约定一个业务 token，由 App 通过 URL 首个参数传给 H5，H5 后续每次 postMessage 都必须带上这个 token，App 端校验 token 合法才处理消息。

7.3 通信协议版本号

通信协议也会升级，建议在消息里加一个version字段。H5 和 App 版本不是同步发布的，老版本 App 配新版本 H5 时，对未知消息要能优雅忽略，不要报错。我的处理方式是：H5 发消息前先发一个 HELLO 消息带版本号，App 端比较版本号后，对不兼容的消息类型主动降级或提示。

8. 结束前的最后一点心得

折腾完几个 UniApp 混合开发项目后，我的体会是：双向通信本身并不难，难的是“稳定地双向通信”。你实际写代码时，第一个版本往往都能跑通理想链路，但真实环境里的网络加载慢、webview 内核差异、H5 页面 JS 报错，都会把通信时序打得七零八落。建议不要跳过前面说的“就绪信号 + 消息队列 + ACK 对账”这套机制，它虽然让代码看起来多一点，但它能救你于“用户反馈偶发白屏、数据丢失”的水火之中。

另外一个小建议：H5 端的桥接代码，不要用框架耦合的方式去写。我最终把bridge.js抽成了独立文件，任何框架（Vue、React、原生 JS）都能直接引入。这样以后 H5 端换框架，通信层完全不用动。这个习惯帮我省了不少维护成本，你也可以直接照这个思路来做。