前端无原生截图API，需依赖html2canvas或dom-to-image等库，但二者均存在iframe、伪元素、CSS变量、跨域图片及滚动内容等兼容性问题，且中文文件名下载需encodeURIComponent编码。
网页截图没有“原生一键API”，所谓 HTML DevTools 截图只是开发者工具里的调试功能，不能在业务代码里调用；真要实现前端截图，得靠 html2canvas 或 dom-to-image 这类库，且各有硬伤。
Chrome DevTools 的 screenshot 不是 JS API
你在 Chrome 按 F12 → Ctrl+Shift+P → 输入 Capture screenshot 确实能截当前页，但这是 DevTools 自身能力，和网页 JS 完全隔离。试图在页面脚本里写 chrome.runtime.sendMessage 或 chrome.tabs.captureVisibleTab 会直接报错：Cannot read property 'sendMessage' of undefined。
原因很简单：这些是 Chrome 扩展专用接口，需要声明 "permissions": ["tabs"] 和 "manifest_version": 3，普通网页脚本无权访问。
- 即使你写了 content script 注入页面，也只能截整个 tab 可见区域，无法指定某个
<div id="report">节点 - Firefox / Safari 完全不支持这套机制，跨浏览器方案不存在
- 本地调试时用
--remote-debugging-port=9222发 HTTP 请求调用Page.captureScreenshot是可行的，但仅限你本地启服务、手动发请求，不能用于用户点击“下载截图”按钮的场景
html2canvas 截不到 iframe 和伪元素是设计使然
html2canvas 的本质是遍历 DOM、计算样式、逐元素重绘到 <canvas> 上，它不是屏幕捕获，所以天然不处理 iframe 内容——哪怕同域也会留白或抛出 Failed to execute 'toDataURL' on 'HTMLCanvasElement'。
立即学习“前端免费学习笔记（深入）”；
常见翻车点：
- 页面里嵌了
<iframe src="https://xxx.com/embed">？截图区域直接变空白块 - 用了
::before或::after插入图标/装饰？默认不渲染，加allowTaint: true+useCORS: true也不稳定，尤其在滚动容器内 - 跨域图片（如 CDN 上的头像）没配
Access-Control-Allow-Origin？画布上显示为灰色或黑块，控制台静默失败 - 目标元素有
overflow-y: scroll？只截当前视口，全量内容得自己算scrollHeight、分段渲染再拼接，scale和scrollY参数必须配平，否则错位
dom-to-image 对 CSS 变量和 SVG 滤镜支持很脆弱
dom-to-image 走的是 DOM → SVG → rasterize 路径，理论上比 html2canvas 更准，但它对现代 CSS 特性容忍度更低：
- CSS 自定义属性（
--main-color: #3b82f6）在旧版 Chrome/Safari 中会被忽略，建议构建时编译成固定值，或加color: #3b82f6fallback - SVG 内嵌的
<filter>、<mask>全部丢失，阴影/模糊效果变成 plain box-shadow，没法还原 - 必须同时引入
dom-to-image和FileSaver（提供saveAs），漏一个就报domtoimage is not defined或点击无反应 -
domtoimage.toPng(node)返回 Promise，必须链.then(blob => saveAs(blob, 'xxx.png'))，直接saveAs(domtoimage.toPng(...), ...)会传进去一个 Promise 对象，下载失败
中文文件名下载乱码必须 encodeURIComponent
用 saveAs(blob, '我的截图.png') 在 Windows Chrome 下常变成 ???.png，这不是库的问题，是 Blob URL 的 filename 参数未编码导致的。
正确写法：
const filename = '我的截图.png'; saveAs(blob, encodeURIComponent(filename));
注意：这里不是对整个 URL 编码，只对文件名部分做 encodeURIComponent；如果服务端返回的是 Blob，也要确认响应头含 Content-Disposition: attachment; filename*=UTF-8''%E6%88%91%E7%9A%84%E6%88%AA%E5%9B%BE.png 才真正跨平台安全。
真正难的从来不是“怎么调用函数”，而是判断该用哪个库、哪组参数、以及哪部分 UI 必须提前降级处理——比如把伪元素内容改用真实 DOM 节点，把 iframe 替换为静态占位图，把滚动区域预渲染成一张长图再截。这些取舍，没人替你做。
