proof-html Docker镜像

镜像概述

proof-html是一个基于Headless Chrome的HTML转PDF工具，能够准确渲染现代HTML/CSS并生成高质量PDF文档。该工具特别适合需要从网页或HTML模板生成精确定制PDF的场景，提供了丰富的自定义选项以满足各种文档需求。

核心功能和特性

• 基于Headless Chrome引擎，完整支持现代Web标准
• 准确渲染HTML5、CSS3和JavaScript动态内容
• 支持复杂布局、Flexbox和Grid布局
• 可自定义PDF页面大小、方向和边距
• 支持页眉页脚配置，包含页码等动态内容
• 支持设置PDF元数据（标题、作者、主题等）
• 可从HTML标题自动生成PDF书签
• 轻量级设计，易于集成到自动化工作流

使用场景和适用范围

• 从HTML模板生成业务报告和文档
• 将网页内容保存为高质量PDF档案
• 自动化生成发票、收据等业务文档
• 静态网站内容转换为PDF电子书
• CI/CD流程中自动生成产品文档
• 教育材料和在线内容的PDF版本创建
• 法律和财务文档的电子格式转换

使用方法和配置说明

基本使用方法

最简单的使用方式是将当前目录的HTML文件转换为PDF：

docker run --rm -v $(pwd):/workspace anishathalye/proof-html input.html output.pdf

自定义页面设置

指定页面大小、方向和边距：

docker run --rm -v $(pwd):/workspace anishathalye/proof-html \
  --page-size A4 \
  --orientation portrait \
  --margin-top 2cm \
  --margin-right 2cm \
  --margin-bottom 2cm \
  --margin-left 2cm \
  input.html output.pdf

设置页眉页脚

docker run --rm -v $(pwd):/workspace anishathalye/proof-html \
  --header "报告标题" \
  --footer "第 [page] 页，共 [total] 页" \
  input.html output.pdf

设置PDF元数据

docker run --rm -v $(pwd):/workspace anishathalye/proof-html \
  --title "年度财务报告" \
  --author "财务部门" \
  --subject "2023年度财务总结" \
  --keywords "财务,报告,2023,年度总结" \
  report.html report.pdf

Docker Compose 配置示例

创建docker-compose.yml文件：

version: '3'
services:
  pdf-generator:
    image: anishathalye/proof-html
    volumes:
      - ./html:/workspace/html
      - ./pdf:/workspace/pdf
    command: ["--page-size", "Letter", "--margin-top", "1in", "html/report.html", "pdf/report.pdf"]

运行服务：

docker-compose run --rm pdf-generator

配置参数详解

高级用法示例

从URL生成PDF

直接从网页URL生成PDF：

docker run --rm -v $(pwd):/workspace anishathalye/proof-html \
  [***] documentation.pdf

处理动态内容

对于包含大量JavaScript或异步加载内容的页面，使用延迟参数确保内容完全加载：

docker run --rm -v $(pwd):/workspace anishathalye/proof-html \
  --delay 5000 \
  --page-size Letter \
  dynamic-content.html report.pdf

生成带书签的PDF

从HTML标题自动生成PDF书签：

docker run --rm -v $(pwd):/workspace anishathalye/proof-html \
  --bookmarks \
  --title "产品手册" \
  --author "技术文档团队" \
  manual.html product-manual.pdf

注意事项

• 确保挂载目录有适当的读写权限，避免权限错误
• 对于复杂或大型HTML文件，转换可能需要较长时间
• 某些Web字体可能需要在HTML中显式加载或使用@font-face定义
• 使用print媒体查询可以为PDF输出定义特定样式
• 本地HTML文件应使用相对路径引用外部资源，或确保资源可通过网络访问

/* 示例：PDF专用样式 */
@media print {
  .no-print {
    display: none !important;
  }
  
  body {
    font-size: 12pt;
    line-height: 1.5;
  }
}