1. 先搞明白跨域到底卡在哪了1.1 浏览器的同源策略是道门如果你是个前端早晚会撞上这么一个需求页面里嵌了iframe里面的页面可能是你自己的子应用也可能是第三方服务结果两边要互传数据、同步状态、触发方法。要是同源直接iframe.contentWindow.document拿过来调就完了可一旦跨域浏览器直接给你红牌——报SecurityError连碰都不让你碰。这时候postMessage就是绕开同源限制的官方通道。我第一次接触跨域时心里特别不服气我自己的页面嵌自己的iframe凭什么不让通信后来才明白浏览器把每一个独立的上下文origin当成一个“房间”。同源策略就是房间的墙目的不是恶心开发者而是防止恶意脚本在你不知情的情况下窃取另一个站点页面的数据。同源的定义包括三点协议、域名、端口。只要有一个不同就算跨域。注意一个容易翻车的地方很多人以为端口不同不算跨域其实是算的http://localhost:8080和http://localhost:5173这俩就是完全不同的 origin。本地开发时前端 dev server 默认跑在 5173后端服务跑在 8080iframe一嵌进去几乎必然踩到端口跨域这道坎。跨域的限制并不是单点的而是分了好几个层面DOM 访问限制你尝试读iframe.contentWindow.document直接抛SecurityError存储隔离localStorage、cookie等也按 origin 隔离互相看不见网络请求限制XMLHttpRequest/fetch走 CORS 控制响应对 JS 不可见窗口通信限制window.opener、window.parent之间的跨窗口操作也受限。这里有一个点必须分清不同限制的“解锁方式”不一样。fetch 跨域靠 CORS 响应头页面间通信靠postMessage。CORS 需要服务器配合设置响应头Access-Control-Allow-Origin而postMessage不需要服务器配合它是浏览器内置的、专门给跨窗口、跨 iframe、跨域页面发消息用的 API。把这两件事混为一谈的人后面排查问题时会走很多弯路。1.2 同源判定与“跨域”的几种形态要判断一个页面和它内嵌的iframe是不是同源最直接的方式是在控制台跑一下const currentOrigin window.location.origin; const iframeOrigin new URL(document.getElementById(myFrame).src).origin; console.log(currentOrigin, iframeOrigin);常见的几种跨域形态我列一下你对照着看协议不同https的父页面嵌http的子页面这类还被浏览器标记为混合内容可能直接拦截域名不同a.example.com嵌b.example.com端口不同本地开发最常见localhost:8080嵌localhost:5173子域名不同app.example.com嵌static.example.com也算跨域。子域名不同这种场景以前可以靠document.domain把两边的主域降级成一致来通信但document.domain现在已经被标记为不推荐使用一方面它有安全风险放宽了同源限制另一方面新标准下很多场景已经不再有效。我在新项目里基本不碰它统一用postMessage解决简单又干净。跨域情况下你能做什么、不能做什么边界要记清楚能调用window.postMessage发消息能读iframe.contentWindow.name这种极少数属性以及能读iframe.contentWindow.location的有限信息能通过修改iframe.src给 iframe 导航因为这是用户显式授权的导航行为不能读写 iframe 内页面的 DOM、JS 变量、storage、cookie。了解了这个边界之后再去看postMessage就豁然开朗了它是跨域场景下唯一一个能让两个 window 上下文直接对话的公开通道。2. postMessage 基础先把 API 吃透2.1 postMessage 的三个参数postMessage是谁的方法关键就一句话消息要发给谁就用谁的 window 对象调用它。父页面要发给 iframe就用iframe.contentWindow.postMessage(...)iframe 要发给父页面就用window.parent.postMessage(...)或window.top.postMessage(...)。完整签名是targetWindow.postMessage(message, targetOrigin, [transfer]);三个参数挨个说清楚。message要发送的数据。理论上可以是任意“结构化可克隆”的值比如字符串、对象、数组、Map、Set。注意是结构化克隆算法复制了一份传过去接收端拿到的是副本不是引用在接收端改了不会反向影响发送端。函数、DOM 节点、class 实例不能传会直接抛DataCloneError。这里有个很多人踩过的坑想传一个对象但对象里带着方法、循环引用、Date实例直接传一般没事可如果你自作聪明先JSON.stringify再传Date变字符串、方法被丢弃到对面类型全变了。targetOrigin安全闸门。它指定“只发给指定源的页面”写*表示不管对方是什么源都发送。但强烈建议别上来就*。正确姿势是在父页面嵌入 iframe 时明确写 iframe 的src对应的 originiframe.contentWindow.postMessage(data, https://child.example.com);为什么强调这一点设想一下你的页面嵌了个 iframe如果恶意代码通过某种方式把你的 iframe 的src换成了一个钓鱼页面此时你调postMessage(secret, *)消息就直接发给了钓鱼页面。但如果你写死了targetOrigin浏览器会在发送前检查目标窗口的当前 url origin不匹配就压根不发直接帮你挡住这层风险。一个容易弄反的点targetOrigin匹配的是目标窗口里当前页面的 origin不是它初始src的 origin也不是你自己页面的 origin。如果 iframe 内部做了跳转比如从登录页跳到了业务页发送前务必确认目标页的当前 origin。transfer可转移对象。可选项用于传ArrayBuffer、MessagePort这类对象。转移的意思是原对象在发送端会被“清空/不可再用”数据所有权直接给接收端。这对大二进制数据、音视频帧处理特别有用能避免结构化克隆的拷贝开销。普通业务消息通信基本用不到。2.2 message 事件怎么接接收端只需要在 window 上加一个事件监听window.addEventListener(message, handleMessage); function handleMessage(event) { // 先校验再处理 }handler收到的是一个MessageEvent对象关键字段有这么几个event.data对方发来的数据event.origin发送方的 origin格式是协议://域名:端口这是判断消息到底是谁发的核心依据必须校验event.source发送方 window 对象的引用可以用它来回发消息比如event.source.postMessage(...)event.lastEventId配合MessageChannel用的普通场景忽略。注意这里的监听对象是当前 window不是某个元素。我见过有人写成iframe.addEventListener(message, handler)结果半天收不到消息。message事件是在 window 上派发的不是 iframe 元素。另外一个新手容易忽略的点message事件的监听不区分同源还是跨源哪怕同源 iframe 发的消息也会触发message事件。所以即使业务场景本来就是同源我也建议用postMessage统一封装一层不要直接在父页面里用contentWindow.document去操作子页面 DOM。这样做的维护性好很多后面详细说。3. 实战父页面与 iframe 双向通信3.1 场景A父页面向 iframe 发消息假设我有一个父页面https://parent.example.com内嵌子页面https://child.example.com/report.html。父页面代码大概长这样iframe idchildFrame srchttps://child.example.com/report.html stylewidth:100%;height:600px;/iframe script const childFrame document.getElementById(childFrame); const CHILD_ORIGIN https://child.example.com; function sendToChild(payload) { if (!childFrame.contentWindow) return; childFrame.contentWindow.postMessage({ type: UPDATE_REPORT, payload: payload, requestId: Date.now() }, CHILD_ORIGIN); } /script我在实际项目里给消息加了一个requestId字段。原因很实用iframe 里的请求可能是异步的返回时我需要知道它对应的是哪条请求而且如果 iframe 连续收到多条消息每条回执必须对得上号。postMessage本身不提供“请求-响应”关联机制所以要在业务协议里自己维护消息 ID。这里有一个非常典型的坑iframe 加载时序问题。iframe 的contentWindow在 iframe 加载过程中是存在的但子页面的监听器可能还没注册完成你发的消息就丢了。postMessage的特点是“发出去就不管了”不排队、不重试、不报错。解决办法一般有两个等 iframe 的load事件触发后再发子页面加载完成后主动给父页面发一条ready通知父页面收到ready后才放心往下发。第二种在实际项目中更靠谱。load事件只能说明资源加载完了不能说明子页面的业务代码已经执行到注册监听器那一步。比如子页面是个 Vue 应用要等框架mounted后才注册监听那父页面在load之后立刻发消息一样会丢。所以生产环境我都是用“握手”模式。3.2 场景Biframe 向父页面回传子页面里这样写window.addEventListener(message, (event) { // 安全校验永远放在第一位 if (event.origin ! https://parent.example.com) { console.warn(rejected message from unexpected origin:, event.origin); return; } if (typeof event.data ! object || event.data null) return; if (event.data.type ! UPDATE_REPORT) return; // 处理业务逻辑... const result { code: 0, data: { ok: true } }; // 回发给父页面用 event.origin 作为 targetOrigin event.source.postMessage({ type: UPDATE_REPORT_RESULT, requestId: event.data.requestId, result: result }, event.origin); });这里用event.source回发比自己写window.parent再指定 origin 好处很大万一 iframe 被嵌到了多个不同的父页面下面比如同一个子页面同时服务多个父级代码依然正确。event.origin是“当前这次消息的真实来源”用它做回发的targetOrigin是既安全又动态。有人会问event.source一定等于window.parent吗大部分情况是的但也有例外。比如页面 A 里嵌了 iframe BB 里又嵌了 iframe CC 里的window.parent是 B但 B 如果做了消息转发C 收到的消息event.source可能是 A 的 window。所以不要假设event.source就是window.parent一切以event.source为准。3.3 数据序列化与传输细节前文提到postMessage会做结构化克隆但实际开发中还是有不少“活见鬼”场景传 Date 对象结构化克隆能保持 Date 类型但如果你中间用JSON.stringify包了一层Date 会变成字符串到对面要自己重新new Date()。别问我是怎么踩到的。传 Map/Set结构化克隆支持但老版本浏览器兼容性有坑。保守做法是转成普通数组再传。传 undefinedpostMessage(undefined, *)其实会抛错。一些封装层不做类型检查直接把 undefined 当普通值传结果运行时炸了。循环引用直接传给postMessage结构化克隆是能处理循环引用的不会抛错。但如果你先JSON.stringify循环引用直接抛TypeError。所以我的经验是能用结构化克隆就直接传对象不要没事先 stringify。不过接受端做类型校验永远推荐因为消息经过网络在部分跨域场景其实是同进程传递和不同封装层后类型可能会变。什么场景下需要序列化成 JSON 字符串再传我总结了几种要兼容非常老的浏览器老 IE 对结构化克隆支持不完整消息需要被非浏览器端消费比如 WebView 原生层拦截处理你需要消息跨系统传递中间件JSON 字符串更通用。4. 安全底线不校验 origin 就是在裸奔4.1 每个消息都必须经过三查经常在网上看到 demo 代码监听message后拿到data就直接用也不看origin。演示可以生产环境千万别学。原因不复杂postMessage是公开通道任何能往你这个 window 发消息的窗口包括恶意页面都能触发你的message监听器。如果没有 origin 校验就等于你家门一直开着谁来都能递纸条你还都当真。我总结了一套“三查”原则每次处理消息前必做一查event.origin是否在白名单里二查event.source是否是预期的来源窗口有时候 origin 对但窗口不对比如同源下别的 iframe 也发了消息三查data结构是否合法type、字段、类型都对不上就丢弃。对于第二点什么时候要深入校验source同源多 iframe 场景比较重要。比如页面里有 A、B 两个同源 iframeA 发消息时可能目标明确但 B 也监听了 window 上的 message就需要通过requestId或预存的source引用区分。更严谨的做法是在初始化时存下期望的 source 引用收到消息时逐一比对。4.2 我踩过的安全坑和实战清单整理一份这些年用postMessage的安全清单targetOrigin别写*写具体源。即使对方是你自己家的子应用也建议明确写。多花一秒钟少交一份智商税。接收端校验 origin 白名单不要用includes就完事。比如白名单配了https://example.com却用event.origin.includes(example.com)那https://evil-example.com也能通过。要用new URL(event.origin)拿协议 域名 端口做精确比对。永远不要用event.data直接拼接innerHTML、eval、new Function。即使消息来自可信源也遵循“内容不等于可执行代码”的原则。如果业务上必须要渲染 HTML也要走 HTML 转义或白名单过滤。不要信任event.data里的任何url和path并直接用于重定向或资源加载先做一次 URL 解析校验。敏感操作改密码、支付、删数据不要只靠postMessage一条消息触发最好带上一次性 token或者由父页面弹出确认后走服务端二次校验。另外还有一个很多人忽略的问题消息风暴。如果你的页面监听了message事件然后又通过message事件触发新的postMessage回发编程不小心会形成无限循环——A 给 B 发B 收到后回发A 又收到再发……尤其双方都用event.source回发时特别容易出现“对讲机回声”。我有个项目就出过线上事故一次操作导致两个 iframe 互相发了几万条消息页面直接卡死。从那以后所有消息处理函数都加了去重逻辑记录最近处理过的requestId重复的就丢弃。这个经验在我做过的每一个 iframe 通信项目里都值回票了。5. 常见坑位与排查实录5.1 为什么收不到 message排查postMessage问题我一般按这个顺位来是不是发给了错误的 window 对象父页面要用iframe.contentWindow.postMessage子页面要用window.parent.postMessage或window.top.postMessage顶层窗口就用event.source。这个错了后面一切白搭。监听器是否注册成功子页面代码是否在合适时机执行了addEventListener如果子页面用了框架注意生命周期。我见过 Vue3 项目在setup里注册监听器但因为组件卸载又重建导致监听丢失还要在onUnmounted里清理掉否则会重复注册。是不是消息发太早了子页面还没加载完、还没 ready。targetOrigin 是否写错了写死https://child.example.com但 iframe 实际加载的是http://localhost:3000时消息会被浏览器直接丢弃而且不发任何报错。这就是postMessage的一个特点——静默失败。不发消息也不报错排查要花时间。是不是传了不可序列化的数据比如函数、Symbol或者在某些 WebView 环境里传了原生对象。会抛DataCloneError但有些框架会把异常吞掉表面看不出。有一个非常典型的场景本地开发时父页面是http://localhost:5173iframe 是http://localhost:8080代码里targetOrigin写的是线上域名开发环境就收不到。我建议把目标 origin 做成配置项开发环境从环境变量读取不要硬编码。5.2 iframe 加载时序问题用握手协议解决前面提到过 ready 握手这里展开讲讲。正常的工作流是这样的父页面创建 iframe并挂载 DOMiframe 的src加载子页面脚本执行子页面注册message监听器完成后向父页面发CHILD_READY父页面收到CHILD_READY后再发业务消息。要注意如果 iframe 内部有异步初始化比如调接口、等框架挂载CHILD_READY一定得等所有初始化完成后再发否则还是丢消息。另外子页面如果允许被多个页面嵌入建议在CHILD_READY消息里携带一个iframeId或sessionId用来区分这次 ready 对应的是哪个 iframe 实例。父页面那边维护一个MapiframeId, { ready, pendingQueue }消息来了但还没 ready就先放进pendingQueue等 ready 事件后统一 flush。这套机制虽然简单但很抗造。我实际写过一个简化版本const bridgeState { ready: false, pendingQueue: [], }; function requestToChild(payload) { if (!bridgeState.ready) { bridgeState.pendingQueue.push(payload); return; } childFrame.contentWindow.postMessage(payload, CHILD_ORIGIN); } function onChildReady() { bridgeState.ready true; bridgeState.pendingQueue.forEach(p { childFrame.contentWindow.postMessage(p, CHILD_ORIGIN); }); bridgeState.pendingQueue []; }这个写法的好处是即使子页面初始化很慢业务侧也不用关心时机只管调用requestToChild就行。5.3 与 Vue3 嵌套 iframe 的配合现在不少项目是用 Vue3 做前端框架嵌套 iframe 时有几个注意点。第一iframe 的src不要用响应式变量做频繁变更。每次src变化都会触发 iframe 重新加载子页面会重新走加载流程之前的 ready 状态就失效了。如果业务上有切换需求建议用v-if来控制 iframe 实例的挂载卸载切换时顺便清理监听。第二监听message事件时记得清理。Vue3 的setup里用onMounted注册在onBeforeUnmount里移除否则组件被销毁后监听还挂在 window 上既浪费内存又可能在组件重建后重复处理消息。注意多个 iframe 会同时在同一 window 上监听message所以消息里必须有标识区分来源。第三Vue3 的组件通信习惯是 props / emit / eventBus但跨 iframe 是隔离的不能用这些常规手段。如果你在 Vue3 项目里做父子 iframe 通信最好的方式还是封装一个通信模块统一管理postMessage的发送、接收、路由。我习惯封装一个createIframeBridge(iframe, targetOrigin)函数返回一个 Promise 风格的消息发送接口内部处理 ready 握手和requestId匹配。5.4 动态 iframe加载失败、CSP 拦截与超时处理动态创建的 iframe比如用户点了个按钮才加载报表特别容易踩到加载失败的问题。src指向的资源 404、网络断开、被 CSP 阻挡iframe 一样会存在于 DOM 中但contentWindow可能可以访问你发的消息也没人接。排查办法给 iframe 加onload和onerror监听。但onerror并不能覆盖所有情况比如 404 的页面其实也会触发load所以最靠谱的还是 ready 握手配合超时机制。我的做法是父页面发一个PING子页面 3 秒内没有回PONG就认为加载失败然后提示用户。这个 PING/PONG 机制非常简单但在动态 iframe 场景下特别实用。还有一个高发问题是CSP 拦截。如果父页面配置了Content-Security-Policy其中frame-src或child-src不包含子页面域名iframe 会被浏览器直接拦截。控制台会显示类似 “Refused to frame ... because it violates the following Content Security Policy directive”。看到这种日志直接去查 CSP 配置别在 postMessage 代码里浪费时间。6. 扩展与 iframe 相关的高频场景既然聊到 iframe顺便把几个和它有千丝万缕联系但又容易被混淆的场景一起说清楚省得你遇到时抓瞎。6.1 隐藏滚动条与样式隔离很多人嵌完 iframe 后第一件事就是想去掉丑丑的滚动条。同源的话你可以直接操作iframe.contentDocument里的样式跨域就不行了外部样式管不到 iframe 内部文档的滚动条。跨域情况下能做的有限给 iframe 设置样式overflow: hidden但注意这个方法对 iframe 滚动条未必有效因为滚动条是 iframe 内部文档的外部样式管不到更靠谱的招数是让子页面内部的body/html上设置overflow: hidden由子页面自己处理内容滚动。如果内容确实超高需要滚动可以在子页面容器上用scrollbar-width: noneChrome或::-webkit-scrollbar { display: none }隐藏滚动条。这一点和postMessage的关系在于跨域下你执行不了子页面的样式操作所以必须在子页面里配合实现。这时候可以约定一套消息协议比如父页面发SET_OVERFLOW_HIDDEN子页面收到后设置自己document的样式——这就是postMessage在“跨域样式协调”上的典型用法。6.2 后端跨域 CORS 与 postMessage 的区别经常有入门同学把 CORS 和postMessage搞混。我拿一张简单的对照表说清楚对比项CORSpostMessage面向对象网络请求fetch / XHRwindow 对象之间依赖服务器需要服务器响应头配合不需要服务器配置用途决定“我能不能拿你的数据”决定“我能不能和你说话”绕过方式前端无法绕过只能后端配置浏览器原生支持无配置一句话总结CORS 管的是能不能请求资源postMessage 管的是能不能互发消息。两者方向完全不同。如果你遇到后端跨域配置错误比如Access-Control-Allow-Origin设置成了前端域名但漏了Access-Control-Allow-Credentials: true前端 fetch 会报 CORS 错误这种情况你去找postMessage没有任何用处问题出在服务端响应头。6.3 关于 DataEase 社区版禁止 iframe 嵌入的边界我之前做过一个项目想用 iframe 把 DataEase 的报表嵌入到企业门户里结果发现 DataEase 社区版通过响应头限制了不允许被 iframe 嵌入。这是服务端通过X-Frame-Options或 CSP 的frame-ancestors指令直接拒绝的和跨域postMessage无关。遇到这种“嵌不进去”的情况常规排查思路是看响应头里有没有X-Frame-Options: DENY / SAMEORIGIN或者 CSP 里有没有frame-ancestors指令如果服务端设置了这个限制前端没有任何办法绕过。这是浏览器基于安全策略做的强制限制不能靠前端 hackDataEase 商业版或特定版本可能开放嵌入白名单或者通过它的 API 取数据后自己渲染而不是直接 iframe。这个案例告诉你postMessage只管“嵌进去之后怎么通信”但“能不能嵌进去”是由服务端响应头和浏览器安全策略说了算的。这两件事要分开排查。6.4 主页面可以调用 iframe 里的函数吗这也是高频问题分两种情况同源可以直接iframe.contentWindow.someFunction()或者拿到iframe.contentDocument之后操作 DOM跨域不行直接访问会抛SecurityError。唯一可行的方式就是通过postMessage发送指令iframe 内部监听后调用自己的函数。即使同源我也推荐用postMessage封装一层接口而不是直接暴露内部函数。原因很简单直接暴露函数会让父页面和子页面耦合很深——父页面要知道子页面的内部函数名、参数结构、返回方式子页面一重构就崩。用消息协议可以做到接口稳定子页面内部怎么实现完全自由。我在实际项目里用postMessage做了快 5 年最大的感受是这个 API 本身极简五分钟就能学会难的是把通信双方的组织方式、安全边界和异常处理设计清楚。如果你也正在做类似功能建议先把四件事想明白再动手校验event.origin、管理消息 ID、做好 ready 握手、处理 iframe 生命周期。把这四件事做好了剩下的业务逻辑都只是往这套框架里填代码而已。
1. 先搞明白跨域到底卡在哪了1.1 浏览器的同源策略是道门如果你是个前端早晚会撞上这么一个需求页面里嵌了iframe里面的页面可能是你自己的子应用也可能是第三方服务结果两边要互传数据、同步状态、触发方法。要是同源直接iframe.contentWindow.document拿过来调就完了可一旦跨域浏览器直接给你红牌——报SecurityError连碰都不让你碰。这时候postMessage就是绕开同源限制的官方通道。我第一次接触跨域时心里特别不服气我自己的页面嵌自己的iframe凭什么不让通信后来才明白浏览器把每一个独立的上下文origin当成一个“房间”。同源策略就是房间的墙目的不是恶心开发者而是防止恶意脚本在你不知情的情况下窃取另一个站点页面的数据。同源的定义包括三点协议、域名、端口。只要有一个不同就算跨域。注意一个容易翻车的地方很多人以为端口不同不算跨域其实是算的http://localhost:8080和http://localhost:5173这俩就是完全不同的 origin。本地开发时前端 dev server 默认跑在 5173后端服务跑在 8080iframe一嵌进去几乎必然踩到端口跨域这道坎。跨域的限制并不是单点的而是分了好几个层面DOM 访问限制你尝试读iframe.contentWindow.document直接抛SecurityError存储隔离localStorage、cookie等也按 origin 隔离互相看不见网络请求限制XMLHttpRequest/fetch走 CORS 控制响应对 JS 不可见窗口通信限制window.opener、window.parent之间的跨窗口操作也受限。这里有一个点必须分清不同限制的“解锁方式”不一样。fetch 跨域靠 CORS 响应头页面间通信靠postMessage。CORS 需要服务器配合设置响应头Access-Control-Allow-Origin而postMessage不需要服务器配合它是浏览器内置的、专门给跨窗口、跨 iframe、跨域页面发消息用的 API。把这两件事混为一谈的人后面排查问题时会走很多弯路。1.2 同源判定与“跨域”的几种形态要判断一个页面和它内嵌的iframe是不是同源最直接的方式是在控制台跑一下const currentOrigin window.location.origin; const iframeOrigin new URL(document.getElementById(myFrame).src).origin; console.log(currentOrigin, iframeOrigin);常见的几种跨域形态我列一下你对照着看协议不同https的父页面嵌http的子页面这类还被浏览器标记为混合内容可能直接拦截域名不同a.example.com嵌b.example.com端口不同本地开发最常见localhost:8080嵌localhost:5173子域名不同app.example.com嵌static.example.com也算跨域。子域名不同这种场景以前可以靠document.domain把两边的主域降级成一致来通信但document.domain现在已经被标记为不推荐使用一方面它有安全风险放宽了同源限制另一方面新标准下很多场景已经不再有效。我在新项目里基本不碰它统一用postMessage解决简单又干净。跨域情况下你能做什么、不能做什么边界要记清楚能调用window.postMessage发消息能读iframe.contentWindow.name这种极少数属性以及能读iframe.contentWindow.location的有限信息能通过修改iframe.src给 iframe 导航因为这是用户显式授权的导航行为不能读写 iframe 内页面的 DOM、JS 变量、storage、cookie。了解了这个边界之后再去看postMessage就豁然开朗了它是跨域场景下唯一一个能让两个 window 上下文直接对话的公开通道。2. postMessage 基础先把 API 吃透2.1 postMessage 的三个参数postMessage是谁的方法关键就一句话消息要发给谁就用谁的 window 对象调用它。父页面要发给 iframe就用iframe.contentWindow.postMessage(...)iframe 要发给父页面就用window.parent.postMessage(...)或window.top.postMessage(...)。完整签名是targetWindow.postMessage(message, targetOrigin, [transfer]);三个参数挨个说清楚。message要发送的数据。理论上可以是任意“结构化可克隆”的值比如字符串、对象、数组、Map、Set。注意是结构化克隆算法复制了一份传过去接收端拿到的是副本不是引用在接收端改了不会反向影响发送端。函数、DOM 节点、class 实例不能传会直接抛DataCloneError。这里有个很多人踩过的坑想传一个对象但对象里带着方法、循环引用、Date实例直接传一般没事可如果你自作聪明先JSON.stringify再传Date变字符串、方法被丢弃到对面类型全变了。targetOrigin安全闸门。它指定“只发给指定源的页面”写*表示不管对方是什么源都发送。但强烈建议别上来就*。正确姿势是在父页面嵌入 iframe 时明确写 iframe 的src对应的 originiframe.contentWindow.postMessage(data, https://child.example.com);为什么强调这一点设想一下你的页面嵌了个 iframe如果恶意代码通过某种方式把你的 iframe 的src换成了一个钓鱼页面此时你调postMessage(secret, *)消息就直接发给了钓鱼页面。但如果你写死了targetOrigin浏览器会在发送前检查目标窗口的当前 url origin不匹配就压根不发直接帮你挡住这层风险。一个容易弄反的点targetOrigin匹配的是目标窗口里当前页面的 origin不是它初始src的 origin也不是你自己页面的 origin。如果 iframe 内部做了跳转比如从登录页跳到了业务页发送前务必确认目标页的当前 origin。transfer可转移对象。可选项用于传ArrayBuffer、MessagePort这类对象。转移的意思是原对象在发送端会被“清空/不可再用”数据所有权直接给接收端。这对大二进制数据、音视频帧处理特别有用能避免结构化克隆的拷贝开销。普通业务消息通信基本用不到。2.2 message 事件怎么接接收端只需要在 window 上加一个事件监听window.addEventListener(message, handleMessage); function handleMessage(event) { // 先校验再处理 }handler收到的是一个MessageEvent对象关键字段有这么几个event.data对方发来的数据event.origin发送方的 origin格式是协议://域名:端口这是判断消息到底是谁发的核心依据必须校验event.source发送方 window 对象的引用可以用它来回发消息比如event.source.postMessage(...)event.lastEventId配合MessageChannel用的普通场景忽略。注意这里的监听对象是当前 window不是某个元素。我见过有人写成iframe.addEventListener(message, handler)结果半天收不到消息。message事件是在 window 上派发的不是 iframe 元素。另外一个新手容易忽略的点message事件的监听不区分同源还是跨源哪怕同源 iframe 发的消息也会触发message事件。所以即使业务场景本来就是同源我也建议用postMessage统一封装一层不要直接在父页面里用contentWindow.document去操作子页面 DOM。这样做的维护性好很多后面详细说。3. 实战父页面与 iframe 双向通信3.1 场景A父页面向 iframe 发消息假设我有一个父页面https://parent.example.com内嵌子页面https://child.example.com/report.html。父页面代码大概长这样iframe idchildFrame srchttps://child.example.com/report.html stylewidth:100%;height:600px;/iframe script const childFrame document.getElementById(childFrame); const CHILD_ORIGIN https://child.example.com; function sendToChild(payload) { if (!childFrame.contentWindow) return; childFrame.contentWindow.postMessage({ type: UPDATE_REPORT, payload: payload, requestId: Date.now() }, CHILD_ORIGIN); } /script我在实际项目里给消息加了一个requestId字段。原因很实用iframe 里的请求可能是异步的返回时我需要知道它对应的是哪条请求而且如果 iframe 连续收到多条消息每条回执必须对得上号。postMessage本身不提供“请求-响应”关联机制所以要在业务协议里自己维护消息 ID。这里有一个非常典型的坑iframe 加载时序问题。iframe 的contentWindow在 iframe 加载过程中是存在的但子页面的监听器可能还没注册完成你发的消息就丢了。postMessage的特点是“发出去就不管了”不排队、不重试、不报错。解决办法一般有两个等 iframe 的load事件触发后再发子页面加载完成后主动给父页面发一条ready通知父页面收到ready后才放心往下发。第二种在实际项目中更靠谱。load事件只能说明资源加载完了不能说明子页面的业务代码已经执行到注册监听器那一步。比如子页面是个 Vue 应用要等框架mounted后才注册监听那父页面在load之后立刻发消息一样会丢。所以生产环境我都是用“握手”模式。3.2 场景Biframe 向父页面回传子页面里这样写window.addEventListener(message, (event) { // 安全校验永远放在第一位 if (event.origin ! https://parent.example.com) { console.warn(rejected message from unexpected origin:, event.origin); return; } if (typeof event.data ! object || event.data null) return; if (event.data.type ! UPDATE_REPORT) return; // 处理业务逻辑... const result { code: 0, data: { ok: true } }; // 回发给父页面用 event.origin 作为 targetOrigin event.source.postMessage({ type: UPDATE_REPORT_RESULT, requestId: event.data.requestId, result: result }, event.origin); });这里用event.source回发比自己写window.parent再指定 origin 好处很大万一 iframe 被嵌到了多个不同的父页面下面比如同一个子页面同时服务多个父级代码依然正确。event.origin是“当前这次消息的真实来源”用它做回发的targetOrigin是既安全又动态。有人会问event.source一定等于window.parent吗大部分情况是的但也有例外。比如页面 A 里嵌了 iframe BB 里又嵌了 iframe CC 里的window.parent是 B但 B 如果做了消息转发C 收到的消息event.source可能是 A 的 window。所以不要假设event.source就是window.parent一切以event.source为准。3.3 数据序列化与传输细节前文提到postMessage会做结构化克隆但实际开发中还是有不少“活见鬼”场景传 Date 对象结构化克隆能保持 Date 类型但如果你中间用JSON.stringify包了一层Date 会变成字符串到对面要自己重新new Date()。别问我是怎么踩到的。传 Map/Set结构化克隆支持但老版本浏览器兼容性有坑。保守做法是转成普通数组再传。传 undefinedpostMessage(undefined, *)其实会抛错。一些封装层不做类型检查直接把 undefined 当普通值传结果运行时炸了。循环引用直接传给postMessage结构化克隆是能处理循环引用的不会抛错。但如果你先JSON.stringify循环引用直接抛TypeError。所以我的经验是能用结构化克隆就直接传对象不要没事先 stringify。不过接受端做类型校验永远推荐因为消息经过网络在部分跨域场景其实是同进程传递和不同封装层后类型可能会变。什么场景下需要序列化成 JSON 字符串再传我总结了几种要兼容非常老的浏览器老 IE 对结构化克隆支持不完整消息需要被非浏览器端消费比如 WebView 原生层拦截处理你需要消息跨系统传递中间件JSON 字符串更通用。4. 安全底线不校验 origin 就是在裸奔4.1 每个消息都必须经过三查经常在网上看到 demo 代码监听message后拿到data就直接用也不看origin。演示可以生产环境千万别学。原因不复杂postMessage是公开通道任何能往你这个 window 发消息的窗口包括恶意页面都能触发你的message监听器。如果没有 origin 校验就等于你家门一直开着谁来都能递纸条你还都当真。我总结了一套“三查”原则每次处理消息前必做一查event.origin是否在白名单里二查event.source是否是预期的来源窗口有时候 origin 对但窗口不对比如同源下别的 iframe 也发了消息三查data结构是否合法type、字段、类型都对不上就丢弃。对于第二点什么时候要深入校验source同源多 iframe 场景比较重要。比如页面里有 A、B 两个同源 iframeA 发消息时可能目标明确但 B 也监听了 window 上的 message就需要通过requestId或预存的source引用区分。更严谨的做法是在初始化时存下期望的 source 引用收到消息时逐一比对。4.2 我踩过的安全坑和实战清单整理一份这些年用postMessage的安全清单targetOrigin别写*写具体源。即使对方是你自己家的子应用也建议明确写。多花一秒钟少交一份智商税。接收端校验 origin 白名单不要用includes就完事。比如白名单配了https://example.com却用event.origin.includes(example.com)那https://evil-example.com也能通过。要用new URL(event.origin)拿协议 域名 端口做精确比对。永远不要用event.data直接拼接innerHTML、eval、new Function。即使消息来自可信源也遵循“内容不等于可执行代码”的原则。如果业务上必须要渲染 HTML也要走 HTML 转义或白名单过滤。不要信任event.data里的任何url和path并直接用于重定向或资源加载先做一次 URL 解析校验。敏感操作改密码、支付、删数据不要只靠postMessage一条消息触发最好带上一次性 token或者由父页面弹出确认后走服务端二次校验。另外还有一个很多人忽略的问题消息风暴。如果你的页面监听了message事件然后又通过message事件触发新的postMessage回发编程不小心会形成无限循环——A 给 B 发B 收到后回发A 又收到再发……尤其双方都用event.source回发时特别容易出现“对讲机回声”。我有个项目就出过线上事故一次操作导致两个 iframe 互相发了几万条消息页面直接卡死。从那以后所有消息处理函数都加了去重逻辑记录最近处理过的requestId重复的就丢弃。这个经验在我做过的每一个 iframe 通信项目里都值回票了。5. 常见坑位与排查实录5.1 为什么收不到 message排查postMessage问题我一般按这个顺位来是不是发给了错误的 window 对象父页面要用iframe.contentWindow.postMessage子页面要用window.parent.postMessage或window.top.postMessage顶层窗口就用event.source。这个错了后面一切白搭。监听器是否注册成功子页面代码是否在合适时机执行了addEventListener如果子页面用了框架注意生命周期。我见过 Vue3 项目在setup里注册监听器但因为组件卸载又重建导致监听丢失还要在onUnmounted里清理掉否则会重复注册。是不是消息发太早了子页面还没加载完、还没 ready。targetOrigin 是否写错了写死https://child.example.com但 iframe 实际加载的是http://localhost:3000时消息会被浏览器直接丢弃而且不发任何报错。这就是postMessage的一个特点——静默失败。不发消息也不报错排查要花时间。是不是传了不可序列化的数据比如函数、Symbol或者在某些 WebView 环境里传了原生对象。会抛DataCloneError但有些框架会把异常吞掉表面看不出。有一个非常典型的场景本地开发时父页面是http://localhost:5173iframe 是http://localhost:8080代码里targetOrigin写的是线上域名开发环境就收不到。我建议把目标 origin 做成配置项开发环境从环境变量读取不要硬编码。5.2 iframe 加载时序问题用握手协议解决前面提到过 ready 握手这里展开讲讲。正常的工作流是这样的父页面创建 iframe并挂载 DOMiframe 的src加载子页面脚本执行子页面注册message监听器完成后向父页面发CHILD_READY父页面收到CHILD_READY后再发业务消息。要注意如果 iframe 内部有异步初始化比如调接口、等框架挂载CHILD_READY一定得等所有初始化完成后再发否则还是丢消息。另外子页面如果允许被多个页面嵌入建议在CHILD_READY消息里携带一个iframeId或sessionId用来区分这次 ready 对应的是哪个 iframe 实例。父页面那边维护一个MapiframeId, { ready, pendingQueue }消息来了但还没 ready就先放进pendingQueue等 ready 事件后统一 flush。这套机制虽然简单但很抗造。我实际写过一个简化版本const bridgeState { ready: false, pendingQueue: [], }; function requestToChild(payload) { if (!bridgeState.ready) { bridgeState.pendingQueue.push(payload); return; } childFrame.contentWindow.postMessage(payload, CHILD_ORIGIN); } function onChildReady() { bridgeState.ready true; bridgeState.pendingQueue.forEach(p { childFrame.contentWindow.postMessage(p, CHILD_ORIGIN); }); bridgeState.pendingQueue []; }这个写法的好处是即使子页面初始化很慢业务侧也不用关心时机只管调用requestToChild就行。5.3 与 Vue3 嵌套 iframe 的配合现在不少项目是用 Vue3 做前端框架嵌套 iframe 时有几个注意点。第一iframe 的src不要用响应式变量做频繁变更。每次src变化都会触发 iframe 重新加载子页面会重新走加载流程之前的 ready 状态就失效了。如果业务上有切换需求建议用v-if来控制 iframe 实例的挂载卸载切换时顺便清理监听。第二监听message事件时记得清理。Vue3 的setup里用onMounted注册在onBeforeUnmount里移除否则组件被销毁后监听还挂在 window 上既浪费内存又可能在组件重建后重复处理消息。注意多个 iframe 会同时在同一 window 上监听message所以消息里必须有标识区分来源。第三Vue3 的组件通信习惯是 props / emit / eventBus但跨 iframe 是隔离的不能用这些常规手段。如果你在 Vue3 项目里做父子 iframe 通信最好的方式还是封装一个通信模块统一管理postMessage的发送、接收、路由。我习惯封装一个createIframeBridge(iframe, targetOrigin)函数返回一个 Promise 风格的消息发送接口内部处理 ready 握手和requestId匹配。5.4 动态 iframe加载失败、CSP 拦截与超时处理动态创建的 iframe比如用户点了个按钮才加载报表特别容易踩到加载失败的问题。src指向的资源 404、网络断开、被 CSP 阻挡iframe 一样会存在于 DOM 中但contentWindow可能可以访问你发的消息也没人接。排查办法给 iframe 加onload和onerror监听。但onerror并不能覆盖所有情况比如 404 的页面其实也会触发load所以最靠谱的还是 ready 握手配合超时机制。我的做法是父页面发一个PING子页面 3 秒内没有回PONG就认为加载失败然后提示用户。这个 PING/PONG 机制非常简单但在动态 iframe 场景下特别实用。还有一个高发问题是CSP 拦截。如果父页面配置了Content-Security-Policy其中frame-src或child-src不包含子页面域名iframe 会被浏览器直接拦截。控制台会显示类似 “Refused to frame ... because it violates the following Content Security Policy directive”。看到这种日志直接去查 CSP 配置别在 postMessage 代码里浪费时间。6. 扩展与 iframe 相关的高频场景既然聊到 iframe顺便把几个和它有千丝万缕联系但又容易被混淆的场景一起说清楚省得你遇到时抓瞎。6.1 隐藏滚动条与样式隔离很多人嵌完 iframe 后第一件事就是想去掉丑丑的滚动条。同源的话你可以直接操作iframe.contentDocument里的样式跨域就不行了外部样式管不到 iframe 内部文档的滚动条。跨域情况下能做的有限给 iframe 设置样式overflow: hidden但注意这个方法对 iframe 滚动条未必有效因为滚动条是 iframe 内部文档的外部样式管不到更靠谱的招数是让子页面内部的body/html上设置overflow: hidden由子页面自己处理内容滚动。如果内容确实超高需要滚动可以在子页面容器上用scrollbar-width: noneChrome或::-webkit-scrollbar { display: none }隐藏滚动条。这一点和postMessage的关系在于跨域下你执行不了子页面的样式操作所以必须在子页面里配合实现。这时候可以约定一套消息协议比如父页面发SET_OVERFLOW_HIDDEN子页面收到后设置自己document的样式——这就是postMessage在“跨域样式协调”上的典型用法。6.2 后端跨域 CORS 与 postMessage 的区别经常有入门同学把 CORS 和postMessage搞混。我拿一张简单的对照表说清楚对比项CORSpostMessage面向对象网络请求fetch / XHRwindow 对象之间依赖服务器需要服务器响应头配合不需要服务器配置用途决定“我能不能拿你的数据”决定“我能不能和你说话”绕过方式前端无法绕过只能后端配置浏览器原生支持无配置一句话总结CORS 管的是能不能请求资源postMessage 管的是能不能互发消息。两者方向完全不同。如果你遇到后端跨域配置错误比如Access-Control-Allow-Origin设置成了前端域名但漏了Access-Control-Allow-Credentials: true前端 fetch 会报 CORS 错误这种情况你去找postMessage没有任何用处问题出在服务端响应头。6.3 关于 DataEase 社区版禁止 iframe 嵌入的边界我之前做过一个项目想用 iframe 把 DataEase 的报表嵌入到企业门户里结果发现 DataEase 社区版通过响应头限制了不允许被 iframe 嵌入。这是服务端通过X-Frame-Options或 CSP 的frame-ancestors指令直接拒绝的和跨域postMessage无关。遇到这种“嵌不进去”的情况常规排查思路是看响应头里有没有X-Frame-Options: DENY / SAMEORIGIN或者 CSP 里有没有frame-ancestors指令如果服务端设置了这个限制前端没有任何办法绕过。这是浏览器基于安全策略做的强制限制不能靠前端 hackDataEase 商业版或特定版本可能开放嵌入白名单或者通过它的 API 取数据后自己渲染而不是直接 iframe。这个案例告诉你postMessage只管“嵌进去之后怎么通信”但“能不能嵌进去”是由服务端响应头和浏览器安全策略说了算的。这两件事要分开排查。6.4 主页面可以调用 iframe 里的函数吗这也是高频问题分两种情况同源可以直接iframe.contentWindow.someFunction()或者拿到iframe.contentDocument之后操作 DOM跨域不行直接访问会抛SecurityError。唯一可行的方式就是通过postMessage发送指令iframe 内部监听后调用自己的函数。即使同源我也推荐用postMessage封装一层接口而不是直接暴露内部函数。原因很简单直接暴露函数会让父页面和子页面耦合很深——父页面要知道子页面的内部函数名、参数结构、返回方式子页面一重构就崩。用消息协议可以做到接口稳定子页面内部怎么实现完全自由。我在实际项目里用postMessage做了快 5 年最大的感受是这个 API 本身极简五分钟就能学会难的是把通信双方的组织方式、安全边界和异常处理设计清楚。如果你也正在做类似功能建议先把四件事想明白再动手校验event.origin、管理消息 ID、做好 ready 握手、处理 iframe 生命周期。把这四件事做好了剩下的业务逻辑都只是往这套框架里填代码而已。
