如何用 wkhtmltopdf 快速将 HTML 转为 PDF？超实用的开源工具指南

如何用 wkhtmltopdf 快速将 HTML 转为 PDF？超实用的开源工具指南

【免费下载链接】wkhtmltopdf项目地址: https://gitcode.com/gh_mirrors/wkh/wkhtmltopdf

wkhtmltopdf 是一款强大的开源工具，能够利用 QT Webkit 渲染引擎将 HTML 页面转换为高质量 PDF 和多种图像格式。它完全"无头"运行，无需显示器或显示服务，是开发者和普通用户处理 HTML 转 PDF 任务的理想选择。

📋 常见问题解决方案：快速上手指南

基础转换：从零开始

将 HTML 文件转换为 PDF 只需一行命令，支持本地文件或网络 URL：

# 转换本地 HTML 文件 wkhtmltopdf input.html output.pdf # 转换网页为图片（支持 png/jpg 等格式） wkhtmltoimage https://example.com screenshot.png

图：wkhtmltopdf 工具的核心功能展示，展示了从 HTML 到高质量 PDF 的转换过程

核心参数速查表

以下参数能解决 90% 的日常转换需求：

参数	功能描述	示例
--page-size A4	设置纸张尺寸	--page-size Letter
--margin-top 20mm	顶部边距	--margin-top 15mm
--orientation Landscape	页面方向	--orientation Portrait
--header-center "报告标题"	添加居中页眉	--header-center "月度报表"
--footer-right "Page [page]/[topage]"	动态页脚	--footer-right "第[page]页"

🚀 进阶应用：专业级 PDF 定制

多文档合并与目录生成

wkhtmltopdf 支持将多个网页合并为一个 PDF，并自动生成目录：

wkhtmltopdf \ cover cover.html \ toc \ page1.html page2.html \ final_document.pdf

自定义样式与高级布局

通过 XSLT 样式表可以完全自定义目录的外观：

# 导出默认 XSLT 模板作为参考 wkhtmltopdf --dump-default-toc-xsl > custom_toc.xsl # 使用自定义样式生成目录 wkhtmltopdf toc --xsl-style-sheet custom_toc.xsl input.html output.pdf

💡 最佳实践：高效工作流建议

批量处理技巧

对于需要处理大量页面的情况，可以使用标准输入参数：

# 创建命令文件 echo "https://doc.qt.io/archives/qt-4.8/qapplication.html qapplication.pdf" >> cmds echo "cover google.com https://en.wikipedia.org/wiki/Qt_(software) qt.pdf" >> cmds # 批量执行转换 wkhtmltopdf --read-args-from-stdin --book < cmds

错误处理与调试

wkhtmltopdf 提供了完善的错误处理机制：

# 启用 JavaScript 调试输出 wkhtmltopdf --debug-javascript input.html output.pdf # 设置日志级别 wkhtmltopdf --log-level warn input.html output.pdf

🔧 开发集成：C API 应用示例

基本转换流程

通过 C API 可以灵活集成到各种应用中：

#include <wkhtmltox/pdf.h> int main() { wkhtmltopdf_init(false); wkhtmltopdf_global_settings * gs = wkhtmltopdf_create_global_settings(); wkhtmltopdf_set_global_setting(gs, "out", "test.pdf"); wkhtmltopdf_object_settings * os = wkhtmltopdf_create_object_settings(); wkhtmltopdf_set_object_setting(os, "page", "http://doc.qt.io/qt-5/qstring.html"); wkhtmltopdf_converter * c = wkhtmltopdf_create_converter(gs); wkhtmltopdf_add_object(c, os, NULL); if (!wkhtmltopdf_convert(c)) fprintf(stderr, "Conversion failed!"); wkhtmltopdf_destroy_converter(c); wkhtmltopdf_deinit(); return 0; }

进度监控与回调处理

void progress_changed(wkhtmltopdf_converter * c, int p) { printf("%3d%%\r",p); fflush(stdout); }

🎯 核心优势总结

无需图形界面：完全 headless 运行，适合服务器环境
高质量渲染：基于 QT Webkit，完美支持 CSS 和 JavaScript
灵活定制：丰富的命令行参数和样式控制选项
开源免费：MIT 许可证，可自由使用和二次开发

通过 wkhtmltopdf，你可以轻松实现从简单网页到复杂文档的高质量 PDF 转换。无论是日常使用还是系统集成，这款工具都能提供稳定可靠的解决方案。

【免费下载链接】wkhtmltopdf项目地址: https://gitcode.com/gh_mirrors/wkh/wkhtmltopdf