onepage-pdf

onepage-pdf

从 github.com/xntj-ai/onepage-pdf 引入 作者：张拼拼 · XNTJ，采用 MIT License。详见 LICENSE。

通过无头 Chrome 将 HTML 渲染为一张纵向长 PDF 页面，再用 PyMuPDF 将页面裁剪到实际内容高度。不会预测高度（打印布局不同于屏幕布局），而是在渲染后精确测量。

**要求：**安装了 pymupdf 的 Python，以及本地 Chrome 或 Edge。无需 API token。

工作流

1. 先检查源 HTML

阅读 HTML 并检查以下四项；它们决定是否需要 --extra-css：

1. 响应式断点。 打印媒体查询会按默认纸张宽度（约 741px）求值，而不是按 @page 尺寸。任何 @media (max-width: N) 中 N ≥ 741 的规则都会在打印时触发，并导致桌面布局折叠。对于每条此类规则，编写一个用 !important 锁定桌面端值的覆盖规则（例如 .grid{grid-template-columns:repeat(3,1fr)!important}）。
2. 玻璃拟态。 PDF 输出会静默忽略 backdrop-filter 模糊效果。如果玻璃元素位于复杂背景上，请添加打印回退样式： .glass{backdrop-filter:none!important;background:rgba(255,255,255,.88)!important}。
3. 滚动显示动画。 常见类名模式（fade*、reveal*、animate*、aos）会自动强制显示。其他任何初始值为 opacity:0 的元素都需要显式添加 opacity:1!important 覆盖规则。
4. vh/vw 尺寸。 打印时，视口单位会按页面区域计算，产生约 1% 的偏差；min-height:100vh 的 hero 区块在超大页面上会变成约 187in 高。请用固定 px 值覆盖此类规则。

将所有覆盖规则放入同一个 CSS 文件，并通过 --extra-css 传入。

2. 转换

以下路径均相对于此技能目录。

python scripts/onepage_pdf.py input.html -o output.pdf --width 1280 \
    [--extra-css fixes.css] [--replace subs.json --forbid words.txt]

• --width：匹配页面的设计宽度（取整到 8px；非 8px 的页面尺寸会触发 MediaBox 舍入错误，产生虚假页面）。
• --replace：JSON [["old","new"], ...]，按顺序应用——较长或更具体的字符串应放在前面。用于发布前脱敏。
• --forbid：每行一个词；只要该词仍存在于 HTML 或最终 PDF 文本层中，脚本就会中止。务必与 --replace 配合使用。
• --crop pixel：如果矢量裁剪判断有误（例如装饰元素绘制得比实际内容更高），切换为按栅格行扫描。

脚本会自动处理：超大页面渲染并在溢出时自动重试、内容裁剪（以相同方式重写 MediaBox 和 CropBox，以确保查看器兼容性）、支持 CJK 的输出路径，以及单页断言。

examples/ 中附带了一个示例，可端到端运行：

python scripts/onepage_pdf.py examples/demo.html -o /tmp/demo.pdf \
    --width 1280 --extra-css examples/demo-fixes.css

3. 验证

脚本会打印 OK 1 page, WxHpt。然后：

1. 渲染缩略图并目视检查（布局完整、网格未折叠、背景存在、底部内容未被截断）：

   import pymupdf
   doc = pymupdf.open("output.pdf")
   doc[0].get_pixmap(dpi=40).save("check.png")
   

2. 如果使用了脱敏功能，禁止词检查已针对 PDF 文本运行；仍需抽查渲染图像，确认栅格图中没有敏感内容。
3. 注意脚本警告：高度超过 14400pt 会导致 Acrobat 出错（Chrome、Firefox 和 WeChat 预览正常）；“content nearly fills the bedrock” 表示应检查末尾是否被截断。

故障排除与工作原理

如果输出异常（布局折叠、背景缺失、空白页面、出现虚假的第二页、CJK 字形模糊或缺失），请阅读 references/mechanics.md——其中记录了此工具所依据的 Chrome 打印渲染规则，以及基于 CDP 的替代方案。