wkhtmltopdf 安装指南：5 步搞定命令行 HTML 转 PDF

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 转一个 PDFwkhtmltopdf input.html output.pdf加上页尺寸、方向和边距这几个常用参数结果就更贴近最终排版wkhtmltopdf --page-size A4 --orientation Landscape --margin-top 20mm input.html output.pdf故障速查依赖缺失、中文乱码与慢转换怎么办现象多半原因处理命令 / 做法启动报缺 libXxx.so系统库没装全Ubuntusudo apt-get install -y fontconfig libfreetype6 libx11-6 libxext6 libxrender1CentOSsudo yum install -y fontconfig freetype libX11 libXext libXrender中文变方框或空白没装中文字体Ubuntusudo apt-get install -y fonts-wqy-zenheiCentOSsudo 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），仅供参考