★ FEATURED ARTICLE 这需求听起来简单真做一次就知道带 iframe 的页面就像个叠起来的透明抽屉主页面存好了抽屉里的内容却不一定跟着走。我最近做资料归档时就撞上了——某个管理后台的详情页嵌套了一个第三方报表iframe 里的图表和表格怎么也导不出来直接转 PDF 要么白屏、要么只转出半个页面。折腾了几天把 mht 和 PDF 两条路线都试了一遍这里把完整方案和踩过的坑一次性写清楚适合后面要接“页面归档、报表导出、网页快照”这类需求的朋友直接参考。1. 先搞清楚卡点在哪带 Iframe 的页面为什么不能像普通页面一样转1.1 Iframe 的加载机制和普通页面有本质区别普通 HTML 页面浏览器从上往下解析文档图片、样式、脚本都在同一个文档上下文里。就算资源加载再慢我们只要等window.load事件或networkidle整个页面的内容基本就绪了。但 iframe 是独立的嵌套浏览上下文。子文档有自己独立的DOMContentLoaded、load事件自己的样式表和脚本有独立的执行环境主文档的load事件根本不会等 iframe 里的资源加载完。你在主页面里做任何快照操作都像是“拍了一张全景图但忘了拉开窗帘”——窗帘后面的内容没人知道有没有渲染完。这个差异在导出场景里会被无限放大。像我用 Playwright 控制无头浏览器时如果只await page.goto(url, waitUntilnetworkidle)实际上 networkidle 是对主文档可见的请求而言iframe 内部的接口可能在主文档稳定之后才开始请求尤其是懒加载的报表。所以带 iframe 的页面第一步不是选工具而是确认“iframe 里的内容到底加载到了什么程度”。1.2 MHT 和 PDF 的格式逻辑完全不同很多人把 mht 和 PDF 混着选实际上这俩不是一个维度的东西。MHT 是 MIME HTML 封装本质是一封“邮件”格式的容器把主 HTML、图片、CSS、iframe 子文档等所有资源用multipart/related打包成一个文件。它的特点是文件打开后还保留原来的 HTML 结构、脚本、链接关系浏览器或支持 MHT 的阅读器可以按原样展示。适合做“网页快照”方便后续检索和重新编辑。PDF 是渲染结果转出去就变成一张一张的纸字体、排版都固定了适合传给不看技术的人使用、打印、盖章归档。它关注的是“看到的画面是不是完整”不关心底层 HTML 结构。明白这个差异之后选型就简单了要还原、要可编辑走 mht要交付、要打印走 PDF。下面两条路线分开讲。2. MHT 路线优先用无头浏览器的快照接口自己拼 MIME 是最后手段2.1 用 Chrome DevTools 协议的 captureSnapshot 直接拿 MHT现在新版浏览器界面上的“另存为”基本砍掉了网页单一文件格式的入口菜单里只剩“网页全部”和“网页仅 HTML”。如果是纯手工操作想拿 mht 还得靠扩展但自动化脚本里完全可以直接调用 CDP 接口。CDP 里有一个叫Page.captureSnapshot的接口指定format: mhtml就能把当前页面包括所有子框架的资源打包成一个 mht 字符串返回。我用的 Playwright 可以直接通过 CDPSession 调用const { chromium } require(playwright); (async () { const browser await chromium.launch({ headless: true }); const page await browser.newPage({ viewport: { width: 1920, height: 1080 } }); await page.goto(https://your-target-page.com, { waitUntil: networkidle, timeout: 60000 }); // 额外等待 iframe 内容完成 const frames page.frames(); await Promise.all(frames.map(f f.waitForLoadState(networkidle, { timeout: 30000 }).catch(() {}))); const cdp await page.context().newCDPSession(page); const { data } await cdp.send(Page.captureSnapshot, { format: mhtml }); const fs require(fs); fs.writeFileSync(output.mht, data); await browser.close(); })();关键点在于Promise.all(frames.map(...))。这个接口虽然会把 iframe 的子文档一起打进 mht但前提是那个子文档已经完成加载。如果你在页面刚进入就调用快照iframe 区域大概率拿到的是一块空白或 Loading 占位符。用f.waitForLoadState(networkidle)会有个意外情况如果 iframe 里有轮询请求、长连接或一直转圈的图标networkidle 可能永远等不到。所以我在 Promise.all 外面套了.catch(() {})和 30 秒超时宁可画面多等几秒也不能卡死整个任务。Python 版本写法也差不多import asyncio from playwright.async_api import async_playwright async def capture_mht(url: str, output: str): async with async_playwright() as p: browser await p.chromium.launch(headlessTrue) page await browser.new_page(viewport{width: 1920, height: 1080}) await page.goto(url, wait_untilnetworkidle, timeout60000) for frame in page.frames: try: await frame.wait_for_load_state(networkidle, timeout30000) except Exception: continue client await page.context.new_cdp_session(page) result await client.send(Page.captureSnapshot, {format: mhtml}) with open(output, w, encodingutf-8) as f: f.write(result[data]) await browser.close() asyncio.run(capture_mht(https://your-target-page.com, output.mht))2.2 嵌套 Iframe 在 MHT 里的实际表现用captureSnapshot打出来的 mht对单层 iframe 通常表现不错主文档是一个 partiframe 子文档也会作为另一个 part 被打包并且通过 Content-Location 和主文档里的 src 关联。但嵌套多层 iframe 时要注意某些阅读器打开 mht 后二级、三级 iframe 会出现空白。这不是打包失败而是 MHT 规范里对 iframe 这种嵌套浏览上下文的关联映射各浏览器实现并不统一。国内文档归档场景下最稳妥的做法是打包完成后自己抽查一下用浏览器打开生成的 mht确认报表区域有内容。如果发现嵌套层级的内容丢失我会直接改策略在打包前用脚本把深层 iframe 的srcdoc替换成已拉取到的子文档全文让页面在快照时刻变成一个“单层结构”。这个操作如果跨域是做不了的所以更多是应急手段后面讲 PDF 时还有更好的思路。2.3 完全没有条件用无头浏览器时手动组装 MIME 的底线方案自动化的无头浏览器是首选但有些生产环境安装不了浏览器、或者目标系统在内网隔离区没法跑 Playwright。这时候只能自己写脚本组装 MHT。MHT 的构造原理说穿了很简单先声明MIME-Version: 1.0再声明Content-Type: multipart/related给出一个 boundary 字符串然后每个资源是一段 part每个 part 带上 Content-Type 和 Content-Location。Python 结合 requests 和 BeautifulSoup 可以写一个简化版import requests from bs4 import BeautifulSoup from email.mime.multipart import MIMEMultipart from email.mime.text import MIMEText from email.mime.image import MIMEImage import uuid URL https://your-target-page.com s requests.Session() resp s.get(URL) resp.encoding resp.apparent_encoding html resp.text soup BeautifulSoup(html, html.parser) multipart MIMEMultipart(related, boundaryf----_NextPart_{uuid.uuid4().hex}) multipart[Content-Location] URL # 主 HTML part html_part MIMEText(str(soup), html, utf-8) html_part[Content-Location] URL multipart.attach(html_part) # 提取和下载图片、CSS 等资源简化处理只处理静态资源 for img in soup.find_all(img): src img.get(src) if not src or src.startswith(data:): continue abs_url requests.compat.urljoin(URL, src) content s.get(abs_url).content ctype image/png if abs_url.endswith(.png) else image/jpeg part MIMEImage(content, _subtypectype.split(/)[1]) part[Content-Location] abs_url part[Content-Transfer-Encoding] base64 multipart.attach(part) img[src] abs_url with open(manual.mht, wb) as f: f.write(multipart.as_string().encode(utf-8))这样写的最大问题是 iframe。如果页面里有个iframe srchttps://other-domain/report.php脚本就要去抓取那个 cross-origin 文档并且要在 mht 里给这个子文档建一个 part再修改主文档里 iframe 的 src 指向 Content-Location。逻辑不难但遇到跨域资源时源站如果设置了X-Frame-Options: DENY或X-Frame-Options: SAMEORIGIN那你直接在浏览器里看到的就是个拒绝框拉回来的内容可能是一段错误页面源站如果设置了 CSPframe-ancestors none同理源站如果做了 User-Agent 校验、会跳登录、人机验证拉出来的就根本不是真实内容。所以手动组装方案只适合“源站自己可控、结构简单、确实没办法用无头浏览器”的特定环境。大多数需求不要绕这条路直接上无头浏览器的快照接口。3. PDF 路线用 Chromium 打印链路但必须处理三个深坑3.1 基础打印参数别上来就 page.pdf()PDF 转化我用的是 Playwright 调用 Chromium 的打印渲染核心 API 是page.pdf()它最终会走 CDP 的Page.printToPDF。最基础的写法是await page.pdf( pathoutput.pdf, formatA4, print_backgroundTrue, display_header_footerFalse, prefer_css_page_sizeTrue, margin{top: 0, bottom: 0, left: 0, right: 0} )这里最容易踩的第一个坑page.pdf()只能在无头模式下使用。有头模式会直接抛异常。很多调试时喜欢headlessFalse看渲染效果的人都会在这里懵一下。第二个坑是formatA4和prefer_css_page_sizeTrue同时存在时CSS 里的page { size: ... }会覆盖 format 参数。如果你的页面本身写死了page { size: 1421px 2000px }浏览器会优先用这个尺寸最终 PDF 的每页尺寸就不一定是 A4。这点不是 bug但很多人以为设置了 format 就万事大吉导致打印出来对不上预期。第三个坑是display_header_footer。默认是 True会在每页顶部加标题、底部加页码 URL。批量导出几十个页面时这些链接会显得很杂所以我在做归档文档时统一设成 False。3.2 等待 iframe 加载完成的正确姿势如果 iframe 里的内容已经通过主文档和 iframe 外部脚本触发了请求直接用wait_untilnetworkidle在主文档上等待经常是无效的。我会写成这样await page.goto(url, wait_untilcommit, timeout60000) # 等待主文档稳定 await page.wait_for_load_state(networkidle, timeout60000) # 重点遍历所有 frame逐个确认加载 for frame in page.frames: try: await frame.wait_for_load_state(load, timeout30000) await frame.wait_for_load_state(networkidle, timeout30000) except Exception: print(fframe {frame.url} 加载超时继续尝试打印) # 最后再额外等一拍 await page.wait_for_timeout(2000)为什么要先wait_untilcommit而不是直接networkidle因为如果目标页面本身响应很快但 iframe 里的报表要 20 秒才出数直接 goto 的 networkidle 可能等的是主文档的 idleiframe 还没开始拉接口就返回了。用 commit 先把文档建立起来再做二次等待能稳住时序。如果你知道 iframe 里具体有接口请求更稳的做法是在打印前反复断言某个可见元素比如“等待 iframe 内部出现 id 为report_total的元素”。但跨域 iframe 的 DOM 是访问不了的能用的手段就少了很多。我会在内网同域场景下用元素的wait_for在跨域场景下用时间兜底。3.3 跨域 iframe、X-Frame-Options 和 CSP 的深坑这是整个需求里最容易翻车的部分。一个第三方页面能不能被嵌进 iframe不是你在代码里怎么拼的问题而是对方的响应头说了算。在动手转换之前先用命令探一下对方源站的响应头curl -sI https://other-domain/report.php | grep -iE X-Frame-Options|Content-Security-Policy看到X-Frame-Options: DENY说明这个页面在浏览器里无论如何也是嵌不进来的正常渲染状态就是空白。看到Content-Security-Policy: frame-ancestors self意思也是只允许同源页面嵌套。这两种情况你去打印 PDF出来的一定是空白或错误提示。如果目标站点是你自己的服务解决起来就简单去掉这个响应头或者在网关层面对内部预览路径单独放开限制。如果目标站点是第三方且没有权限改响应头那要趁早给业务方说清楚这不是工具问题是目标站的安全策略禁止被嵌入。正确的替代方案是让第三方报表平台提供导出接口或者在一个独立标签页里打开目标页面再让用户自己按 CtrlP。另一种情况iframe 本身能嵌进来但内容是跨域的。此时 Playwright 可以拿到frame对象但访问frame.content()或frame.locator(...)会受限。打印前我只能在主文档层面控制 iframe 标签的尺寸没法深入内部改样式。比如一个报表在内部是 1600px 宽的但 iframe 被固定成 900px 宽打印出来就会把右边截掉。这种场景我会退而求其次在主文档里用 JS 动态把 iframe 的宽度撑开能不能撑开取决于 iframe 有没有自身宽度限制。下面的代码在 PDF 打印前执行可以把大多数固定宽度的 iframe 先膨胀到内容实际宽度await page.evaluate(() { document.querySelectorAll(iframe).forEach(ifr { const el ifr; // 通过父页面可以修改 iframe 外层标签的宽高 el.style.width 1920px; el.style.minWidth 1000px; el.style.height 1200px; }); });但要注意如果 iframe 内容内部还有滚动条核心报表区域可能在视觉上被滚动条切走。更彻底的做法是在服务端直接用抓取后的完整 HTML 重新拼一个无 iframe 的页面再打印前提是目标站点的接口 CORS 允许你服务端去拉取。3.4 分页、样式和长截图的取舍打印 PDF 时iframe 如果比一页纸高会被 Chromium 的打印分页逻辑硬生生切断。明明在网页上滚动没问题转出来却总是“图表被腰斩”就是这个原因。解决分页问题有两条路第一调整打印样式在页面主文档里临时注入一段 CSS* { -webkit-print-color-adjust: exact !important; print-color-adjust: exact !important; } html, body { height: auto !important; overflow: visible !important; } iframe { page-break-inside: avoid !important; break-inside: avoid !important; }page-break-inside: avoid能让 iframe 整体搬去下一页避免被截断在中间。但就算搬页如果 iframe 本身就比 A4 纸高还是会被切成多页只是切口位置对齐到了 iframe 的边界比默认的乱切好看很多。第二提前把 iframe 按内容高度撑开然后打印时不要用固定 A4而是让 PDF 跟着页面高度走。比如把prefer_css_page_size打开页面上临时挂一个自定义尺寸的pagemedia print { page { size: 1440px 2000px; margin: 0; } }这样 PDF 出来的页面就不是标准 A4更像是一张长截图。业务方如果要求笔直白纸排版这条方案不合适如果只是要“内容完整”它比 A4 硬切更容易看清。另外一个常被忽略的细节是print_backgroundTrue。浏览器的默认打印样式会去掉背景色报表类页面大量使用浅色背景、斑马纹表格如果漏了这个参数PDF 里所有底色全都没了看起来像没渲染完。每次导出我都会带上它。4. 实测对照同域、跨域、被拒绝三种场景的产出差异4.1 三种场景的完整对比我拿三个测试页面做过一轮对照测试第一个是同域 iframe 嵌套报表第二个是跨域但允许嵌入的第三方图表第三个是响应头里带X-Frame-Options: DENY的页面。场景MHTPDF说明同域 iframe正常子文档内容完整正常打印后 iframe 内容完整最好处理等待标准加载事件即可跨域但允许嵌入大部分正常嵌套层级深时偶发空白基本正常但宽度溢出时会被截断需要额外设置 iframe 尺寸和等待时间响应头禁止嵌入生成的文件里 iframe 区域只有错误页或空白生成 PDF 里对应区域空白必须从源头解决工具无法绕过4.2 从一个实际 Case 看完整的处理链路完整的处理链路我以“跨域但允许嵌入”的 case 为例把参数和判断步骤串一遍。假设目标页面https://report.internal.example/main/view里面嵌了https://chart.internal.example/embed/monthly。我先 curl 头部确认没有 X-Frame-Options 和 CSP 限制然后用 Playwright 打开主文档遍历page.frames找到 URL 包含chart.internal的 frame对它做wait_for_load_state(networkidle)接着在主文档 evaluate 里把 iframe 的宽度拉到 1920px高度先设成 1500px最后等 3 秒执行page.pdf(path..., print_backgroundTrue, formatA4, margin...)。这个流程跑下来的结果里iframe 内容能出来但它的顶部和底部如果超过 1500px 还是会被截断。这里我通常再加一个轮询判断在主文档里读取 iframe 的scrollHeight但这是跨域 iframe父页面读不到内部高度解决办法是在嵌入方页面里由业务方提供一个回调 API或者在主文档把 iframe height 设大到一个足够覆盖内层报表的固定值。这个“足够大”的值没有统一标准只能靠实测不同报表后沉淀一个经验值表。4.3 对于被拒绝嵌入的页面我建议的兜底路线遇到被拒绝嵌入的页面说实话任何工具都救不了。这时候我会先做接口探测看目标站点有没有开放导出接口有就对接接口拿数据文件没有就让使用者自己在浏览器里打开原页面用系统的打印功能保存 PDF。不要硬扛。如果你控制着目标站点的网关可以在内网环境里去掉该响应头但要注意这等于放宽了点击劫持防护需评估内部系统的安全要求是否允许。很多时候这种响应头是安全基线的强制要求随意去掉可能在合规上有麻烦这也是为什么我更倾向于让业务方在独立窗口导出。5. 我的选型建议和一套能直接用的参数集5.1 什么时候该无脑选 PDF如果你的需求是“给业务看”“发送给外部客户”“打印归档”直接选 PDF。这类交付物不需要保留原本的 DOM 结构只看画面是否清晰完整。PDF 的兼容性几乎无敌手机、Windows、macOS 都能打开不像 mht 在很多环境的默认浏览器里打不开。代价是要花心思控制分页、等待 iframe、处理跨域样式打印前还要做一轮可能持续几十秒的等待任务并发多的时候资源消耗比较大。5.2 什么时候值得坚持选 MHT如果你的需求是“把网页原样存下来之后还能还原、检索、再次编辑”MHT 是更合理的方向。MHT 保留了原始页面结构、脚本和资源关联相当于把整个网页连同它的子框架都冻结在一个文件里。配合captureSnapshot生成很快而且不需要调分页和 CSS 打印样式。MHT 的短板是兼容性新版浏览器大多不原生渲染 mht需要用支持该格式的阅读器或插件。所以交付前一定要确认接收方用什么工具打开。5.3 我最终沉淀的一套参数集我在项目里同时跑两套脚本输入是 URL输出目录下同时生成 mht 和 PDF# 这段代码是一个实际使用的最小框架生产环境可在这个基础上加 DB 记录和重试 async def archive(url: str, tag: str default): async with async_playwright() as p: browser await p.chromium.launch(headlessTrue, args[ --disable-gpu, --no-sandbox, --disable-dev-shm-usage, ]) page await browser.new_page(viewport{width: 1920, height: 1080}) # 登录态优先很多内网页面必须带 cookie context await browser.new_context(storage_statecookies.json) await page.goto(url, wait_untilcommit, timeout60000) await page.wait_for_load_state(networkidle, timeout60000) for frame in page.frames: try: await frame.wait_for_load_state(load, timeout20000) await frame.wait_for_load_state(networkidle, timeout20000) except Exception: pass await page.wait_for_timeout(3000) # 输出 PDF await page.pdf( pathfarchives/{tag}.pdf, formatA4, print_backgroundTrue, display_header_footerFalse, page_ranges1-50, ) # 输出 MHT cdp await page.context.new_cdp_session(page) result await cdp.send(Page.captureSnapshot, {format: mhtml}) with open(farchives/{tag}.mht, w, encodingutf-8) as f: f.write(result[data]) await browser.close()页面里如果因为触发了登录跳转最终打出来的 PDF 全是登录表单这类问题很难从代码层面排查。建议在脚本里加一个简单断言比如页面标题里出现“登录”字样就抛错。5.4 如果让我只留一条经验如果让我只留一条经验给后来人那就是不要一开始就在某个工具上死磕先花 5 分钟确认三件事——目标页面是否允许被嵌入、iframe 是动态加载还是静态内容、输出之后给谁用。这三件事决定了后面所有方案的方向。方向错了越聪明的脚本只是在用更多代码解决一个本不该存在的需求。另外最后再分享一个小技巧批量导出前先用低分辨率无头浏览器跑通一个样例页面肉眼检查一下 iframe 区域是否出现内容再放量。这个动作成本很低但能拦截掉大部分“白屏”事故。千万别把几千个页面的归档任务一口气丢进去等跑完才发现整个任务里的 iframe 都没拿到数据重跑的成本会让人印象深刻。
阅读完成 · 觉得有帮助？
