wkhtmltopdf 使用指南：从HTML到PDF的专业转换工具
工具概述
wkhtmltopdf 是一个基于Qt WebKit引擎的开源命令行工具，能够将HTML文档转换为PDF格式。它支持多种HTML特性，包括CSS样式、JavaScript执行以及复杂的页面布局。0.12.6版本采用了经过补丁的Qt引擎，提供了更好的兼容性和功能支持。
基本使用语法
wkhtmltopdf [全局选项]... [对象]... <输出文件>
文档对象类型
wkhtmltopdf支持三种主要的文档对象类型，它们按照命令行中指定的顺序被添加到输出PDF中：
-
页面对象：将单个网页内容添加到PDF中
(page)? <输入URL/文件名> [页面选项]... -
封面对象：添加封面页，不显示在目录中且无页眉页脚
cover <输入URL/文件名> [页面选项]... -
目录对象：在PDF中插入自动生成的目录
toc [目录选项]...
全局选项详解
wkhtmltopdf提供了丰富的全局选项来控制PDF生成的整体行为：
-
页面设置：
--page-size：设置纸张大小（默认为A4）--orientation：设置方向（Portrait或Landscape）--margin-top/bottom/left/right：设置页边距
-
输出控制：
--grayscale：生成灰度PDF--lowquality：生成低质量PDF以减小文件大小--no-pdf-compression：禁用PDF对象无损压缩
-
日志与帮助：
--log-level：设置日志级别（none, error, warn, info）--quiet：静默模式（等同于--log-level none）
页面选项配置
针对每个页面对象，可以设置特定的选项：
-
内容加载控制：
--allow：允许加载指定路径的文件--images/--no-images：控制是否加载图片--javascript-delay：设置JavaScript执行延迟时间（毫秒）
-
页面渲染：
--zoom：设置缩放因子--viewport-size：设置视口大小--background/--no-background：控制是否打印背景
-
安全与权限：
--disable-local-file-access：限制本地文件访问--username/--password：设置HTTP认证凭据
页眉页脚定制
wkhtmltopdf提供了灵活的页眉页脚配置选项：
--header-left "[page]/[topage]" # 左侧显示当前页/总页数
--footer-center "机密文档" # 居中显示页脚文本
--header-line # 在页眉下方添加分隔线
支持以下替换变量：
[page]：当前页码[frompage]：起始页码[webpage]：当前页面URL[date]：系统本地格式日期
目录生成技巧
目录(TOC)生成是wkhtmltopdf的强大功能之一：
--toc-header-text "文档目录" # 设置目录标题
--toc-level-indentation 2em # 设置层级缩进
--xsl-style-sheet custom.xsl # 使用自定义XSLT样式表
可以通过--dump-default-toc-xsl导出默认样式表进行自定义修改。
高级使用技巧
-
批量处理：使用
--read-args-from-stdin从标准输入读取参数，实现批量转换：echo "input1.html output1.pdf" | wkhtmltopdf --read-args-from-stdin -
代理设置：支持多种代理配置格式：
-p "http://user:pass@proxy:8080" -p "socks5://proxy" -
表单处理：使用
--enable-forms将HTML表单转换为PDF可填写表单字段。 -
智能缩放：
--enable-smart-shrinking启用WebKit智能缩放策略，优化内容适应页面。
常见问题解决方案
-
中文显示问题：确保HTML文档指定了正确的编码（如UTF-8），并考虑在CSS中指定中文字体。
-
内容截断：适当调整
--viewport-size和--zoom参数，或检查HTML中的CSS是否限制了宽度。 -
JavaScript执行不完整：增加
--javascript-delay值，给复杂脚本更多执行时间。 -
跨域资源加载：使用
--allow参数明确允许加载外部资源路径。
性能优化建议
- 对于大型文档，考虑禁用图片(
--no-images)或降低图片质量(--image-quality) - 在无GUI环境下运行时，避免使用
--use-xserver选项 - 批量处理时使用
--read-args-from-stdin减少启动开销 - 适当调整
--cache-dir位置以提高重复转换速度
wkhtmltopdf作为一款成熟的HTML转PDF工具，通过合理配置可以满足从简单网页到复杂报表的各种转换需求。掌握其丰富的选项配置能够帮助用户生成更专业、更符合需求的PDF文档。
