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 位、具体哪个发行版，下载包要一一对应
• 版本与渠道：优先选官方仓库或包管理器提供的稳定版；渠道按"包管理器优先、官方安装包次之"的顺序来，避开来路不明的第三方包

分平台安装：Windows、macOS 与 Linux 各走三步

三个平台的思路一致：先选渠道，再执行安装，最后确认环境变量生效。下面每节给一条主推路径和一种备选。

Windows：从安装包到自动配置 PATH

主推路径是装官方 .exe 安装包，它会自动把 wkhtmltopdf 写进系统 PATH：

1. 选渠道：从项目下载页拿到对应版本号的安装包
2. 执行安装：双击安装包，跟着向导一路"下一步"即可
3. 配置生效：装完 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

故障速查：依赖缺失、中文乱码与慢转换怎么办

进阶调优：中文字体、headless 与常用参数

字体方面，装完中文字体后 wkhtmltopdf 会通过 fontconfig 自动找到它；如果还是乱码，多半是 HTML 里没写对font-family，补一个中文字体族名即可。

在完全无界面的服务器上，最省事的 headless 方式是配合 xvfb 跑：

xvfb-run -a wkhtmltopdf input.html output.pdf

常用参数列在这里，随取随用：

文档、下载页与源码在哪找

想查完整参数说明，读 使用指南 最直接；要拿对应系统的安装包，去 下载页 按版本挑；源码则用下面的命令克隆下来自己看：

git clone https://gitcode.com/gh_mirrors/wk/wkhtmltopdf

工具装好、字体配顺之后，剩下的就是把转换命令嵌进你的脚本里，让报表在月底自己跑出来。

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