网页完整渲染保存工具说明
1. 文件说明
- 脚本文件：
src/test/Test.js
- 使用方式：Tampermonkey 用户脚本
- 主要目标：将当前网页尽可能完整地保存为高清图片，并支持长页面分片导出
该脚本适用于浏览器页面截图场景，重点解决以下问题：
- 自动滚动页面，触发懒加载内容渲染
- 支持 1x 到 4x 的截图清晰度配置
- 支持
PNG 和 WebP 两种导出格式
- 针对超长页面自动分片截图，避免浏览器画布超限
- 自动输出调试日志，便于问题定位
- 自动排除脚本自身的悬浮按钮、配置面板、进度框，避免被截入图片
2. 功能概览
当前脚本具备以下能力：
- 页面加载完成后，在右下角生成“保存网页”悬浮按钮
- 支持快捷键
Ctrl + Shift + S 打开保存流程
- 打开配置面板后可选择清晰度和导出格式
- 保存前自动滚动整页，尽量触发图片懒加载和延迟渲染内容
- 对长页面按分片方式截图并逐个下载
- 页面过长时自动降低缩放倍数，避免浏览器
canvas 超限
- 控制台输出完整日志，便于分析失败原因
3. 安装方式
3.1 前置条件
- 浏览器已安装 Tampermonkey
- 浏览器允许加载脚本
@require 引入的 html2canvas
3.2 安装步骤
- 打开 Tampermonkey 管理面板
- 新建脚本
- 将
src/test/Test.js 的内容完整复制进去
- 保存脚本
- 打开目标网页进行测试
4. 操作说明
4.1 启动方式
可通过以下任一方式启动：
- 点击页面右下角的“保存网页”按钮
- 使用快捷键
Ctrl + Shift + S
4.2 参数选择
启动后会弹出配置面板，可选择：
- 清晰度
- 格式
png：优先保真，图片更清晰，文件更大webp：压缩率更高，文件更小
4.3 保存流程
脚本保存流程如下：
- 展示进度框
- 自动滚动页面到底部，触发懒加载
- 回到页面顶部
- 计算当前页面宽高和安全缩放倍率
- 如页面过长，则自动分片渲染
- 逐片下载截图文件
- 保存完成后关闭进度框
4.4 导出结果
- 普通页面：导出单张图片
- 超长页面：导出多张图片，文件名带
_part1、_part2 等后缀
文件命名规则示例：
【完整网页】_example.com_20260313153045.png
【完整网页】_example.com_20260313153045_part1.png
【完整网页】_example.com_20260313153045_part2.png
5. 日志说明
5.1 日志开关
脚本中默认开启调试日志：
const DEBUG_ENABLED = true;
如果不希望在浏览器控制台打印日志，可改为：
const DEBUG_ENABLED = false;
5.2 日志前缀
所有日志统一以前缀输出：
[page-capture]
5.3 主要日志内容
控制台会输出以下关键日志：
- 开始保存
- 用户取消保存
- 自动滚动加载开始/结束
- 当前截图配置
- 清晰度自动降级告警
- 每个分片的渲染开始/结束
- 文件下载信息
- 保存失败异常信息
5.4 失败排查建议
如果出现保存失败，优先查看浏览器开发者工具 Console：
- 是否存在跨域资源报错
- 是否存在
canvas 尺寸超限
- 是否存在页面节点渲染异常
- 是否存在浏览器下载被拦截
建议同时记录以下信息：
- 失败页面地址
- 页面大概长度
- 选择的清晰度和格式
- 控制台完整报错信息
- 浏览器名称和版本
6. 关键实现说明
6.1 自动滚动加载
脚本会按可视窗口高度递增滚动页面，并在每一步留出短暂延时，用于触发：
- 图片懒加载
- 无限滚动中的局部内容加载
- 某些依赖滚动进入视口才渲染的节点
6.2 分片截图
由于浏览器对 canvas 的最大宽高和总像素数存在限制，脚本不会盲目生成一张超大的整图，而是：
- 先计算页面实际宽高
- 再根据最大画布边长和总面积估算安全缩放倍数
- 必要时自动降低截图倍率
- 将整页拆分为多个分片逐个导出
6.3 自身元素排除
为避免脚本 UI 被截入图片，以下元素在截图时会被忽略：
脚本通过 data-html2canvas-ignore 属性配合 ignoreElements 实现排除。
7. 已知限制
该脚本基于 html2canvas，因此存在一些天然限制，以下场景无法保证完全还原：
- 跨域
iframe
- 部分视频画面
- 浏览器插件注入内容
- 某些使用特殊绘制方式的
canvas
- 强依赖浏览器 GPU 或原生控件的内容
- 某些开启严格跨域策略的图片资源
另外需要注意：
- 若页面是无限加载型站点，滚动到底部可能会持续新增内容，导致截图高度持续变化
- 某些站点会在滚动时动态回收 DOM，可能导致前后区域样式不一致
- 浏览器可能会拦截连续多文件下载，需要手工允许
8. 建议使用方式
为了获得更稳定的截图结果，建议：
- 截图前先等待页面主要内容完全加载
- 对超长页面优先使用
2x 或 3x
- 若下载文件过多，可先缩小清晰度再尝试
- 若页面存在浮动广告、客服按钮等站点自身浮层，可继续扩展“排除元素”逻辑
- 出现失败时先查看控制台日志，不要只看弹窗提示
9. 后续可扩展项
如果后续还需要增强，可以考虑继续增加以下能力：
- 支持 JPEG 导出和图片质量配置
- 支持将多个分片自动拼接为单张超长图
- 支持按 CSS 选择器排除页面元素
- 支持固定等待时间或等待图片资源全部加载
- 支持将日志导出为文本
- 支持截图前自动隐藏指定浮层
10. 维护说明
如果修改 Test.js，建议同步检查以下内容：
- 是否仍能排除脚本自身 UI
- 长页面分片规则是否仍然有效
- 日志是否覆盖关键流程
- 文件命名是否保持一致
- 是否引入新的浏览器兼容性问题
