wkhtmltopdf 安装指南：5 步搞定命令行 HTML 转 PDF
【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
月底要交报表，手头攒了一百多份 HTML 页面，一份份截图再拼进 Word 显然不现实。更稳妥的做法，是装上命令行工具 wkhtmltopdf，把这些 HTML 一次性批量转成 PDF。这篇文章带你走完安装、验证和第一次 HTML 转 PDF 的完整流程，顺带把中文字体、无界面服务器、转换慢这几个高频坑一次配好，看完就能直接上手。
先看 wkhtmltopdf 是什么：无头渲染 + 命令行
一句话理解它：wkhtmltopdf 把网页丢进一个"看不见屏幕"的 WebKit 渲染器里跑一遍，再把渲染结果按 PDF 格式导出，全程不弹任何窗口，所以叫无头（headless）运行。它走的是真实的浏览器渲染管线，HTML 和 CSS 支持得完整，转换质量高，速度也够日常使用。
典型用法大致有三类：
- 把定时生成的 HTML 报表批量导出成 PDF 存档
- 把一批网页或本地 .html 文件转成可打印、可分发的 PDF
- 在脚本里嵌入转换步骤，实现无人值守的自动化产出
安装前准备：确认架构、选对版本与渠道
动手前花三十秒确认两件事，能省掉后面大半的报错：
- 架构：先弄清系统是 64 位还是 32 位、具体哪个发行版，下载包要一一对应
- 版本与渠道：优先选官方仓库或包管理器提供的稳定版；渠道按"包管理器优先、官方安装包次之"的顺序来，避开来路不明的第三方包
| 确认项 | 怎么做 | 为什么重要 |
|---|---|---|
| 系统架构 | 64 位选 amd64，老机器选 i386 | 包名不同，选错装不上 |
| 发行版/版本 | 记下具体版本号，如 Ubuntu 22.04 | 决定用哪个包管理器和包名 |
| 安装渠道 | 优先包管理器，其次官方安装包 | 依赖自动解析，后续升级方便 |
分平台安装：Windows、macOS 与 Linux 各走三步
三个平台的思路一致：先选渠道，再执行安装，最后确认环境变量生效。下面每节给一条主推路径和一种备选。
Windows：从安装包到自动配置 PATH
主推路径是装官方 .exe 安装包，它会自动把 wkhtmltopdf 写进系统 PATH：
- 选渠道：从项目下载页拿到对应版本号的安装包
- 执行安装：双击安装包，跟着向导一路"下一步"即可
- 配置生效：装完 PATH 已配好，新开一个命令提示符就能直接调用
备选方案：如果公司限制装 GUI 程序，可以拿压缩包版本，把里面的可执行文件放进一个已加入 PATH 的目录，效果一样。
macOS：用 Homebrew 一条命令装好
主推路径是用 Homebrew，它会把依赖全解析好：
brew install wkhtmltopdf配置生效：命令装完即可用，不需要额外改 PATH。
备选方案：没装 Homebrew 时，下载对应 macOS 的官方压缩包，把 wkhtmltopdf 二进制拷到 /usr/local/bin（需要 sudo），同样能直接调用。
Linux：按发行版选包管理器
主推路径是用发行版自带的包管理器，依赖会自动补齐：
# Ubuntu / Debian sudo apt-get install -y wkhtmltopdf # CentOS / RHEL（先确认 EPEL 已启用） sudo yum install -y wkhtmltopdf # Alpine apk add wkhtmltopdf配置生效：装完直接可用，无需改环境变量。
备选方案：包管理器里没有你要的版本时，用官方 .deb 包手动装，装完补一下依赖：
sudo dpkg -i wkhtmltox_x.y.z.dist_amd64.deb sudo apt-get install -f三行命令验证安装，跑通第一次 HTML 转 PDF
装完先确认三件事，再跑第一次转换。
wkhtmltopdf --version wkhtmltopdf --help wkhtmltopdf --license这三行分别确认版本号能读、参数列表能列出、许可证信息正常，说明工具本身没问题。
然后是最简转换，一个 HTML 转一个 PDF：
wkhtmltopdf input.html output.pdf加上页尺寸、方向和边距这几个常用参数，结果就更贴近最终排版：
wkhtmltopdf --page-size A4 --orientation Landscape --margin-top 20mm input.html output.pdf故障速查：依赖缺失、中文乱码与慢转换怎么办
| 现象 | 多半原因 | 处理命令 / 做法 |
|---|---|---|
| 启动报缺 libXxx.so | 系统库没装全 | Ubuntu：sudo apt-get install -y fontconfig libfreetype6 libx11-6 libxext6 libxrender1；CentOS：sudo yum install -y fontconfig freetype libX11 libXext libXrender |
| 中文变方框或空白 | 没装中文字体 | Ubuntu：sudo apt-get install -y fonts-wqy-zenhei；CentOS：sudo yum install -y wqy-zenhei-fonts |
| 无图形界面服务器跑不起来 | 缺少虚拟显示 | 安装xvfb，用xvfb-run wkhtmltopdf input.html output.pdf包裹运行 |
| 转换速度明显偏慢 | 页面含 JS 和图片 | 加--disable-javascript --no-images关掉非必要加载 |
进阶调优：中文字体、headless 与常用参数
字体方面，装完中文字体后 wkhtmltopdf 会通过 fontconfig 自动找到它；如果还是乱码，多半是 HTML 里没写对font-family，补一个中文字体族名即可。
在完全无界面的服务器上，最省事的 headless 方式是配合 xvfb 跑：
xvfb-run -a wkhtmltopdf input.html output.pdf常用参数列在这里，随取随用：
| 参数 | 作用 | 示例值 |
|---|---|---|
| --page-size | 页面尺寸 | A4、Letter |
| --orientation | 纸张方向 | Portrait、Landscape |
| --margin-top / --margin-bottom | 上/下边距 | 20mm |
| --disable-javascript | 禁用 JS 提速 | （开关） |
| --no-images | 不加载图片 | （开关） |
| --low | 降渲染质量换速度 | （开关） |
文档、下载页与源码在哪找
想查完整参数说明，读 使用指南 最直接；要拿对应系统的安装包，去 下载页 按版本挑；源码则用下面的命令克隆下来自己看：
git clone https://gitcode.com/gh_mirrors/wk/wkhtmltopdf工具装好、字体配顺之后，剩下的就是把转换命令嵌进你的脚本里，让报表在月底自己跑出来。
【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
/YOLO安全帽反光衣检测)
