这需求听起来简单，真做一次就知道，带 iframe 的页面就像个叠起来的透明抽屉：主页面存好了，抽屉里的内容却不一定跟着走。我最近做资料归档时就撞上了——某个管理后台的详情页嵌套了一个第三方报表，iframe 里的图表和表格怎么也导不出来，直接转 PDF 要么白屏、要么只转出半个页面。折腾了几天，把 mht 和 PDF 两条路线都试了一遍，这里把完整方案和踩过的坑一次性写清楚，适合后面要接“页面归档、报表导出、网页快照”这类需求的朋友直接参考。
1. 先搞清楚卡点在哪：带 Iframe 的页面为什么不能像普通页面一样转
1.1 Iframe 的加载机制和普通页面有本质区别
普通 HTML 页面，浏览器从上往下解析文档，图片、样式、脚本都在同一个文档上下文里。就算资源加载再慢，我们只要等window.load事件或networkidle，整个页面的内容基本就绪了。
但 iframe 是独立的嵌套浏览上下文。子文档有自己独立的DOMContentLoaded、load事件，自己的样式表和脚本有独立的执行环境，主文档的load事件根本不会等 iframe 里的资源加载完。你在主页面里做任何快照操作，都像是“拍了一张全景图，但忘了拉开窗帘”——窗帘后面的内容没人知道有没有渲染完。
这个差异在导出场景里会被无限放大。像我用 Playwright 控制无头浏览器时，如果只await page.goto(url, waitUntil='networkidle')，实际上 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(headless=True) page = await browser.new_page(viewport={"width": 1920, "height": 1080}) await page.goto(url, wait_until="networkidle", timeout=60000) for frame in page.frames: try: await frame.wait_for_load_state("networkidle", timeout=30000) except Exception: continue client = await page.context.new_cdp_session(page) result = await client.send("Page.captureSnapshot", {"format": "mhtml"}) with open(output, "w", encoding="utf-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 通常表现不错：主文档是一个 part，iframe 子文档也会作为另一个 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", boundary=f"----=_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, _subtype=ctype.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 src="https://other-domain/report.php">，脚本就要去抓取那个 cross-origin 文档，并且要在 mht 里给这个子文档建一个 part，再修改主文档里 iframe 的 src 指向 Content-Location。逻辑不难，但遇到跨域资源时：
- 源站如果设置了
X-Frame-Options: DENY或X-Frame-Options: SAMEORIGIN，那你直接在浏览器里看到的就是个拒绝框，拉回来的内容可能是一段错误页面； - 源站如果设置了 CSP
frame-ancestors 'none'，同理； - 源站如果做了 User-Agent 校验、会跳登录、人机验证，拉出来的就根本不是真实内容。
所以手动组装方案只适合“源站自己可控、结构简单、确实没办法用无头浏览器”的特定环境。大多数需求不要绕这条路，直接上无头浏览器的快照接口。
3. PDF 路线：用 Chromium 打印链路，但必须处理三个深坑
3.1 基础打印参数：别上来就 page.pdf()
PDF 转化我用的是 Playwright 调用 Chromium 的打印渲染，核心 API 是page.pdf()，它最终会走 CDP 的Page.printToPDF。最基础的写法是：
await page.pdf( path="output.pdf", format="A4", print_background=True, display_header_footer=False, prefer_css_page_size=True, margin={"top": "0", "bottom": "0", "left": "0", "right": "0"} )这里最容易踩的第一个坑：page.pdf()只能在无头模式下使用。有头模式会直接抛异常。很多调试时喜欢headless=False看渲染效果的人都会在这里懵一下。
第二个坑是format="A4"和prefer_css_page_size=True同时存在时，CSS 里的@page { size: ... }会覆盖 format 参数。如果你的页面本身写死了@page { size: 1421px 2000px }，浏览器会优先用这个尺寸，最终 PDF 的每页尺寸就不一定是 A4。这点不是 bug，但很多人以为设置了 format 就万事大吉，导致打印出来对不上预期。
第三个坑是display_header_footer。默认是 True，会在每页顶部加标题、底部加页码 URL。批量导出几十个页面时，这些链接会显得很杂，所以我在做归档文档时统一设成 False。
3.2 等待 iframe 加载完成的正确姿势
如果 iframe 里的内容已经通过主文档和 iframe 外部脚本触发了请求，直接用wait_until="networkidle"在主文档上等待，经常是无效的。我会写成这样：
await page.goto(url, wait_until="commit", timeout=60000) # 等待主文档稳定 await page.wait_for_load_state("networkidle", timeout=60000) # 重点：遍历所有 frame，逐个确认加载 for frame in page.frames: try: await frame.wait_for_load_state("load", timeout=30000) await frame.wait_for_load_state("networkidle", timeout=30000) except Exception: print(f"frame {frame.url} 加载超时，继续尝试打印") # 最后再额外等一拍 await page.wait_for_timeout(2000)为什么要先wait_until="commit"而不是直接networkidle？因为如果目标页面本身响应很快，但 iframe 里的报表要 20 秒才出数，直接 goto 的 networkidle 可能等的是主文档的 idle，iframe 还没开始拉接口就返回了。用 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，出来的一定是空白或错误提示。
如果目标站点是你自己的服务，解决起来就简单：去掉这个响应头，或者在网关层面对内部预览路径单独放开限制。如果目标站点是第三方且没有权限改响应头，那要趁早给业务方说清楚：这不是工具问题，是目标站的安全策略禁止被嵌入。正确的替代方案是让第三方报表平台提供导出接口，或者在一个独立标签页里打开目标页面再让用户自己按 Ctrl+P。
另一种情况：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打开，页面上临时挂一个自定义尺寸的@page：
@media print { @page { size: 1440px 2000px; margin: 0; } }这样 PDF 出来的页面就不是标准 A4，更像是一张长截图。业务方如果要求笔直白纸排版，这条方案不合适；如果只是要“内容完整”，它比 A4 硬切更容易看清。
另外一个常被忽略的细节是print_background=True。浏览器的默认打印样式会去掉背景色，报表类页面大量使用浅色背景、斑马纹表格，如果漏了这个参数，PDF 里所有底色全都没了，看起来像没渲染完。每次导出我都会带上它。
4. 实测对照：同域、跨域、被拒绝三种场景的产出差异
4.1 三种场景的完整对比
我拿三个测试页面做过一轮对照测试：第一个是同域 iframe 嵌套报表；第二个是跨域但允许嵌入的第三方图表；第三个是响应头里带X-Frame-Options: DENY的页面。
| 场景 | MHT | 说明 | |
|---|---|---|---|
| 同域 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_background=True, format="A4", 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(headless=True, 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_state="cookies.json") await page.goto(url, wait_until="commit", timeout=60000) await page.wait_for_load_state("networkidle", timeout=60000) for frame in page.frames: try: await frame.wait_for_load_state("load", timeout=20000) await frame.wait_for_load_state("networkidle", timeout=20000) except Exception: pass await page.wait_for_timeout(3000) # 输出 PDF await page.pdf( path=f"archives/{tag}.pdf", format="A4", print_background=True, display_header_footer=False, page_ranges="1-50", ) # 输出 MHT cdp = await page.context.new_cdp_session(page) result = await cdp.send("Page.captureSnapshot", {"format": "mhtml"}) with open(f"archives/{tag}.mht", "w", encoding="utf-8") as f: f.write(result["data"]) await browser.close()页面里如果因为触发了登录跳转，最终打出来的 PDF 全是登录表单，这类问题很难从代码层面排查。建议在脚本里加一个简单断言，比如页面标题里出现“登录”字样就抛错。
5.4 如果让我只留一条经验
如果让我只留一条经验给后来人，那就是：不要一开始就在某个工具上死磕，先花 5 分钟确认三件事——目标页面是否允许被嵌入、iframe 是动态加载还是静态内容、输出之后给谁用。这三件事决定了后面所有方案的方向。方向错了，越聪明的脚本只是在用更多代码解决一个本不该存在的需求。
另外最后再分享一个小技巧：批量导出前，先用低分辨率无头浏览器跑通一个样例页面，肉眼检查一下 iframe 区域是否出现内容，再放量。这个动作成本很低，但能拦截掉大部分“白屏”事故。千万别把几千个页面的归档任务一口气丢进去，等跑完才发现整个任务里的 iframe 都没拿到数据，重跑的成本会让人印象深刻。
