简介html2pdf.zip 是一份面向 Java 开发者的 HTML 转 PDF 工具源码包基于 pd4ml 库实现重点解决复杂 HTML 布局、原始样式保留及中文字体支持难题适合 Web 开发、文档生成、报告与电子书输出等场景。压缩包共 15 个文件、约 37MB包含 pd4ml 及辅助 jar 依赖库、simsun.ttf 等中文字体、Java 源码与编译后的 class 文件以及 Eclipse 工程配置文件可帮助使用者快速理解转换流程并直接导入开发环境运行。其中 .classpath 与 .project 便于在 Eclipse 中构建项目.settings 保存 IDE 配置src 目录存放核心转换逻辑bin 目录为编译输出lib 集中管理外部库。与 iText 相比pd4ml 转换速度更快、容错性更强对中文多字体支持友好因而特别适合生成中文 PDF 文档。已有 215 人浏览学习读者可借此掌握 pd4ml 的调用方式并基于源码二次定制转换行为用于发票、报告等实际项目。1. 把 HTML 转成 PDF一份可以直接落地的工具包做后端开发的十有八九都遇到过「把网页存成 PDF」的需求——生成电子发票、导出报表、归档合同前端辛辛苦苦排好的版到了 PDF 里全乱套。我用过浏览器打印、截屏转图、硬调 CSS折腾一圈下来最省心的还是走命令行工具。html2pdf.zip 就是把 wkhtmltopdf 这类转换方案打包整理好的成品解压就能跑不需要自己再满世界找依赖。这份资源适合两类人一是手头有大量 HTML 文档要批量转 PDF 的开发者二是被报表导出折磨、想找一个稳定方案的测试或运维。它解决的核心问题很具体怎么用一条命令把 HTML 文件或网页转成排版不乱的 PDF以及怎么处理分页、页眉页脚、JavaScript 渲染这些绕不开的坑。接下来我从选型讲起逐步带你跑通它。2. 选型对比为什么用命令行方案而不是无头浏览器很多人在 HTML 转 PDF 这条路上最先想到的是无头浏览器。最常见的做法是 Puppeteer 控制 Chrome 无头模式设置好视口尺寸后等页面加载完毕再截图最后输出 PDF。这条路确实能拿到效果图但代价是你的环境里得装一个完整的浏览器内核内存和启动时间都不小而且版本一变截图尺寸和字体渲染常跟着翻车。wkhtmltopdf 走的是另一条路它基于 Qt WebKit 内核专门为渲染 PDF 而生。不弹窗口、不跑界面一条命令喂进去 HTML 路径吐出来就是 PDF 文件。它对 CSS 2.1 的支持很稳对 CSS3 里 flex 和 grid 的支持有限——但如果你要转的页面本来就是老式布局或者邮件模板这反而成了优点。HTML 本来就是这方案的主场不需要为了一个转换任务拉起来一个浏览器实例。我在这份工具包里更看重的是它的批量处理能力。你写个 Python 脚本循环遍历目录下的 HTML 文件逐个调用命令转换再对异常文件单独重试。换成无头浏览器你得先初始化浏览器实例再逐个页面打开、等待渲染、保存逻辑链路长了不止一倍。相比之下命令行方案更适合脚本化和定时任务。这份压缩包里的东西说白了就是三部分转换程序的预编译可执行文件Windows 版本带 exe、一段调用它的封装脚本、以及一份参数说明文档。它本身没有复杂的配置文件核心就是命令组装。你不需要理解 WebKit 内部机制只需要知道哪些参数控制纸张大小、哪些控制边距、哪些控制 JavaScript 的等待时间这几个参数搞明白就能覆盖大多数使用场景。3. 环境准备与基础调用把 PDF 先跑出来拿到压缩包第一步不是急着敲命令而是先确认环境。这份资源里如果带的是 Linux 版本你得先确认 glibc 版本和系统位数。我一般在 Ubuntu 20.04 及以上版本上跑依赖的共享库在系统默认源里都能找到。Windows 用户直接用包里的 exe 文件就好注意路径不要带空格否则命令行解析会出幺蛾子。解压出的目录结构通常是bin、lib和一个转换脚本文件。bin里面放主程序lib放着 Qt 运行库。第一次运行时如果提示找不到 libpng 或 libssl 类似的库就用系统的包管理器装一遍基础依赖。我在干净环境里部署过缺的通常是libxrender1和libfontconfig1装上就能跑。3.1 基础命令格式与纸张控制基础命令长这样直接在终端里执行./wkhtmltopdf --page-size A4 --margin-top 15mm --margin-bottom 15mm --encoding utf-8 input.html output.pdf这条命令做了三件事把纸张设置为 A4——A4 是电子文档最常用的尺寸把上下边距各设置为 15 毫米这个数值下打印出来不挤然后强制用 UTF-8 编码读取 HTML。之所以要加--encoding utf-8是因为如果 HTML 文件里没有显式写meta charsetutf-8某些环境下转换程序会按系统默认编码解析中文直接变成乱码。加了这参数等于从源头锁死编码问题。如果你要自定义纸张尺寸直接用--page-width和--page-height指定毫米数就行。比如生成一张宽度 80 毫米、高度 200 毫米的小票样式 PDF就是--page-width 80mm --page-height 200mm。注意单位必须带不带单位的话程序默认按毫米之外的单位处理出来的尺寸会跟你预期差得离谱。3.2 封面与目录页的拼合技巧很多文档需要先有一个独立的封面页再跟正文拼到一起。用命令行的好处是可以在一次转换中合并多个源不用先转好再手动合成./wkhtmltopdf cover cover.html --page-size A4 toc --xsl-style-sheet toc.xsl body.html final.pdfcover表示后面的文件作为封面封面页不参与分页编号。toc告诉它自动生成目录目录会基于正文中的标题标签从 h1 到 h6自动提取条目。如果不指定--xsl-style-sheet目录就按默认样式生成长文档一般都嫌它丑这个参数可以换成自定义的 XSL 模板来改字体和缩进。这个语法里有个细节值得记一下多个输入文件直接用空格分隔但必须在它们前面加上cover或toc关键字来标明角色。不加关键字的多个文件会被依次追加到正文章节里不单独分页。3.3 避坑字符集、路径与权限的 3 个高发问题第一坑中文内容转出来是方框或问号。现象是 PDF 里中文全部变成豆腐块英文和数字正常。原因是系统里没有对应字体。wkhtmltopdf 依赖的是系统级字体不是嵌入在程序里的。解决方法是先确认/usr/share/fonts目录下存在中文字体没有就装一个文泉驿微米黑或 Noto Sans CJK装完执行fc-cache刷新字体缓存再转换。第二坑相对路径引用的资源加载不出来。现象是 HTML 文件里img srcimages/logo.png引用的图片在 PDF 里是空白的。原因是对相对路径的解析基准不同。浏览器里相对路径是相对于当前页面文件所在的目录而命令行工具在没有基准目录参数时是按运行命令时的当前工作目录去解析的。解决方法是加--base-url参数指向文件所在目录或者干脆在脚本里先把工作目录切到 HTML 文件所在目录再执行转换。第三坑批量转换到一半进程退出。现象是循环处理 200 个文件跑到第 120 个时直接卡死等了半天没反应最后强制结束。原因是某些 HTML 里有复杂的 JavaScript 或无限轮询的逻辑转换程序会一直等待页面加载完成。解决方法是加--javascript-delay 1000强制让它最多等待 1000 毫秒就继续。如果页面里有重要脚本要执行但延迟不稳定就再配合--no-stop-slow-scripts这参数来平衡。4. 实战配置页眉页脚、水印与批量脚本化基础调用跑通之后我们来看真正干活时需要的东西。实际项目中的 PDF 很少是光秃秃的正文通常都要带页码、公司名称、甚至水印。wkhtmltopdf 在命令行里就支持这些不需要提前在 HTML 里写死。页眉页脚不是用参数直接传文字而是要单独提供一个 HTML 片段作为模板。这个模板是悬浮在每一页顶部的你可以在里面写表格、写图片、写内联样式。比如页脚要显示「第 X 页 / 共 Y 页」模板里就写两个占位符变量。4.1 页脚模板与翻页变量页脚模板footer.html的内容大致是这样!DOCTYPE html html head meta charsetutf-8 style .footer { width: 100%; text-align: center; font-size: 9px; color: #666; } /style /head body div classfooter 内部资料 - 第 span classpage/span 页 / 共 span classtotal/span 页 /div /body /html这里面的两个 span 是占位符类名page和total是转换程序内置的约定。命令行调用时加上./wkhtmltopdf --footer-html footer.html body.html output.pdf注意页脚模板里的单位要小一般不超过 10px因为它是直接渲染在 PDF 的物理页面上的跟屏幕像素不是一回事。页眉和页脚模板都会按实际页面宽度重新布局如果你在里面用了固定像素宽度出来的效果会在不同纸张尺寸下错位。4.2 背景、水印与灰度模式水印实现方式有两种。一种是直接在 HTML 里用绝对定位放一个半透明的大字这要求你在转换时开启背景打印否则背景色和背景图都会被忽略。命令里对应的是./wkhtmltopdf --background --print-media-type body.html output.pdf--background告诉它输出背景默认情况下背景是不打印的。--print-media-type更阴险一些它让程序用media print的 CSS 规则替代屏幕样式。如果你的 HTML 里压根没写打印样式加上这个参数通常没什么明显变化但如果你写了它就会改变布局。所以我的习惯是只在明确需要打印样式时才加其余时候不加。另一种水印方式是在输出 PDF 后用别的手段叠加。命令行工具本身没有内置的「倾斜 45 度的水印」参数如果你要的是那种从角到角的斜向水印最省事的方法是在 HTML 里放一个旋转过的层再配--background参数输出。4.3 用脚本批量转换并记录失败项单个文件手动转换没问题之后批量就是写循环的事。我给的封装脚本是 Python 的因为它在处理路径和编码上比 Shell 脚本更不容易出错import subprocess import os from pathlib import Path input_dir Path(html_files) output_dir Path(pdf_output) output_dir.mkdir(exist_okTrue) for html_file in input_dir.glob(*.html): output_file output_dir / (html_file.stem .pdf) cmd [ ./wkhtmltopdf, --page-size, A4, --margin-top, 15mm, --margin-bottom, 15mm, --footer-html, footer.html, --encoding, utf-8, str(html_file), str(output_file), ] result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: print(f转换失败: {html_file.name} - {result.stderr[:200]})这段脚本的逻辑是遍历html_files目录下的所有.html文件逐个调用转换程序失败的把错误信息的前 200 个字符打印出来。capture_output的作用是把转换程序的输出捕获到内存而不是直接打到终端上批量跑的时候不会刷屏。returncode非零时不再继续处理这个文件但循环会继续保证一个坏文件不拖累整个批次。批量场景里有个参数很容易被忽略--quiet。不加它每个文件转换时都会往 stdout 输出进度信息几百个文件下来终端就像在刷日志。加了--quiet之后程序只在真正出错时输出内容配合上面的脚本用干净利落。我把这个参数默认写进了脚本的内部命令里平时不用专门管它。5. 进阶技巧压缩输出体积与解决字体渲染偏移基础功能都跑通之后再往下走就是实际生产环境里的优化了。有两个问题非常典型一个是你辛辛苦苦转出来的 PDF 高达几十 MB另一个是同一份 HTML 在不同机器上转出来的字体间距不一样。这两个问题工具包本身没有直接提供一键解决但调整参数和配合外部工具是可以处理的。PDF 体积大的根源通常是页面里嵌入了大量图片而 wkhtmltopdf 默认不会对图片做压缩处理。你在 HTML 里放一张 4000 像素宽的截图转出来的 PDF 里这张图还是 4000 像素体积自然爆炸。我一般会在转换前对图片做一次预处理把宽度压到 1440 像素以内。这个数值是按 A4 纸宽度 210 毫米、打印分辨率约 173 dpi 反推出来的在常规阅读距离下完全够用。字体渲染偏移的问题多半是不同系统对字体度量metrics的解析差异。同一个忠正宋体字在 Ubuntu 和 CentOS 上渲染出的行高可能差 2 像素。这个 2 像素在单行文本里看不出来但当你有一个带着边框的表格每行都偏 2 像素整个表格底部就会多出一条明显的空白。我的解决习惯是把多行文本的容器全部改成固定的 line-height 值不要用 normal 或者百分比这样不同系统间渲染结果基本就一致了。再提供一个排查技巧转换完成后用qpdf这类工具做一次结构检查能发现很多肉眼看不见的问题。比如某个页面因为绝对定位元素超出页面边界导致内容虽然渲染了但不可见。命令是qpdf --check output.pdf如果输出里出现 warning那就说明 PDF 结构本身有冗余或者异常。虽然qpdf --check不能修复所有问题但它能告诉你页面连接和对象引用是否有断裂帮助我判断是重转还是手动修。整个资源用下来我自己的固定操作路径是先跑一遍基础命令拿到 PDF然后用qpdf --check看一遍结构打开 PDF 抽查三个关键页——封面、目录、正文里带表格的页。这三处没问题这份转换就算立住了。从那以后我做批量导出不管时间多紧都强制走一遍这个流程。希望帮到你。本文还有配套的精品资源点击获取