wkhtmltopdf 快速上手：3 个系统 10 分钟把 HTML 转成 PDF
【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
当你的脚本要把前端生成的报表 HTML 导出成 PDF 发给客户时，你需要的不是一台浏览器，而是一条命令。wkhtmltopdf 干的就是这件事：它基于打了补丁的 Qt Webkit，在后台把 HTML 无头渲染成 PDF 文件。下文带你用 10 分钟把这套工具装好并跑通第一条转换命令。
工具速览
wkhtmltopdf 是把 HTML 转成 PDF 的命令行工具，同一安装包还附带 wkhtmltoimage 用于导出图片。它的原理一句话：借用浏览器渲染引擎在后台完成排版，不需要占用桌面。典型用途包括报表生成、网页存档和批量文档转换。
快速上手
下面按系统拆分，目标只有一个：让wkhtmltopdf --version能打印出版本号。
Windows 下安装 wkhtmltopdf
- 打开仓库内的 docs/downloads.md，找到 Windows 安装包（.exe）的下载链接，推荐 64 位版本。
- 双击安装包按向导完成，安装程序会自动把命令加进 PATH。
- 验证安装：
wkhtmltopdf --version能打印出wkhtmltopdf 0.12.6 (with patched qt)这类信息就说明可以用了。注意：个别杀毒软件会误报安装包为WS.Reputation.1，这是已知误报，只要从官方列表下载即可放心。
macOS 下安装 wkhtmltopdf
有 Homebrew 的话一条命令：
brew install wkhtmltopdf没有 Homebrew 就从下载列表拿 .pkg 安装器双击安装。验证方式相同：
wkhtmltopdf --version注意：如果 brew 里找不到这个包或版本过旧，优先用官方 .pkg 安装器。
Linux 下安装 wkhtmltopdf
发行版多，最稳的路线是装官方为对应发行版预编译好的包。
- 从 docs/downloads.md 找到你发行版对应的 .deb / .rpm。
- 安装：
# Debian/Ubuntu 系列（以 Ubuntu 22.04 为例） sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb sudo apt-get install -f # 补齐缺失的依赖 # RHEL/CentOS/AlmaLinux 系列 sudo rpm -i wkhtmltox-0.12.6.1-2.almalinux8.x86_64.rpm- 验证：
wkhtmltopdf --version。
⚠️ 如果列表里没有你的发行版版本，用同一发行版较老 LTS 的官方包，通常能直接兼容。
核心用法
以下 5 条命令由简到繁，可以直接复制着跑。
1. 转换本地文件。最基础形态，零参数。
wkhtmltopdf input.html output.pdf一行进一行出，拿到第一份 PDF。
2. 转换网页。把 URL 直接当输入。
wkhtmltopdf https://www.example.com page.pdf默认不开启 JavaScript，动态页面可能渲染不全，排障一节有解法。
3. 指定纸张、方向和页边距。
wkhtmltopdf --page-size A4 --orientation Landscape --margin-top 20mm input.html out.pdf # --page-size 纸张大小，如 A4、Letter # --orientation 横向 # --margin-top 上边距，单位 mm得到 A4 横向、上边距 20mm 的文档。
4. 页脚加页码。
wkhtmltopdf --footer-center "第 [page] / [topage] 页" input.html out.pdf[page]和[topage]是当前页与总页数的占位宏，会在输出时被替换。
5. 封面 + 目录 + 正文合成一份。
wkhtmltopdf cover.html toc page1.html page2.html report.pdf对象按命令行出现的顺序排列：先封面、再目录、后正文，目录由页面标题标签自动生成。
场景化排障
真实项目里最常见的四种情况，每个都按“现象 → 处理 → 验证”给出。
PDF 里中文显示为方块或空白
现象：中文字体缺失，输出里汉字变成方块。
# Debian/Ubuntu sudo apt-get install -y fonts-wqy-zenhei # CentOS/RHEL sudo yum install -y wqy-zenhei-fonts fc-cache -f && fc-list | grep -i cjk # 刷新字体缓存并确认已识别验证：重新转换，中文正常显示。
无桌面环境报 Unable to init server: Could not contact X display
现象：容器或 SSH 会话里没有图形环境，转换直接失败。
sudo apt-get install -y xvfb xvfb-run -a wkhtmltopdf input.html output.pdf # 用虚拟显示跑验证：命令正常退出并生成 output.pdf。
网页动态内容缺失
现象：页面由 JavaScript 生成内容，导出的 PDF 是空壳或不完整。
wkhtmltopdf --enable-javascript --javascript-delay 1000 https://www.example.com out.pdf # --javascript-delay 让 JS 执行 1000 毫秒后再打印验证：PDF 里的动态内容与浏览器中看到的一致。
大图片页面转换慢
现象：页面挂了大量图片，命令长时间没有产出。
wkhtmltopdf --no-images input.html output.pdf # 不加载图片验证：转换时间明显缩短，需要图片时再去掉该参数。
快速参考
最常用命令与参数汇总如下：
| 命令 / 参数 | 说明 | 示例 / 默认值 |
|---|---|---|
wkhtmltopdf <输入> <输出> | 基础转换 | wkhtmltopdf a.html b.pdf |
--page-size <size> | 纸张大小 | --page-size A4 |
--orientation <方向> | 横纵向 | --orientation Landscape |
--margin-top/-left/-right/-bottom | 四边页边距 | 默认 10mm |
--no-images | 不加载图片 | 默认加载 |
--enable-javascript | 启用 JS | 默认禁用 |
--javascript-delay <msec> | 等待 JS 执行 | --javascript-delay 1000 |
-V, --version | 查看版本 | wkhtmltopdf --version |
完整参数说明在 docs/usage/wkhtmltopdf.txt，各平台安装包列表见 docs/downloads.md。想进一步深入渲染与转换流程，可以git clone https://gitcode.com/gh_mirrors/wk/wkhtmltopdf拉取源码，从src/lib/converter.cc开始读起。
【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
