最完整wkhtmltopdf教程：从安装到高级PDF生成全攻略-CSDN博客

最完整wkhtmltopdf教程：从安装到高级PDF生成全攻略

【免费下载链接】wkhtmltopdf Convert HTML to PDF using Webkit (QtWebKit) 项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf

你还在为HTML转PDF的格式错乱、中文字体缺失、页眉页脚排版烦恼吗？本文将带你从零基础掌握wkhtmltopdf的全部核心技能，从命令行基础到企业级PDF生成方案，让你1小时内从小白变身PDF处理专家。读完本文你将获得：

3分钟快速安装wkhtmltopdf的跨平台方案
10个高频实用命令模板（附完整参数说明）
页眉页脚动态数据注入技巧
目录生成与样式定制指南
性能优化与常见错误解决方案

什么是wkhtmltopdf？

wkhtmltopdf是一款基于WebKit渲染引擎的命令行工具，能够将HTML文档转换为高质量PDF文件。它运行完全"无头"(headless)模式，不需要图形界面支持，非常适合服务器环境下的批量处理。项目核心代码位于src/pdf/wkhtmltopdf.cc，通过QtWebKit引擎实现HTML到PDF的精准转换。

官方定义：Convert HTML to PDF using Webkit (QtWebKit) - README.md

快速安装指南

Linux系统

# Ubuntu/Debian
sudo apt-get install wkhtmltopdf

# CentOS/RHEL
sudo yum install wkhtmltopdf

# 源码编译（适合需要最新版本）
git clone https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
cd wkhtmltopdf
qmake && make && sudo make install

Windows系统

访问官方下载页面获取安装包
安装时勾选"添加到系统PATH"选项
打开命令提示符验证：wkhtmltopdf --version

macOS系统

# 使用Homebrew
brew install wkhtmltopdf

基础使用方法

最简单的转换命令

wkhtmltopdf https://example.com output.pdf

这个命令会将指定URL的网页转换为PDF文件并保存为output.pdf。你也可以转换本地HTML文件：

wkhtmltopdf input.html output.pdf

常用参数说明

参数	描述	示例
-s, --page-size	设置纸张大小	`--page-size Letter`
-O, --orientation	设置方向(纵向/横向)	`--orientation Landscape`
-B, -T, -L, -R	设置边距(下,上,左,右)	`-B 20mm -L 15mm`
--dpi	设置DPI值	`--dpi 300`
--grayscale	生成灰度PDF	`--grayscale`
-q, --quiet	静默模式，不输出日志	`-q`

完整参数列表可通过wkhtmltopdf --help查看，或参考docs/usage/wkhtmltopdf.txt

高级PDF定制

页眉页脚设置

wkhtmltopdf提供了丰富的页眉页脚定制选项，支持文本、HTML和动态变量：

wkhtmltopdf \
  --header-left "公司机密" \
  --header-center "财务报告" \
  --header-right "Page [page]/[topage]" \
  --footer-left "[date]" \
  --footer-right "[time]" \
  --header-line \
  --footer-line \
  input.html output.pdf

支持的动态变量包括：

[page] - 当前页码
[topage] - 总页数
[date] - 当前日期
[time] - 当前时间
[title] - 页面标题
[webpage] - 网页URL

对于更复杂的页眉页脚，可以使用HTML文件：

wkhtmltopdf --header-html header.html --footer-html footer.html input.html output.pdf

header.html示例：

<!DOCTYPE html>
<html>
<head>
  <style>
    .header { font-size: 10px; text-align: center; width: 100%; }
  </style>
</head>
<body>
  <div class="header">
    <span class="title"></span> - Page <span class="page"></span>/<span class="topage"></span>
  </div>
</body>
</html>

生成目录(TOC)

使用toc参数可以自动生成目录，基于HTML中的h1-h6标签：

wkhtmltopdf toc --toc-depth 3 input.html output.pdf

常用TOC参数：

--toc-depth: 设置目录深度(1-6)
--toc-header-text: 目录标题文本
--toc-level-indentation: 层级缩进
--xsl-style-sheet: 自定义XSL样式表

导出默认XSL样式表用于定制：

wkhtmltopdf --dump-default-toc-xsl > custom.xsl

然后使用自定义样式：

wkhtmltopdf toc --xsl-style-sheet custom.xsl input.html output.pdf

处理中文与特殊字体

解决中文显示问题的关键是确保系统中安装了所需字体，并在HTML中明确指定：

wkhtmltopdf --user-style-sheet style.css input.html output.pdf

style.css内容：

body {
  font-family: "SimSun", "宋体", serif;
}
@font-face {
  font-family: "CustomFont";
  src: url("./fonts/custom.ttf") format("truetype");
}
.title {
  font-family: "CustomFont", sans-serif;
}

批量转换与高级选项

多页面合并

wkhtmltopdf cover cover.html toc chapter1.html chapter2.html output.pdf

延迟加载与JavaScript执行

对于包含动态内容的页面，使用--javascript-delay参数确保脚本执行完成：

wkhtmltopdf --javascript-delay 1000 --enable-javascript dynamic.html output.pdf

自定义页面大小

wkhtmltopdf --page-width 210mm --page-height 297mm input.html output.pdf

禁用图片与背景

wkhtmltopdf --no-images --no-background input.html output.pdf

企业级应用技巧

性能优化策略

使用缓存：通过--cache-dir参数指定缓存目录
```
wkhtmltopdf --cache-dir ./cache input.html output.pdf
```

并行处理：结合xargs实现多进程转换

ls *.html | xargs -n 1 -P 4 wkhtmltopdf {} {}.pdf

低质量模式：快速生成小体积PDF

wkhtmltopdf -l input.html small-output.pdf

错误处理与调试

详细日志：使用--log-level debug获取详细调试信息
JavaScript调试：--debug-javascript输出JS控制台信息
加载错误处理：--load-error-handling ignore忽略资源加载错误

C API集成

对于需要深度集成的应用，可以使用C API进行开发，示例代码位于examples/pdf_c_api.c：

#include <wkhtmltox/pdf.h>

int main() {
    wkhtmltopdf_global_settings * gs;
    wkhtmltopdf_object_settings * os;
    wkhtmltopdf_converter * c;
    
    wkhtmltopdf_init(false);
    gs = wkhtmltopdf_create_global_settings();
    os = wkhtmltopdf_create_object_settings();
    
    wkhtmltopdf_set_global_setting(gs, "out", "output.pdf");
    wkhtmltopdf_set_object_setting(os, "page", "input.html");
    
    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;
}

常见问题解决方案

Q: 生成的PDF中文字体显示乱码怎么办？

A: 确保系统已安装中文字体，并在HTML中明确指定字体族，或通过--user-style-sheet强制设置字体。

Q: 页面内容被截断或分页不正确？

A: 使用CSS的page-break属性控制分页：

.page-break {
  page-break-after: always;
}

Q: 如何添加水印效果？

A: 通过HTML绝对定位元素实现：

.watermark {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  opacity: 0.2;
  font-size: 48px;
  color: #000;
  z-index: 9999;
}

Q: 转换大型HTML文件时内存占用过高？

A: 拆分HTML为多个小文件，分批次转换后合并，或使用--disable-smart-shrinking减少内存使用。

总结与进阶学习

通过本文学习，你已经掌握了wkhtmltopdf从基础到高级的全部核心用法。无论是日常办公还是企业级应用，wkhtmltopdf都能满足你对HTML转PDF的各种需求。

最完整wkhtmltopdf教程：从安装到高级PDF生成全攻略