在 uniapp 项目里塞一个现成的 HTML 页面进来这种需求其实一点都不少见。常见的场景是设计那边早就给了一套写好的活动页、表单页、富文本预览页或者后台系统自带一个已经跑通的 H5 模块你不可能把这些东西用 vue 重写一遍最省事的做法就是拿 iframe 把它嵌进当前的 uniapp 页面里然后让壳子页面和里面的 HTML 能互相喊话。问题也随之而来——iframe 在 uniapp 的三个端H5、App、小程序里的生存状态完全不同通信方式也不一样稍不留神就会卡在页面是出来了但数据传不进去或者App 端直接白屏这种地方。这篇就把我从实际项目里摸出来的路子完整讲一遍包括 iframe 内嵌 HTML 的真实支持情况、本地文件该怎么放、父子页面怎么双向通信以及那些官方文档里不会写、但实测一定会遇到的坑。适合已经有 uniapp 基础、需要在 App 或 H5 里嵌入外部页面的同学看纯新手也能跟下来。1. 先搞清楚 iframe 在 uniapp 三个端的真实生存空间很多人上手第一步就栽了原因是把 uni-app 当成一套代码跑三端就默认 iframe 也能跑三端。实际上 uni-app 在不同端用的渲染方式根本不一样iframe 本质是浏览器的 DOM 标签只有渲染层是 WebView 的地方才有它立足的余地。所以你在这个方案开工之前第一件事就是确认自己的目标端到底支不支持不然写了半天发现要发的端压根用不了那就白干了。1.1 H5 端就是标准浏览器iframe 随便用H5 端最好理解uni-app 编译到 H5 之后你的页面就是运行在浏览器里的普通网页iframe 是原生支持的标签。你在 template 里直接写iframe src.../iframe就行浏览器怎么支持 iframeuni-app 的 H5 端就怎么支持。父子页面通信走的也是标准的window.postMessage和postMessage监听那一套跟写传统网页没有任何区别。这里唯一的坑不在 iframe 本身而在 uni-app 的页面生命周期上。uni-app 的页面是 Vue 组件iframe 的 DOM 节点要等组件挂载之后才能拿到真实引用所以如果你想在onLoad里就操作 iframe大概率拿到的是 null得放到onReady或者mounted里再取。这个细节后面通信那节还会细说因为它直接决定了你的第一条消息能不能发出去。1.2 App 端app-vue能跑但路径和渲染有一堆讲究App 端分两种渲染模式nvue 和 vue。nvue 走的是原生渲染压根没有 DOM 概念iframe 想都别想这条必须记死别在 nvue 页面里试。而 vue 模式的页面也就是你平时写的那种普通页面在 App 端是通过 WebView 渲染的页面本身跑在一个 WebView 里所以在这个 WebView 内部再嵌一层 iframe多数版本下是能跑起来的效果和 H5 端接近。但要注意能跑起来和官方推荐是两回事。uni-app 官方文档里对 App 端使用 iframe 并没有明确的承诺它更像是利用了 app-vue 底层就是 WebView 这个事实。所以在不同版本、不同机型上行为可能不完全一致我建议的做法是先在真机上跑通最小 Demo确认当前版本能用再决定要不要把整个方案押上去。另外 App 端 iframe 的性能明显比原生组件差嵌一个简单的静态页还行如果里面是重交互的复杂页面滑动和动画会有可感知的迟滞。1.3 小程序端压根没有 iframe别把方案往这上面套小程序端是最需要拎清楚的一环。小程序的逻辑层和渲染层是分开的渲染层不暴露 DOM你写不出iframe这个标签即便写了也不会渲染。小程序里想加载外部网页只能用web-view组件而 web-view 有它自己的规矩它是全屏的、层级最高的同一时刻通常只能加载一个页面通信机制也和 iframe 完全不同走的是uni.postMessage加message而不是window.postMessage。所以结论很明确在 uniapp 里用 iframe 内嵌 HTML 并相互通信这套方案本质是 H5 端和 App 端app-vue的方案小程序端不适用。如果你的项目要同时发小程序就得做条件编译小程序端走 web-view 那条线或者干脆把这块功能从小程序端裁掉。判断清楚这一点能省掉后面一大堆无谓的调试。目标端渲染方式iframe 支持通信方式H5浏览器原生支持window.postMessage/ 直接调函数Appapp-vueWebView多数版本可用非官方承诺window.postMessage/ 同源直调Appnvue原生渲染不支持无小程序双线程不支持用 web-view 替代uni.postMessage/message2. 本地 html 文件放哪、路径怎么写才不在 App 端白屏路径问题是 App 端 iframe 最容易翻车的地方。H5 端你怎么写路径基本都能对一到 App 端就白屏十有八九是路径没找对。核心原因在于App 端打包之后你的项目文件被塞进了一个虚拟的本地目录WebView 加载的是这个虚拟目录里的文件而你写在代码里的路径是相对谁的就需要掰扯清楚。2.1 static 目录的打包去向与 _www 映射关系uni-app 的打包规则是static 目录下的文件会被原样拷贝不参与编译打包。也就是说你把demo.html丢在static/iframe/demo.html打包之后它就会出现在 App 资源目录通常对应_www下的static/iframe/demo.html位置。这一点很关键因为它意味着你的 HTML 不会被打包器处理里面的script、link引用、相对路径都要自己保证正确。反过来说如果你把 HTML 文件放在pages或者别的地方它不会被打包进去运行时就找不到文件。所以第一个铁律所有要内嵌的静态 HTML、它依赖的 css、js、图片全部放 static 目录并且内部引用尽量用相对路径这样一个文件夹整体挪走也不会断链。2.2 H5 与 App 端引用路径的写法差异H5 端最简单src写相对根路径就行iframe src/static/iframe/demo.html/iframeApp 端就麻烦一些。实测比较稳的写法是加条件编译或者在 App 端把本地路径转换成系统能识别的绝对路径// 在 onReady 里处理 // #ifdef APP-PLUS const localPath _www/static/iframe/demo.html const absPath plus.io.convertLocalFileSystemURL(localPath) this.iframeSrc absPath // #endif // #ifdef H5 this.iframeSrc /static/iframe/demo.html // #endifplus.io.convertLocalFileSystemURL是 App 端把虚拟路径转成真实文件系统路径的接口转完之后 iframe 就能找到文件了。我自己的习惯是给 iframe 的 src 绑一个 data 变量在onReady之前不渲染或渲染成空白等路径算好了再赋值这样能避免第一次加载时路径还没准备好导致的 404。2.3 一个实测的白屏排查顺序App 端 iframe 白屏别瞎试按这个顺序排先确认控制台有没有加载错误如果路径不对通常会报找不到资源。检查 HTML 是不是真的在 static 目录里而不是被放到了别的目录。检查 HTML 内部的资源引用是不是用了绝对路径比如/css/style.css在 App 端这种以根开头的路径可能指向的不是你以为的位置改成相对路径试试。检查 HTML 里有没有用到只有浏览器环境才有的 APIApp 端 WebView 环境不完整某些接口可能不存在。最后才怀疑是不是当前 App 版本不兼容 iframe换个最小 Demo 页面验证。我遇到过最离谱的一次是 HTML 里内联了一个base href/H5 端没事App 端直接把所有相对路径解析歪了排查了半天才定位到那一行。所以看到白屏先怀疑路径再怀疑环境。3. 父子页面双向通信postMessage 通道怎么搭页面能显示出来只是第一步真正干活的是通信。父页面uniapp 页面要给 iframe 里的 HTML 传数据HTML 里的操作结果也要回传给父页面这就需要搭一条双向通道。这套机制在 H5 端和 App 端是通用的核心就是window.postMessage加message事件监听两边各干一半。3.1 父传子与子传父的两个方向方向一父页面发给 iframe 里的子页面// 父页面 const iframeEl this.$refs.myIframe // 拿到 iframe 的真实 DOM iframeEl.contentWindow.postMessage( { type: INIT_DATA, payload: { userId: 123 } }, * // 目标源后面细讲 )方向二iframe 里的子页面发给父页面// 子页面demo.html 内部 window.parent.postMessage( { type: FORM_SUBMIT, payload: { name: 张三 } }, * )两个方向都要在接收端挂上监听// 父页面监听子页面来的消息 window.addEventListener(message, (e) { const data e.data if (data data.type FORM_SUBMIT) { // 处理子页面回传的数据 } }) // 子页面监听父页面来的消息 window.addEventListener(message, (e) { const data e.data if (data data.type INIT_DATA) { // 使用父页面传来的数据初始化 } })看起来很简单但通信失败的原因往往不在写法上而在细节上接收端挂了没、targetOrigin 对不对、如果是 App 端 file 协议有没有特殊处理。这几条后面单开一节说。3.2 消息协议别再用裸字符串我见过不少项目两边直接传字符串postMessage(ok)这种能跑但一旦消息种类变多就乱套了。建议一开始就定一个简单的消息协议用对象包一层{ type: INIT_DATA, // 消息类型用于区分业务 payload: { ... }, // 实际数据 id: msg_001, // 可选用于请求-响应配对 timestamp: 1699999999 // 可选方便排查时序问题 }接收端先判断type再决定怎么处理这样做的好处是消息一眼能看懂、方便加日志、后续扩展新消息类型不动老代码。id字段在需要发一条请求、等一条响应的场景特别有用比如你在父页面发了一个请把表单数据给我的消息子页面处理完回一条带同样id的消息父页面就能对上号而不是靠消息顺序去猜。3.3 完整可复制的最小示例把上面的拼起来给一个能直接抄的最小结构。父页面uniapp 的 vue 页面template view classwrap iframe refmyIframe :srciframeSrc frameborder0 stylewidth:100%;height:600px;display:block; loadonIframeLoad /iframe button clicksendToChild给子页面发消息/button /view /template script export default { data() { return { iframeSrc: } }, onReady() { // #ifdef APP-PLUS this.iframeSrc plus.io.convertLocalFileSystemURL(_www/static/iframe/demo.html) // #endif // #ifdef H5 this.iframeSrc /static/iframe/demo.html // #endif window.addEventListener(message, this.onMessage) }, beforeDestroy() { window.removeEventListener(message, this.onMessage) }, methods: { onIframeLoad() { // iframe 加载完成可以安全地发第一条消息了 this.sendToChild() }, sendToChild() { const el this.$refs.myIframe if (el el.contentWindow) { el.contentWindow.postMessage( { type: INIT_DATA, payload: { userId: 123 } }, * ) } }, onMessage(e) { const data e.data if (data data.type FORM_SUBMIT) { console.log(收到子页面数据, data.payload) } } } } /script子页面static/iframe/demo.html!DOCTYPE html html langzh-CN head meta charsetutf-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title内嵌页/title /head body div idapp/div script // 监听父页面来的消息 window.addEventListener(message, function (e) { var data e.data if (data data.type INIT_DATA) { document.getElementById(app).innerText 收到用户ID data.payload.userId } }) // 页面加载后主动告诉父页面我准备好了 window.parent.postMessage({ type: CHILD_READY }, *) // 模拟用户操作后回传数据 function submit() { window.parent.postMessage( { type: FORM_SUBMIT, payload: { name: 张三 } }, * ) } /script /body /html这套结构基本能覆盖大多数场景。抄的时候注意两点父页面onIframeLoad里再发消息这个顺序不能省子页面主动发CHILD_READY这个握手信号也建议加上原因在第五节展开。4. 同源、跨域与 file 协议通信失败最常见的三个原因通信写完了但收不到消息是最让人抓狂的状态因为两端代码看起来都对。绝大多数情况下问题出在源上。postMessage这套机制是围绕源设计的源对不上消息就会被静默丢弃不报错、不提示你只能干瞪眼。4.1 targetOrigin 写错导致消息静默丢弃postMessage(data, targetOrigin)的第二个参数是目标源它规定了只有当接收方的源等于 targetOrigin 时消息才会被投递。上面示例里我都写的*意思是不限制源谁都能收开发阶段方便但生产环境更安全的是写具体源iframeEl.contentWindow.postMessage(data, https://your-domain.com)坑就在这如果 H5 端你的父页面在https://a.comiframe 加载的却是https://b.com的页面你在父页面发消息时把 targetOrigin 写成了https://b.com那是对的但如果写成了自己的域名或者两边域名拼错一个字母消息就石沉大海。排查方法是对接收端的 message 监听打日志看它到底有没有被触发没触发就基本确定是源的问题。4.2 file 协议下 origin 为 null 的特殊处理App 端内嵌本地 HTML 时页面是通过 file 协议或者本地虚拟路径加载的这种情况下页面的 origin 往往是null。这就是为什么在 App 端我强烈建议 targetOrigin 用*——因为你写具体源反而对不上null 这个东西没法拼成合法字符串去匹配。接收端判断时也要注意e.origin可能是null这个字符串或者空别用严格相等去比对具体域名。window.addEventListener(message, (e) { // App 端本地环境 origin 可能是 null不要写死具体域名去卡 if (e.origin ! null e.origin ! https://your-domain.com) { return } // 处理消息 })当然用*是有安全代价的任何页面都能给你发消息。所以如果消息里涉及敏感操作一定要在业务层做校验比如检查消息结构、加一个双方约定的 token别裸信任何发过来的东西。4.3 直接调用对方函数与 postMessage 的取舍如果父页面和 iframe 里的页面是同源的比如都是你自己的域名或者 App 端都在同一个本地环境其实可以走更直接的路径——直接调对方的函数// 父调子同源下可以直接拿到子页面 window 上的方法 this.$refs.myIframe.contentWindow.someMethod(data) // 子调父同源下直接挂在 window 上 window.parent.receiveFromChild(data)同源直调的好处是不用考虑 targetOrigin、消息序列化这些事传对象也没问题postMessage传的数据会被结构化克隆函数、部分特殊对象传不过去。坏处是强耦合而且一旦跨域就不成立。我的经验是开发调试阶段可以用直调快速验证思路正式方案还是走 postMessage因为它对同源/跨域一视同仁将来页面地址变了也不用大改。5. 实测中容易翻车的时序与性能问题通信链路通了不代表就稳了。跑起来之后你会发现真正的妖魔鬼怪都在时序和性能上消息发早了没人接、iframe 高度不对出现滚动条、页面切走了监听器还在、来回切几次内存涨了。这节讲的都是我在真项目里踩过的具体问题。5.1 消息比页面先到ready 握手机制最典型的场景父页面在onReady里就急着给子页面发INIT_DATA结果子页面还没加载完监听器还没挂上消息发出去就丢了。因为postMessage是发出去就不管的没有对方收到了吗的确认。解法就是握手子页面在自身script执行时第一时间发一条CHILD_READY给父页面。父页面收到CHILD_READY之后才发INIT_DATA。这样就能保证数据一定是在子页面准备好之后才发的。如果因为某些原因不方便改子页面那至少要在父页面的loadiframe 加载完成事件回调里再发消息load触发时子页面的 document 已经就绪能接收消息了。5.2 高度自适应与滚动条iframe 默认高度要么是固定的要么是 150px内容一长就出现内部滚动条在移动端体验很难看尤其是在 App 里嵌一层滚动套滚动。两个思路一是父页面给出足够高度让内容不溢出适用于内容高度可预期的场景二是让子页面向父页面报告自己的高度父页面动态设置 iframe 高度。// 子页面里报告高度 const h document.body.scrollHeight window.parent.postMessage({ type: RESIZE, payload: { height: h } }, *) // 父页面收到后改高度 if (data.type RESIZE) { this.iframeHeight data.payload.height }如果要隐藏滚动条iframe 可以加scrollingno或者子页面里设置body { overflow: hidden }。不过要注意强行隐藏滚动条会让内容超出的部分无法查看得配合高度自适应一起用否则就是掩耳盗铃。5.3 组件销毁时的监听器清理父页面的window.addEventListener(message, handler)是挂在 window 上的而 window 是整个应用共享的。如果页面切走了却不移除监听下次这个页面又进来就会挂上第二个监听器消息处理逻辑执行两遍甚至多遍表现出来就是点一次按钮触发了两次。beforeDestroy() { window.removeEventListener(message, this.onMessage) }注意removeEventListener的第二个参数必须和addEventListener时传的是同一个函数引用所以不能写成window.removeEventListener(message, () {})这种匿名函数得把处理函数定义成组件方法或者变量这样才能正确移除。这个细节特别容易被忽略我也在好几个项目里见过因此产生的重复回调。另外如果 iframe 里也往父页面发消息而父页面被销毁了事件可能还在冒泡链上最好在子页面卸载时也做一下清理或者双方约定一个DESTROY消息收到后互相停止。这些清理工作短期看不出效果但在长页面、频繁进出的场景里直接关系到会不会出现内存泄漏。6. iframe 之外的选择web-view 与 renderjs 的适用边界最后聊聊方案选型。iframe 能解决内嵌 HTML 的需求但它不是唯一的办法也不是所有场景的最优解。搞清楚什么时候该用 iframe什么时候该换web-view或者renderjs能帮你在开工前就避开后面的大坑。6.1 什么时候该换 web-view如果你的目标端包含小程序或者你只是要加载一个远端的完整网页那web-view才是正解。它由 uni-app 官方提供三个端的行为相对统一通信接口也是配套设计好的网页端调uni.postMessage页面上监听message接收。代价是web-view在小程序端是全屏的、层级最高你没法在它上面盖别的原生组件排版灵活性不如 iframe。判断标准很简单需要在小程序端跑或者加载的是远端页面用 web-view只在 H5 和 App 端、要嵌的是本地 HTML 且需要和原生界面混排才用 iframe。两者不是谁替代谁的关系是不同场景的不同工具。6.2 renderjs 解决的是另一类问题顺便说一句renderjs很多人把它和 iframe 搞混。renderjs 是 uni-app 提供的一种在 App 端操作视图层 DOM 的技术它解决的问题是在 app-vue 里如何高效地直接操作真实的 DOM而不是如何嵌入另一个页面。它常被用来做高性能的图表、动画、手势库对接。如果你要嵌的是一整页现成的 HTML那用 iframe如果你只是想在当前页面里高效操作某个 DOM 元素那才轮到 renderjs 出场。至于一开始热搜里提到的iframe 隐藏滚动条父页面调用 iframe 函数iframe 里的动态内容这些其实都属于上面几节讨论的范畴滚动条和高度走自适应那条线父调子函数在通信那节动态 iframe 只是说 src 内容动态变化改src之后记得重新走一遍握手流程就行因为新页面是全新的环境老的监听和状态都没了。需求推荐方案备注小程序端加载外部页web-viewiframe 不支持H5/App 嵌本地 HTML 并混排iframe需处理本地路径App 内高效操作 DOMrenderjs不涉及跨页面加载远端整页web-view小程序/ iframeH5、App视目标端而定我个人在实际项目里最大的体会是iframe 方案的稳定性八成取决于你有没有把路径、源、时序这三件事处理好剩下两成才是兼容性。每次新开一个 iframe 需求我都会先在目标真机上跑一个只有父页面发一句话、子页面回一句话的最小 Demo确认这条链路通了再去堆业务逻辑。这个习惯帮我省下来的返工时间比我任何一次优化都值。如果内嵌页后续还要持续迭代强烈建议和负责那个 HTML 的同事约定好消息协议把type定义写成一份双方都能看的文档不然过两个月谁都不记得当初那个ok是干嘛用的了。
在 uniapp 项目里塞一个现成的 HTML 页面进来这种需求其实一点都不少见。常见的场景是设计那边早就给了一套写好的活动页、表单页、富文本预览页或者后台系统自带一个已经跑通的 H5 模块你不可能把这些东西用 vue 重写一遍最省事的做法就是拿 iframe 把它嵌进当前的 uniapp 页面里然后让壳子页面和里面的 HTML 能互相喊话。问题也随之而来——iframe 在 uniapp 的三个端H5、App、小程序里的生存状态完全不同通信方式也不一样稍不留神就会卡在页面是出来了但数据传不进去或者App 端直接白屏这种地方。这篇就把我从实际项目里摸出来的路子完整讲一遍包括 iframe 内嵌 HTML 的真实支持情况、本地文件该怎么放、父子页面怎么双向通信以及那些官方文档里不会写、但实测一定会遇到的坑。适合已经有 uniapp 基础、需要在 App 或 H5 里嵌入外部页面的同学看纯新手也能跟下来。1. 先搞清楚 iframe 在 uniapp 三个端的真实生存空间很多人上手第一步就栽了原因是把 uni-app 当成一套代码跑三端就默认 iframe 也能跑三端。实际上 uni-app 在不同端用的渲染方式根本不一样iframe 本质是浏览器的 DOM 标签只有渲染层是 WebView 的地方才有它立足的余地。所以你在这个方案开工之前第一件事就是确认自己的目标端到底支不支持不然写了半天发现要发的端压根用不了那就白干了。1.1 H5 端就是标准浏览器iframe 随便用H5 端最好理解uni-app 编译到 H5 之后你的页面就是运行在浏览器里的普通网页iframe 是原生支持的标签。你在 template 里直接写iframe src.../iframe就行浏览器怎么支持 iframeuni-app 的 H5 端就怎么支持。父子页面通信走的也是标准的window.postMessage和postMessage监听那一套跟写传统网页没有任何区别。这里唯一的坑不在 iframe 本身而在 uni-app 的页面生命周期上。uni-app 的页面是 Vue 组件iframe 的 DOM 节点要等组件挂载之后才能拿到真实引用所以如果你想在onLoad里就操作 iframe大概率拿到的是 null得放到onReady或者mounted里再取。这个细节后面通信那节还会细说因为它直接决定了你的第一条消息能不能发出去。1.2 App 端app-vue能跑但路径和渲染有一堆讲究App 端分两种渲染模式nvue 和 vue。nvue 走的是原生渲染压根没有 DOM 概念iframe 想都别想这条必须记死别在 nvue 页面里试。而 vue 模式的页面也就是你平时写的那种普通页面在 App 端是通过 WebView 渲染的页面本身跑在一个 WebView 里所以在这个 WebView 内部再嵌一层 iframe多数版本下是能跑起来的效果和 H5 端接近。但要注意能跑起来和官方推荐是两回事。uni-app 官方文档里对 App 端使用 iframe 并没有明确的承诺它更像是利用了 app-vue 底层就是 WebView 这个事实。所以在不同版本、不同机型上行为可能不完全一致我建议的做法是先在真机上跑通最小 Demo确认当前版本能用再决定要不要把整个方案押上去。另外 App 端 iframe 的性能明显比原生组件差嵌一个简单的静态页还行如果里面是重交互的复杂页面滑动和动画会有可感知的迟滞。1.3 小程序端压根没有 iframe别把方案往这上面套小程序端是最需要拎清楚的一环。小程序的逻辑层和渲染层是分开的渲染层不暴露 DOM你写不出iframe这个标签即便写了也不会渲染。小程序里想加载外部网页只能用web-view组件而 web-view 有它自己的规矩它是全屏的、层级最高的同一时刻通常只能加载一个页面通信机制也和 iframe 完全不同走的是uni.postMessage加message而不是window.postMessage。所以结论很明确在 uniapp 里用 iframe 内嵌 HTML 并相互通信这套方案本质是 H5 端和 App 端app-vue的方案小程序端不适用。如果你的项目要同时发小程序就得做条件编译小程序端走 web-view 那条线或者干脆把这块功能从小程序端裁掉。判断清楚这一点能省掉后面一大堆无谓的调试。目标端渲染方式iframe 支持通信方式H5浏览器原生支持window.postMessage/ 直接调函数Appapp-vueWebView多数版本可用非官方承诺window.postMessage/ 同源直调Appnvue原生渲染不支持无小程序双线程不支持用 web-view 替代uni.postMessage/message2. 本地 html 文件放哪、路径怎么写才不在 App 端白屏路径问题是 App 端 iframe 最容易翻车的地方。H5 端你怎么写路径基本都能对一到 App 端就白屏十有八九是路径没找对。核心原因在于App 端打包之后你的项目文件被塞进了一个虚拟的本地目录WebView 加载的是这个虚拟目录里的文件而你写在代码里的路径是相对谁的就需要掰扯清楚。2.1 static 目录的打包去向与 _www 映射关系uni-app 的打包规则是static 目录下的文件会被原样拷贝不参与编译打包。也就是说你把demo.html丢在static/iframe/demo.html打包之后它就会出现在 App 资源目录通常对应_www下的static/iframe/demo.html位置。这一点很关键因为它意味着你的 HTML 不会被打包器处理里面的script、link引用、相对路径都要自己保证正确。反过来说如果你把 HTML 文件放在pages或者别的地方它不会被打包进去运行时就找不到文件。所以第一个铁律所有要内嵌的静态 HTML、它依赖的 css、js、图片全部放 static 目录并且内部引用尽量用相对路径这样一个文件夹整体挪走也不会断链。2.2 H5 与 App 端引用路径的写法差异H5 端最简单src写相对根路径就行iframe src/static/iframe/demo.html/iframeApp 端就麻烦一些。实测比较稳的写法是加条件编译或者在 App 端把本地路径转换成系统能识别的绝对路径// 在 onReady 里处理 // #ifdef APP-PLUS const localPath _www/static/iframe/demo.html const absPath plus.io.convertLocalFileSystemURL(localPath) this.iframeSrc absPath // #endif // #ifdef H5 this.iframeSrc /static/iframe/demo.html // #endifplus.io.convertLocalFileSystemURL是 App 端把虚拟路径转成真实文件系统路径的接口转完之后 iframe 就能找到文件了。我自己的习惯是给 iframe 的 src 绑一个 data 变量在onReady之前不渲染或渲染成空白等路径算好了再赋值这样能避免第一次加载时路径还没准备好导致的 404。2.3 一个实测的白屏排查顺序App 端 iframe 白屏别瞎试按这个顺序排先确认控制台有没有加载错误如果路径不对通常会报找不到资源。检查 HTML 是不是真的在 static 目录里而不是被放到了别的目录。检查 HTML 内部的资源引用是不是用了绝对路径比如/css/style.css在 App 端这种以根开头的路径可能指向的不是你以为的位置改成相对路径试试。检查 HTML 里有没有用到只有浏览器环境才有的 APIApp 端 WebView 环境不完整某些接口可能不存在。最后才怀疑是不是当前 App 版本不兼容 iframe换个最小 Demo 页面验证。我遇到过最离谱的一次是 HTML 里内联了一个base href/H5 端没事App 端直接把所有相对路径解析歪了排查了半天才定位到那一行。所以看到白屏先怀疑路径再怀疑环境。3. 父子页面双向通信postMessage 通道怎么搭页面能显示出来只是第一步真正干活的是通信。父页面uniapp 页面要给 iframe 里的 HTML 传数据HTML 里的操作结果也要回传给父页面这就需要搭一条双向通道。这套机制在 H5 端和 App 端是通用的核心就是window.postMessage加message事件监听两边各干一半。3.1 父传子与子传父的两个方向方向一父页面发给 iframe 里的子页面// 父页面 const iframeEl this.$refs.myIframe // 拿到 iframe 的真实 DOM iframeEl.contentWindow.postMessage( { type: INIT_DATA, payload: { userId: 123 } }, * // 目标源后面细讲 )方向二iframe 里的子页面发给父页面// 子页面demo.html 内部 window.parent.postMessage( { type: FORM_SUBMIT, payload: { name: 张三 } }, * )两个方向都要在接收端挂上监听// 父页面监听子页面来的消息 window.addEventListener(message, (e) { const data e.data if (data data.type FORM_SUBMIT) { // 处理子页面回传的数据 } }) // 子页面监听父页面来的消息 window.addEventListener(message, (e) { const data e.data if (data data.type INIT_DATA) { // 使用父页面传来的数据初始化 } })看起来很简单但通信失败的原因往往不在写法上而在细节上接收端挂了没、targetOrigin 对不对、如果是 App 端 file 协议有没有特殊处理。这几条后面单开一节说。3.2 消息协议别再用裸字符串我见过不少项目两边直接传字符串postMessage(ok)这种能跑但一旦消息种类变多就乱套了。建议一开始就定一个简单的消息协议用对象包一层{ type: INIT_DATA, // 消息类型用于区分业务 payload: { ... }, // 实际数据 id: msg_001, // 可选用于请求-响应配对 timestamp: 1699999999 // 可选方便排查时序问题 }接收端先判断type再决定怎么处理这样做的好处是消息一眼能看懂、方便加日志、后续扩展新消息类型不动老代码。id字段在需要发一条请求、等一条响应的场景特别有用比如你在父页面发了一个请把表单数据给我的消息子页面处理完回一条带同样id的消息父页面就能对上号而不是靠消息顺序去猜。3.3 完整可复制的最小示例把上面的拼起来给一个能直接抄的最小结构。父页面uniapp 的 vue 页面template view classwrap iframe refmyIframe :srciframeSrc frameborder0 stylewidth:100%;height:600px;display:block; loadonIframeLoad /iframe button clicksendToChild给子页面发消息/button /view /template script export default { data() { return { iframeSrc: } }, onReady() { // #ifdef APP-PLUS this.iframeSrc plus.io.convertLocalFileSystemURL(_www/static/iframe/demo.html) // #endif // #ifdef H5 this.iframeSrc /static/iframe/demo.html // #endif window.addEventListener(message, this.onMessage) }, beforeDestroy() { window.removeEventListener(message, this.onMessage) }, methods: { onIframeLoad() { // iframe 加载完成可以安全地发第一条消息了 this.sendToChild() }, sendToChild() { const el this.$refs.myIframe if (el el.contentWindow) { el.contentWindow.postMessage( { type: INIT_DATA, payload: { userId: 123 } }, * ) } }, onMessage(e) { const data e.data if (data data.type FORM_SUBMIT) { console.log(收到子页面数据, data.payload) } } } } /script子页面static/iframe/demo.html!DOCTYPE html html langzh-CN head meta charsetutf-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title内嵌页/title /head body div idapp/div script // 监听父页面来的消息 window.addEventListener(message, function (e) { var data e.data if (data data.type INIT_DATA) { document.getElementById(app).innerText 收到用户ID data.payload.userId } }) // 页面加载后主动告诉父页面我准备好了 window.parent.postMessage({ type: CHILD_READY }, *) // 模拟用户操作后回传数据 function submit() { window.parent.postMessage( { type: FORM_SUBMIT, payload: { name: 张三 } }, * ) } /script /body /html这套结构基本能覆盖大多数场景。抄的时候注意两点父页面onIframeLoad里再发消息这个顺序不能省子页面主动发CHILD_READY这个握手信号也建议加上原因在第五节展开。4. 同源、跨域与 file 协议通信失败最常见的三个原因通信写完了但收不到消息是最让人抓狂的状态因为两端代码看起来都对。绝大多数情况下问题出在源上。postMessage这套机制是围绕源设计的源对不上消息就会被静默丢弃不报错、不提示你只能干瞪眼。4.1 targetOrigin 写错导致消息静默丢弃postMessage(data, targetOrigin)的第二个参数是目标源它规定了只有当接收方的源等于 targetOrigin 时消息才会被投递。上面示例里我都写的*意思是不限制源谁都能收开发阶段方便但生产环境更安全的是写具体源iframeEl.contentWindow.postMessage(data, https://your-domain.com)坑就在这如果 H5 端你的父页面在https://a.comiframe 加载的却是https://b.com的页面你在父页面发消息时把 targetOrigin 写成了https://b.com那是对的但如果写成了自己的域名或者两边域名拼错一个字母消息就石沉大海。排查方法是对接收端的 message 监听打日志看它到底有没有被触发没触发就基本确定是源的问题。4.2 file 协议下 origin 为 null 的特殊处理App 端内嵌本地 HTML 时页面是通过 file 协议或者本地虚拟路径加载的这种情况下页面的 origin 往往是null。这就是为什么在 App 端我强烈建议 targetOrigin 用*——因为你写具体源反而对不上null 这个东西没法拼成合法字符串去匹配。接收端判断时也要注意e.origin可能是null这个字符串或者空别用严格相等去比对具体域名。window.addEventListener(message, (e) { // App 端本地环境 origin 可能是 null不要写死具体域名去卡 if (e.origin ! null e.origin ! https://your-domain.com) { return } // 处理消息 })当然用*是有安全代价的任何页面都能给你发消息。所以如果消息里涉及敏感操作一定要在业务层做校验比如检查消息结构、加一个双方约定的 token别裸信任何发过来的东西。4.3 直接调用对方函数与 postMessage 的取舍如果父页面和 iframe 里的页面是同源的比如都是你自己的域名或者 App 端都在同一个本地环境其实可以走更直接的路径——直接调对方的函数// 父调子同源下可以直接拿到子页面 window 上的方法 this.$refs.myIframe.contentWindow.someMethod(data) // 子调父同源下直接挂在 window 上 window.parent.receiveFromChild(data)同源直调的好处是不用考虑 targetOrigin、消息序列化这些事传对象也没问题postMessage传的数据会被结构化克隆函数、部分特殊对象传不过去。坏处是强耦合而且一旦跨域就不成立。我的经验是开发调试阶段可以用直调快速验证思路正式方案还是走 postMessage因为它对同源/跨域一视同仁将来页面地址变了也不用大改。5. 实测中容易翻车的时序与性能问题通信链路通了不代表就稳了。跑起来之后你会发现真正的妖魔鬼怪都在时序和性能上消息发早了没人接、iframe 高度不对出现滚动条、页面切走了监听器还在、来回切几次内存涨了。这节讲的都是我在真项目里踩过的具体问题。5.1 消息比页面先到ready 握手机制最典型的场景父页面在onReady里就急着给子页面发INIT_DATA结果子页面还没加载完监听器还没挂上消息发出去就丢了。因为postMessage是发出去就不管的没有对方收到了吗的确认。解法就是握手子页面在自身script执行时第一时间发一条CHILD_READY给父页面。父页面收到CHILD_READY之后才发INIT_DATA。这样就能保证数据一定是在子页面准备好之后才发的。如果因为某些原因不方便改子页面那至少要在父页面的loadiframe 加载完成事件回调里再发消息load触发时子页面的 document 已经就绪能接收消息了。5.2 高度自适应与滚动条iframe 默认高度要么是固定的要么是 150px内容一长就出现内部滚动条在移动端体验很难看尤其是在 App 里嵌一层滚动套滚动。两个思路一是父页面给出足够高度让内容不溢出适用于内容高度可预期的场景二是让子页面向父页面报告自己的高度父页面动态设置 iframe 高度。// 子页面里报告高度 const h document.body.scrollHeight window.parent.postMessage({ type: RESIZE, payload: { height: h } }, *) // 父页面收到后改高度 if (data.type RESIZE) { this.iframeHeight data.payload.height }如果要隐藏滚动条iframe 可以加scrollingno或者子页面里设置body { overflow: hidden }。不过要注意强行隐藏滚动条会让内容超出的部分无法查看得配合高度自适应一起用否则就是掩耳盗铃。5.3 组件销毁时的监听器清理父页面的window.addEventListener(message, handler)是挂在 window 上的而 window 是整个应用共享的。如果页面切走了却不移除监听下次这个页面又进来就会挂上第二个监听器消息处理逻辑执行两遍甚至多遍表现出来就是点一次按钮触发了两次。beforeDestroy() { window.removeEventListener(message, this.onMessage) }注意removeEventListener的第二个参数必须和addEventListener时传的是同一个函数引用所以不能写成window.removeEventListener(message, () {})这种匿名函数得把处理函数定义成组件方法或者变量这样才能正确移除。这个细节特别容易被忽略我也在好几个项目里见过因此产生的重复回调。另外如果 iframe 里也往父页面发消息而父页面被销毁了事件可能还在冒泡链上最好在子页面卸载时也做一下清理或者双方约定一个DESTROY消息收到后互相停止。这些清理工作短期看不出效果但在长页面、频繁进出的场景里直接关系到会不会出现内存泄漏。6. iframe 之外的选择web-view 与 renderjs 的适用边界最后聊聊方案选型。iframe 能解决内嵌 HTML 的需求但它不是唯一的办法也不是所有场景的最优解。搞清楚什么时候该用 iframe什么时候该换web-view或者renderjs能帮你在开工前就避开后面的大坑。6.1 什么时候该换 web-view如果你的目标端包含小程序或者你只是要加载一个远端的完整网页那web-view才是正解。它由 uni-app 官方提供三个端的行为相对统一通信接口也是配套设计好的网页端调uni.postMessage页面上监听message接收。代价是web-view在小程序端是全屏的、层级最高你没法在它上面盖别的原生组件排版灵活性不如 iframe。判断标准很简单需要在小程序端跑或者加载的是远端页面用 web-view只在 H5 和 App 端、要嵌的是本地 HTML 且需要和原生界面混排才用 iframe。两者不是谁替代谁的关系是不同场景的不同工具。6.2 renderjs 解决的是另一类问题顺便说一句renderjs很多人把它和 iframe 搞混。renderjs 是 uni-app 提供的一种在 App 端操作视图层 DOM 的技术它解决的问题是在 app-vue 里如何高效地直接操作真实的 DOM而不是如何嵌入另一个页面。它常被用来做高性能的图表、动画、手势库对接。如果你要嵌的是一整页现成的 HTML那用 iframe如果你只是想在当前页面里高效操作某个 DOM 元素那才轮到 renderjs 出场。至于一开始热搜里提到的iframe 隐藏滚动条父页面调用 iframe 函数iframe 里的动态内容这些其实都属于上面几节讨论的范畴滚动条和高度走自适应那条线父调子函数在通信那节动态 iframe 只是说 src 内容动态变化改src之后记得重新走一遍握手流程就行因为新页面是全新的环境老的监听和状态都没了。需求推荐方案备注小程序端加载外部页web-viewiframe 不支持H5/App 嵌本地 HTML 并混排iframe需处理本地路径App 内高效操作 DOMrenderjs不涉及跨页面加载远端整页web-view小程序/ iframeH5、App视目标端而定我个人在实际项目里最大的体会是iframe 方案的稳定性八成取决于你有没有把路径、源、时序这三件事处理好剩下两成才是兼容性。每次新开一个 iframe 需求我都会先在目标真机上跑一个只有父页面发一句话、子页面回一句话的最小 Demo确认这条链路通了再去堆业务逻辑。这个习惯帮我省下来的返工时间比我任何一次优化都值。如果内嵌页后续还要持续迭代强烈建议和负责那个 HTML 的同事约定好消息协议把type定义写成一份双方都能看的文档不然过两个月谁都不记得当初那个ok是干嘛用的了。
