wkhtmltopdf HTML转PDF 实战指南：从 HTML 文件到成品 PDF
【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
wkhtmltopdf 是一款基于 QT Webkit 渲染引擎的无头命令行工具，用于把 HTML 转 PDF，不需要任何显示界面。本文覆盖安装、单页转换、页面参数、页眉页脚和批量处理，看完可以直接跑通并自行处理常见报错。
项目速览
wkhtmltopdf 用 QT Webkit 引擎把 HTML 渲染成 PDF，配套的wkhtmltoimage还能输出图片，全程 headless 运行。功能边界：支持 HTML/CSS、页眉页脚、目录和 PDF 书签；底层是 2016 年前后的 Webkit，依赖非常新的 CSS 特性的页面可能渲染不一致。适合固定版式的报表、文档转换、CI 批量出件，不适合要求最新浏览器引擎的场景。
官方说明：README.md
最短上手路径
从官方发布页下载与你发行版对应的wkhtmltox二进制包（对照表见 docs/downloads.md），装上后验证，直接贴命令就行：
# Debian/Ubuntu 22.04 示例，替换成你发行版的文件名 sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb sudo apt-get install -f wkhtmltopdf --version # 输出 0.12.6 即安装成功核心操作：常见 HTML 转 PDF 场景
转换单页
wkhtmltopdf input.html output.pdf # 第一个参数是输入，最后一个是输出输入也可以是 URL：wkhtmltopdf https://example.com output.pdf。
自定义页面参数
wkhtmltopdf --page-size A4 --orientation Landscape \ --margin-top 15mm --margin-left 12mm \ input.html output.pdf--page-size支持 A3、Letter 等，--orientation只有 Portrait 和 Landscape 两个值；页边距默认 10mm，可用-B -L -R -T短参数分别设置。
页眉页脚与页码
wkhtmltopdf --header-right "Page [page] of [topage]" \ --footer-center "[date]" input.html output.pdf[page]、[topage]是占位符，会替换为当前页码和总页数，还支持[webpage]、[title]等变量。
目录与批量处理
wkhtmltopdf toc input.html output.pdf # 根据 h 标签在文档开头插入目录页面较多时，把每行一组参数喂给 stdin，可以复用同一个进程，比循环调用快不少：
echo "a.html a.pdf" | wkhtmltopdf --read-args-from-stdin各平台差异点
| 平台 | 差异操作 | 备注 |
|---|---|---|
| Linux (Debian/Ubuntu) | 安装对应发行版的 wkhtmltox.deb | 需 fontconfig 等系统依赖，包列表见 docs/downloads.md |
| Linux (RHEL/CentOS/Alma) | 安装对应发行版的.rpm | 同 Debian，按发行版选包 |
| Windows | 7z 压缩包解压后把目录加入 PATH | .exe安装器会自动写入 PATH |
| macOS | 双击.pkg安装，二进制位于/usr/local/bin | 无额外依赖 |
排错速查
| 报错关键词/现象 | 原因 | 解决命令或操作 |
|---|---|---|
wkhtmltopdf: command not found | 未加入 PATH（常见于 7z 解压版） | 把二进制目录加入 PATH，或改装.exe安装器 |
Cannot connect to X11 server | 用了发行版源里未修补的包，需要 X 服务器 | sudo apt-get install xvfb，再用xvfb-run wkhtmltopdf ...运行 |
| 中文显示为方框乱码 | 系统缺少 CJK 字体 | sudo apt-get install fonts-wqy-zenhei && fc-cache |
| dpkg 提示依赖缺失 | .deb依赖未装齐 | sudo apt-get install -f |
| JS 内容没渲染出来 | 页面脚本异步加载，渲染时机过早 | 追加参数--javascript-delay 1000 |
延伸参考
- 完整命令行参数：docs/usage/wkhtmltopdf.txt
- 各平台安装包对照表：docs/downloads.md
- 项目状态与 patched Qt 背景：docs/status.md
如果你需要在 CI 或脚本里批量生成 PDF，这套无头 HTML 转 PDF 流程可以直接落进生产环境使用。
【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
