wkhtmltopdf 使用指南：把 HTML 网页转成 PDF 的 5 个实用技巧
【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
想在服务器或终端里把网页、报表 HTML 文件转成格式规整的 PDF，又不想靠浏览器截图对不齐？wkhtmltopdf 是一款基于 Qt WebKit 引擎的命令行转换工具，一行命令即可把网页渲染成与浏览器几乎一致的 PDF 文档。
📌 核心能力速览：它能做什么
wkhtmltopdf（以及配套的 wkhtmltoimage）是一组命令行工具，基于 Qt WebKit 引擎渲染 HTML，全程 headless 运行，无需图形界面或显示器。
- 把单个或一批 HTML 页面合并渲染成一份 PDF
- 支持插入封面页、自动目录（TOC）和 PDF 书签大纲
- 可加页眉页脚与页码，支持 A4 / Letter 等纸张及横纵方向
- 能控制 JavaScript、图片、背景是否加载，并调节画质与体积
📥 安装与环境准备
最快跑起来的方式是用系统包管理器（以 Debian/Ubuntu 为例，一行命令即可，需安装 fontconfig 与 freetype 字体依赖）：
sudo apt-get install wkhtmltopdf装完运行wkhtmltopdf --version确认版本即可。要获得完整功能，建议改用官方预编译包：从打包仓库下载对应系统的.deb/.rpm/.pkg/.exe安装即用，各发行版说明见 下载文档。
注意：发行版源里的 wkhtmltopdf 通常使用未打补丁的 Qt，会缺少大纲、目录、页眉页脚变量等高级功能；想完整体验请使用官方预编译包。
🚀 基础用法：快速上手命令
三条最典型的命令，覆盖绝大多数场景：
# 把一个网页转成 PDF wkhtmltopdf https://example.com out.pdf # 把本地 HTML 文件转成 PDF wkhtmltopdf report.html report.pdf # 在开头插入自动目录，再生成正文 wkhtmltopdf toc report.html out.pdf多个页面对象按顺序排在命令行上即可合并成一份文档，cover和toc也是对象，例如wkhtmltopdf cover.html toc a.html b.html out.pdf。
🎛️ 常用参数指南：排版、页眉与质量
排版与输出
| 参数 | 说明 |
|---|---|
-s, --page-size A4 | 纸张尺寸，默认 A4，可换 A3 / Letter / Legal |
-O, --orientation Landscape | 切换横向排版 |
-T / -B / -L / -R 15mm | 分别设置上 / 下 / 左 / 右边距 |
页眉页脚
| 参数 | 说明 |
|---|---|
--header-right "Page [page] of [topage]" | 右上角显示“第 x 页共 y 页” |
--footer-center "文档标题" | 底部居中文本 |
--default-header | 一键默认页眉：左页名、右页码 |
内容与质量
| 参数 | 说明 |
|---|---|
--zoom 1.3 | 整体缩放，修复内容超出纸面的问题 |
--lowquality | 降低画质以减小 PDF 体积 |
--javascript-delay 1000 | 等待 JS 渲染完成（毫秒） |
🔬 进阶技巧：更快更稳
- 只要内容、跳过图片：加
--no-images不加载图片，转换更快，适合纯文本报告。 - 批量转换省启动开销：用
--read-args-from-stdin从标准输入逐行读取参数，一个进程处理多份文档，如wkhtmltopdf --read-args-from-stdin < cmds。 - 自定义目录样式：先
--dump-default-toc-xsl导出默认 XSL 样式表作为起点，再用--xsl-style-sheet my.xsl套上自己的目录样式。 - 等动态内容加载完：对依赖 JS 的页面，用
--window-status done等到脚本把window.status置为指定值后再渲染。
⚠️ 常见问题排查：中文乱码与图片缺失
中文显示为方块现象：PDF 里中文全是方框。原因：系统缺少中文字体。解决：安装 CJK 字体后重跑，如sudo apt-get install fonts-noto-cjk，并确认输入带--encoding UTF-8。
本地 HTML 引用的图片不显示现象：本地文件里的图片、子页面一片空白。原因：默认禁止本地文件访问。解决：加--enable-local-file-access，或只放行指定目录--allow ./assets。
页面是 JS 动态渲染，PDF 却是空的现象：内容没加载出来。原因：脚本还没跑完就出图了。解决：加大--javascript-delay 2000，或用--run-script "..."在页面加载后手动补执行。
📚 资源导航：官方文档与源码入口
- 官方使用文档：docs/usage/wkhtmltopdf.txt
- 项目状态与引擎说明：docs/status.md
- 下载与发行版说明：docs/downloads.md
- 安全（AppArmor 策略）：docs/apparmor.md
- C 库 API 文档与示例：docs/libwkhtmltox/、examples/
- 从源码获取：
git clone https://gitcode.com/gh_mirrors/wk/wkhtmltopdf（实际编译打包在独立的 packaging 仓库进行）
【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
