简介基于Aspose.Pdf实现HTML转PDF功能的.NET示例工程面向需要将网页或HTML内容转换为PDF的Web开发者和文档处理技术人员。工程通过C#项目演示从创建PdfDocument对象、加载HTML到保存PDF的完整流程并涉及页面大小、字体替换等自定义设置适合有一定.NET基础、希望快速上手PDF生成的开发者参考。压缩包共32个文件约10.62MB核心包括4个C#源文件、3个DLL库、2个TXT说明以及aspx页面、配置文件、解决方案文件等构成一个可直接打开的ASP.NET项目8个PDF文件可作为转换效果对照帮助验证输出质量。已有2091人学习。项目内含ConvertPDF.aspx及后台代码完整展示了Aspose.Pdf在样式表、图片资源处理方面的调用方式下载后解压可用Visual Studio打开研究能节省自行摸索API的时间。1. HTML转PDF这件事为什么一个页面导出能折腾一整个下午后端只要接到“把订单页面导出成 PDF”这种需求就知道麻烦来了。页面上长得好好的 HTML一到 PDF 里要么错位、要么中文字体变方块、要么表格被拦腰切断。很多人最后只能走“浏览器按 CtrlP 存 PDF”的野路子一个两个文件还行批量导出直接卡死。这次拆的资源就是专门解决这个问题的一套开箱即用的 HTML 转 PDF 工具集核心是无头浏览器渲染方案附带中文字体、打印样式模板和批量转换脚本。它解决的是“HTML 能正常打开就一定能转出像样的 PDF”这条主线——适合被 PDF 交付折磨的后端、需要批量导出单据的管理系统开发者以及自己写小工具处理文档的独立开发。2. 选型与原理无头浏览器渲染路线成为主流的三个理由2.1 三条技术路线的取舍对比浏览器内核、纯 Java 库、命令行工具先把市面上能用的方案摆在一起对比。做选型时社区里讨论最多的就是下面这三条路它们的差别直接决定了后面要花多少时间填坑。方案CSS 还原度JS 执行能力部署复杂度适合场景浏览器内核无头 Chrome / Edge高和浏览器里看到的基本一致完整图表库、异步渲染都能跑中需要本机有浏览器内核业务报表、订单票据、简历导出纯 Java 库iText、PDFBox、OpenHTMLtoPDF低到中对 CSS3 支持看运气不支持低纯 JVM 依赖简单 PDF 生成、PDF 后处理命令行工具wkhtmltopdf 等中用的还是老内核有限低快速出 PDF不追求样式我的结论很直接只要你的 HTML 里用了 flex、grid、圆角、阴影或者任意一种前端图表库就别在纯 Java 库里耗了那不是“转 PDF”那是在用 PDF 语法重画页面。命令行工具虽然部署简单但内核版本普遍偏老很多 CSS3 属性不认页面和 PDF 出来完全是两个东西。无头浏览器是唯一能保证“打开什么样导出什么样”的方案这也是现在主流的做法。2.2 渲染链路里决定成败的三个环节解析、分页与打印样式无头浏览器转 PDF 的链路不复杂先把 HTML 解析成 DOM然后经过布局、绘制最后在生成 PDF 时按照打印媒体的规则重新排版。整个过程下来真正决定产物质量的只有三个环节。第一个是解析环节。浏览器按标准解析 HTML但是如果你传进去的页面里包含未闭合标签、内联样式依赖外部资源没加载完解析结果和预览就会不一致。第二个是分页环节这也是最容易被低估的。PDF 没有“滚动条”的概念内容被一张一张纸切开表格、卡片、图片落在哪一页的分割线上全靠分页规则控制。第三个是打印样式环节。页面在屏幕上的宽度是 100% 视口打印时则要按 A4 或 A5 的物理尺寸重排不写打印样式就默认用屏幕样式硬挤结果就是左右被裁切、上下高度失控。这个资源包解决的就是这三个环节的问题。它内置了标准的打印模板把分页规则、边距、页眉页脚占位都处理好了你要做的就是把业务 HTML 塞进去跑一遍。这个概念是整个资源包的核心逻辑不要在渲染之前临时想“怎么适配”而是约定好一套打印样式标准所有页面都走这一个通道。2.3 资源包目录结构用什么就找什么改哪里就写哪里拿到资源包先别急着跑脚本花两分钟看懂目录结构后面定位问题会快很多。这套资源包按功能划分目录每个目录只干一件事目录作用改动频率engine转换引擎脚本封装了浏览器内核调用和 PDF 生成参数基本不动fonts中文字体文件目录预置了 Noto CJK 等字体按需替换templates打印样式模板包含通用 A4 模板和分页 CSS每个项目都要改config转换参数配置页面大小、边距、等待策略在这里调常常要改scripts批量转换、产物校验、水印处理等辅助脚本按场景使用output生成的 PDF 统一输出到这里每次运行都写目录设计核心原则是“引擎与内容分离”。engine 和 config 属于基础设施装上就不要再碰templates 才是你真正要写代码的地方。很多人在这一步踩的坑是把打印样式直接写死在业务页面里结果业务页面一改PDF 的样式也跟着全乱了。正确做法是让 PDF 模板始终独立于业务页面这份资源目录正好就是这个结构。3. 第一次产出 PDF环境检查、核心脚本与四项必调参数3.1 环境与内核检查先花三分钟确认依赖齐了环境检查是很多人跳过的步骤。这个资源包依赖本机浏览器内核如果你直接跑脚本然后发现报错“Cannot find module”或者“Failed to launch the browser process”大多数情况都是因为系统里没有可用的浏览器或者 Node 版本太老。先跑一遍下面的检查脚本缺什么补什么# 检查 Node 环境是否可用 node -v # 检查系统里有没有可用的浏览器内核任选一条能输出路径就行 which google-chrome || which chromium-browser || ls /Applications/Google Chrome.app/Contents/MacOS/Google Chrome # 检查系统里有没有中文字体没有输出就说明缺字体 fc-list :langzh | head -5第一行检查 Node 运行时资源包的脚本基于 Node 实现没有它后面全部白搭。第二行是找浏览器内核Chrome 和 Edge 都行重点是拿到可执行文件的完整路径这个路径后面会写进配置里。第三行是查中文字体没有输出的话遇到中文内容的 HTML 导出 PDF 会出现豆腐块我在下文专门讲这个问题。这个检查步骤看起来简单但能帮你省掉大量排错时间。我见过不少人第一天拿到资源包直接跑转换脚本报错之后到处问为什么结果一查就是电脑上只有绿版的精简浏览器内核路径根本没注册。3.2 最小可运行转换脚本状态码、页数、字节数一次拿到确认环境没问题之后来看核心转换脚本。这个脚本做的事情很简单打开一个 HTML 文件等待页面就绪然后调用浏览器内核的打印接口生成 PDF。整个转换过程只有三个代码块下面是核心部分const puppeteer require(puppeteer-core); (async () { // 连接本机已安装的浏览器内核不会下载 Chromium离线环境也能用 const browser await puppeteer.launch({ executablePath: process.env.CHROME_PATH || C:/Program Files/Google/Chrome/Application/chrome.exe, headless: new }); const page await browser.newPage(); // 打开本地 HTML 文件networkidle0 表示网络空闲后再继续 await page.goto(file:///D:/templates/order.html, { waitUntil: networkidle0, timeout: 30000 }); // 生成 PDF输出到 output 目录 await page.pdf({ path: output/order.pdf, format: A4, printBackground: true, margin: { top: 10mm, bottom: 15mm, left: 8mm, right: 8mm } }); // 关闭浏览器连接释放内存 await browser.close(); console.log(PDF 生成完成); })();重点说下这里的设计思路。puppeteer-core 和完整版 puppeteer 的区别在于它不会自动下载 Chromium必须指定 executablePath 去连本机浏览器这正是它适合离线内网环境的原因。资源包在 config 里维护了一个内核路径配置你只需在第一次使用时填一次本机浏览器的实际路径即可。page.goto 的 waitUntil 参数用的 networkidle0意思是等页面所有网络请求都结束再继续。如果你的页面里有不断轮询的接口这个参数会导致超时后面我会给出替代策略。timeout 设的 30000 毫秒是兜底正常情况下页面加载用不到这么久但大页面需要给足余量。page.pdf 里的 format、printBackground、margin 是三个核心参数每个业务场景几乎都要动我单独拉出来说明见下一小节。3.3 四项必调参数pageSize、边距、背景打印与等待策略转换脚本能跑通只是第一步产品在不同场景下要对 PDF 做不同的呈现这就要动参数了。下面是四个最常调整的参数按影响面从大到小排列参数默认值适用场景调错的表现formatA4通用文档、合同、订单页面被缩放变形或裁边margin上下 10mm 左右 8mm带页眉页脚的正式文档内容顶到纸边缘打印后装订区被切printBackgroundtrue页面有背景色、渐变、图片背景背景消失浅色文字和图形直接看不见waitUntilnetworkidle0有接口请求、图片懒加载的页面空白页、元素缺失、加载到一半就输出format 看似简单但容易忽略的是它和 CSS 里 page 规则的关系。如果页面内写了page { size: A5; }那么代码里设的 A4 会被页面内规则覆盖以页面内声明为准。所以排查“为什么我设了 A4 出来却是 A5”时先看 HTML 里有没有写 page。margin 的问题则是体现在分页上。上边距设太小内容打印出来贴边页眉根本无处安放下边距太小页码会被系统截掉。一般带页眉页脚的文档上边距至少留 15mm下边距留 18mm装订边再单独加 5mm。printBackground 这个参数容易被忽略但后果很严重。很多业务系统页面背景是浅灰色或者有纹理如果设为 false背景颜色会被抹掉浅色文字直接变透明整个 PDF 像打印店缺墨了一样。默认保持 true 就没问题。waitUntil 是最需要按页面动态调整的。如果页面里有图表、地图或者延迟加载的图片networkidle0 等待的是网络请求全部结束但有些页面网络请求结束后渲染还要几百毫秒。遇到这种情况有两种做法一种是把 waitUntil 改成 domcontentloaded再加一个 1000ms 的固定延时另一种是等某个关键元素出现用 waitForSelector 定向等待。资源包的 config 里同时预留了这两个选项按需切换即可。4. 中文、字体与图片把 PDF 从截图质感拉回印刷质感4.1 中文乱码与字体嵌入从豆腐块到印刷级字符映射HTML 转 PDF 最常遇到的问题就是中文乱码这十次里有八次不是代码问题而是服务器或本机没装中文字体。浏览器渲染 HTML 时遇到系统中不存在的字符不会报错而是用系统默认的 fallback 字体代替表现就是方块、问号或者乱码。而且这个问题在开发环境往往看不出来因为你的本机有完整的中文字体一部署到瘦身过的服务器上立刻翻车。解决方式分两步检查字体是否安装没安装就装。在 Linux 服务器上执行下面的命令# Debian / Ubuntu 系安装中文字体 apt-get install -y fonts-noto-cjk # 安装完成后刷新字体缓存 fc-cache -fv # 验证字体是否被系统正确识别 fc-match Noto Sans CJK SC第一步安装的是 Google 的 Noto CJK 字体这套字体覆盖简体、繁体、日文和韩文是目前 Linux 上最稳的中文渲染选择。第二步刷新字体缓存是很多人会漏掉的步骤——装完字体不刷新缓存系统依然找不到新字体。第三步是验证如果 fc-match 输出的字体名包含了 Noto Sans CJK说明系统已经认识它了。如果是内网离线环境装不了包这个资源包在 fonts 目录里预置了字体文件你只需要把字体文件路径写进启动参数让渲染引擎在启动时注册该字体即可。我一般会在转换脚本入口处加一行字体注册代码优先加载资源包 fonts 目录下的字体这样业务服务器什么都不用装项目中自带字体生态。注意字体问题不要在 CSS 里用font-family: 微软雅黑硬指定系统里没有这个字体时照样 fallback。建议统一用Noto Sans CJK SC或者干脆不设 font-family让浏览器用系统默认中文字体渲染效果反而更稳定。4.2 图片加载的三个坑懒加载、防盗链与 base64 内联图片在 PDF 里的表现也是一门玄学页面里看着好好的图导出后变成空白框或裂图。最常见的坑有三个懒加载、防盗链、远程图片超时。先说懒加载。现在很多页面用了loadinglazy或者各种懒加载库图片在滚动到可视区域才会去加载资源而无头浏览器生成 PDF 时并不会真的滚动整个页面所以这些图片根本不会被加载。资源包的处理方式是在调用 pdf 之前强制页面滚一遍整个文档长度或者直接把懒加载属性干掉让图上全部变成即时加载。再说防盗链。部分图床会检查 Referer无头浏览器发出的请求 Referer 是空的或异常的图片服务器直接拒绝返回 403。这种情况的表现是页面预览正常PDF 里图片缺失。绕过办法是在请求拦截阶段给图片请求统一附加 Referer 头但这个做法对业务上依赖防盗链保护版权图片的场景要谨慎。最后是远程图片。有些内网页面图片地址用的是 NAT 地址在公网环境跑转换脚本时自然访问不到。最可靠的兜底方案是提前把所有图片转成 base64 内联到 HTML 里坏处是 HTML 文件变大但换来的是完全不依赖网络。资源包的 scripts 目录里有一个图片内联脚本输入原始 HTML输出一份内联好的 HTML再交给转换引擎这一招能解决绝大多数图片相关的疑难杂症。4.3 打印页面的分页控制用 CSS 保住表格与卡片完整性分页控制是“好用”和“凑合能用”的分水岭。在不设任何分页规则的情况下表格行、卡片、代码块可能会被拦腰切断上半页一个半截表格下半页接着另半截。幸好在 CSS 层面有标准解法把这套规则写进打印样式模板里即可page { size: A4; margin: 10mm 12mm; } /* 表格、卡片、代码块尽量保持完整不跨页切断 */ table, .card, pre, img { break-inside: avoid; } /* 标题后面紧跟正文标题不要孤零零落在页尾 */ h2, h3 { break-after: avoid; } /* 长表格跨页时表头在每一页重复显示 */ thead { display: table-header-group; }page 规则定义了打印物理纸张的大小和边距这里设置的尺寸优先级高于脚本里传的参数全局唯一入口建议只维护一处。break-inside 是核心它告诉浏览器这些元素内部不要断开整块挪到下一页去展示。注意这个属性不能滥用大表格动辄十几行设了 avoid 会导致前面留白一大片所以一般只对 tbody 内的行做保护或者只对卡片和代码块做保护。thead 重复表头是长表格跨页时的关键配置没有它一个 50 行的表格分到三页后第二页和第三页都没有表头阅读的人完全不知道列含义。这个 CSS 片段在资源包的 templates 目录里就是现成的你拿到业务 HTML 后直接把这段内容插在原有样式后面覆盖即可不用改业务页面本身的代码。5. 避坑清单五个高频翻车现象与排查路径5.1 中文变成方块豆腐块现象页面上正常的汉字转成 PDF 后变成方块或者一排问号英文字母和数字正常。原因系统缺少中文字体。浏览器在找不到对应字形时用 fallback 字体替代而服务器精简版系统往往只带英文字体中文没有可用的字形映射。这个和页面代码没有关系在本地开发环境很难复现部署到服务器才会暴露。解决按 4.1 的方法安装 fonts-noto-cjk装完执行 fc-cache -fv 刷新缓存最后用 fc-match 验证。如果离线环境从资源包 fonts 目录挂载字体路径在启动参数里注册字体。装完再跑一遍转换问题就消失了。5.2 PDF 内容和浏览器预览不一致整体左移或被裁切现象浏览器里打开的页面布局正常PDF 里内容整体偏移右侧被裁掉一部分缩放比例不对。原因页面没有写打印样式也没有模拟 print 媒体类型。浏览器的屏幕渲染和打印渲染是两个不同的媒价体系屏幕宽度按视口算打印宽度按物理纸张算。在不设置任何打印规则的情况下浏览器用屏幕样式硬排到 PDF 上A4 纸宽度不够右侧就被裁掉。解决在 page.goto 之后调用await page.emulateMediaType(print);强制浏览器进入打印媒体模式让页面里的media print样式生效。同时检查页面根元素的宽度不要用 100vw 这类以视口为单位的宽度改用具名尺寸或者自适应布局。5.3 长表格被分页拦腰切断现象一个完整的长表格导出后某一行被切成上下两半上半行在上一页下半行在下一页表格线也断开了。原因默认分页规则允许在任何位置断开内容浏览器不会智能识别表格行不能拆。这个现象在跨页时非常刺眼特别是带边框的表格。解决在打印样式里给表格行加上break-inside: avoid;并配合thead { display: table-header-group; }让表头在每一页重复显示。如果表格数据量很大导致一整页放不下几行可以考虑缩小行高或者换横向纸张。还有一种做法是按业务逻辑把大表格拆成多个小表格但从通用性角度CSS 方案最简单。5.4 图表、异步数据在 PDF 里是空白现象页面上图表库渲染的折线图、柱状图在 PDF 里完全空白接口返回的数据也没有展示出来。原因生成 PDF 的动作发生在图表和数据渲染完成之前。waitUntil 设的是 networkidle0只等网络请求结束但图表库拿到数据后还需要时间完成绘制150ms 后页面看起来才是完整的。如果用的是 domcontentloaded那连接口数据都没等到。解决把 waitUntil 改为针对关键元素的显式等待例如await page.waitForSelector(#chart canvas);图表容器里出现 canvas 说明绘制基本完成。如果数据是接口加载的先await page.waitForFunction(() document.querySelector(#data).children.length 0);等数据渲染出来再执行 pdf 生成。固定延时只能作为兜底准确的做法是等待业务关键元素出现。5.5 生成的 PDF 体积异常大现象一个 20 页的 PDF生成出来体积高达几十 MB打开都卡。原因字体没有子集化整个字体文件被完整嵌入了 PDF。最常见的原因是页面 CSS 里用font-face引用了 base64 格式的字体文件浏览器把整个字体都打进了 PDF而不是只嵌入用到的字符。解决检查页面里有没有font-face和 base64 字体如果有改成资源包 fonts 目录的系统字体引用方式。如果必须用自定义字体确认使用的字体文件是 woff2 格式而不是 ttf/otfwoff2 对子集化的支持更好。后处理方案是用 PDF 压缩工具对产物二次瘦身但这个只治标不治本优先从前端源头解决。6. 进阶技巧批量并发、iText 7 水印与产物三查6.1 批量转换的并发策略控制在三个并发以内跑得又稳又快单体转换跑通后批量导出是下一个真实场景。一键导出 100 张订单 PDF 时如果一次全部并发启动无头浏览器进程内存瞬间爆掉轻则转换失败重则整台服务器卡死。我一般把并发数压到 3这个数字在速度和稳定性之间最平衡。用 shell 的方式最直接# 遍历 templates 目录下的所有 HTML同时最多 3 个转换进程并行 ls templates/*.html | xargs -P 3 -I {} node scripts/convert.js {} # 如果之前有失败漏跑的增量补转 # 只处理 output 目录里不存在的 PDF for f in templates/*.html; do name$(basename $f .html) [ -f output/$name.pdf ] || node scripts/convert.js $f done第一条命令适合全量重跑-P 3 控制并行数。第二条命令是增量补转检查 output 目录里是否已有对应的 PDF 文件有就跳过、没有才转。配合定时任务可以做成每天夜里自动补转失败文件的后台流程。6.2 用 iText 7 做后处理给 PDF 批量加盖水印很多人会把 iText 7 当成 HTML 转 PDF 的首选这是个坑。iText 对 HTML 和 CSS 的还原度很差复杂页面基本不能看。它的正确位置是后处理环节——给已经生成的 PDF 加水印、合并、加密。在这个资源包里水印脚本就是基于 iText 实现的核心逻辑如下PdfReader reader new PdfReader(output/order.pdf); PdfStamper stamper new PdfStamper(reader, new FileOutputStream(output/order_watermarked.pdf)); int n reader.getNumberOfPages(); for (int i 1; i n; i) { PdfContentByte over stamper.getOverContent(i); over.beginText(); over.setFontAndSize(BaseFont.createFont(), 42); over.setColorFill(BaseColor.LIGHT_GRAY); over.showTextAligned(Element.ALIGN_CENTER, 内部资料, PageSize.A4.getWidth() / 2, PageSize.A4.getHeight() / 2, 30); over.endText(); } stamper.close(); reader.close();这段代码遍历每一页把“内部资料”四个字以 30 度旋转居中铺在页面上。getOverContent 拿的是页面上层内容水印会压在正文上层。注意水印颜色用的是浅灰深色水印会干扰正文阅读。如果你需要每页水印位置不同可以把 showTextAligned 的坐标参数按页号偏移计算。6.3 产物三查页数、字号、颜色一个都不能省最后说一个我自己摔出来的习惯。有了工具后坑往往不是“能不能转”而是“转出来对不对”。批量跑完 50 份 PDF不可能一份份打开肉眼看我用资源包里自带的校验脚本做三查const pdfjs require(pdfjs-dist); const data new Uint8Array(fs.readFileSync(output/order.pdf)); const doc await pdfjs.getDocument({ data }).promise; // 一查页数确认没有空白页、少页 console.log(总页数:, doc.numPages); // 二查字体确认中文字体被正确嵌入而不是 fallback const page await doc.getPage(1); const ops await page.getOperatorList(); console.log(字体嵌入情况:, ops.argsArray.length 0 ? 有字体数据 : 字体缺失); // 三查页面尺寸确认生成的是 A4 而不是异常尺寸 console.log(页面尺寸:, page.view, 期待值: 595.28 x 841.89 (A4));一查页数防止因为异步加载未完成导致页面内容缺失、总页数变少。二查字体数据存在性防止中文字体 fallback。三查页面尺寸防止 CSS 里 page 声明的非 A4 尺寸悄悄改变纸张大小。这三项跑完基本能覆盖 80% 的交付事故。至于字号和颜色是否清晰机器不好判断只能抽前中后各一页人工过目但配合三查已经能把风险压到很低。从那以后我每次交付 PDF 前都强制走一遍三查页数对不对、字体嵌没嵌、尺寸变没变。这个习惯是从一次交付 52 页的报表后在打印店翻车才开始坚持的——文件没报错、页数也对但第 40 页到最后的页面全部因为字体缺失变成了方块当场没客户让重印。工具能自动完成的事都交给工具剩下的肉眼检查步骤别省。希望帮到你。本文还有配套的精品资源点击获取
简介基于Aspose.Pdf实现HTML转PDF功能的.NET示例工程面向需要将网页或HTML内容转换为PDF的Web开发者和文档处理技术人员。工程通过C#项目演示从创建PdfDocument对象、加载HTML到保存PDF的完整流程并涉及页面大小、字体替换等自定义设置适合有一定.NET基础、希望快速上手PDF生成的开发者参考。压缩包共32个文件约10.62MB核心包括4个C#源文件、3个DLL库、2个TXT说明以及aspx页面、配置文件、解决方案文件等构成一个可直接打开的ASP.NET项目8个PDF文件可作为转换效果对照帮助验证输出质量。已有2091人学习。项目内含ConvertPDF.aspx及后台代码完整展示了Aspose.Pdf在样式表、图片资源处理方面的调用方式下载后解压可用Visual Studio打开研究能节省自行摸索API的时间。1. HTML转PDF这件事为什么一个页面导出能折腾一整个下午后端只要接到“把订单页面导出成 PDF”这种需求就知道麻烦来了。页面上长得好好的 HTML一到 PDF 里要么错位、要么中文字体变方块、要么表格被拦腰切断。很多人最后只能走“浏览器按 CtrlP 存 PDF”的野路子一个两个文件还行批量导出直接卡死。这次拆的资源就是专门解决这个问题的一套开箱即用的 HTML 转 PDF 工具集核心是无头浏览器渲染方案附带中文字体、打印样式模板和批量转换脚本。它解决的是“HTML 能正常打开就一定能转出像样的 PDF”这条主线——适合被 PDF 交付折磨的后端、需要批量导出单据的管理系统开发者以及自己写小工具处理文档的独立开发。2. 选型与原理无头浏览器渲染路线成为主流的三个理由2.1 三条技术路线的取舍对比浏览器内核、纯 Java 库、命令行工具先把市面上能用的方案摆在一起对比。做选型时社区里讨论最多的就是下面这三条路它们的差别直接决定了后面要花多少时间填坑。方案CSS 还原度JS 执行能力部署复杂度适合场景浏览器内核无头 Chrome / Edge高和浏览器里看到的基本一致完整图表库、异步渲染都能跑中需要本机有浏览器内核业务报表、订单票据、简历导出纯 Java 库iText、PDFBox、OpenHTMLtoPDF低到中对 CSS3 支持看运气不支持低纯 JVM 依赖简单 PDF 生成、PDF 后处理命令行工具wkhtmltopdf 等中用的还是老内核有限低快速出 PDF不追求样式我的结论很直接只要你的 HTML 里用了 flex、grid、圆角、阴影或者任意一种前端图表库就别在纯 Java 库里耗了那不是“转 PDF”那是在用 PDF 语法重画页面。命令行工具虽然部署简单但内核版本普遍偏老很多 CSS3 属性不认页面和 PDF 出来完全是两个东西。无头浏览器是唯一能保证“打开什么样导出什么样”的方案这也是现在主流的做法。2.2 渲染链路里决定成败的三个环节解析、分页与打印样式无头浏览器转 PDF 的链路不复杂先把 HTML 解析成 DOM然后经过布局、绘制最后在生成 PDF 时按照打印媒体的规则重新排版。整个过程下来真正决定产物质量的只有三个环节。第一个是解析环节。浏览器按标准解析 HTML但是如果你传进去的页面里包含未闭合标签、内联样式依赖外部资源没加载完解析结果和预览就会不一致。第二个是分页环节这也是最容易被低估的。PDF 没有“滚动条”的概念内容被一张一张纸切开表格、卡片、图片落在哪一页的分割线上全靠分页规则控制。第三个是打印样式环节。页面在屏幕上的宽度是 100% 视口打印时则要按 A4 或 A5 的物理尺寸重排不写打印样式就默认用屏幕样式硬挤结果就是左右被裁切、上下高度失控。这个资源包解决的就是这三个环节的问题。它内置了标准的打印模板把分页规则、边距、页眉页脚占位都处理好了你要做的就是把业务 HTML 塞进去跑一遍。这个概念是整个资源包的核心逻辑不要在渲染之前临时想“怎么适配”而是约定好一套打印样式标准所有页面都走这一个通道。2.3 资源包目录结构用什么就找什么改哪里就写哪里拿到资源包先别急着跑脚本花两分钟看懂目录结构后面定位问题会快很多。这套资源包按功能划分目录每个目录只干一件事目录作用改动频率engine转换引擎脚本封装了浏览器内核调用和 PDF 生成参数基本不动fonts中文字体文件目录预置了 Noto CJK 等字体按需替换templates打印样式模板包含通用 A4 模板和分页 CSS每个项目都要改config转换参数配置页面大小、边距、等待策略在这里调常常要改scripts批量转换、产物校验、水印处理等辅助脚本按场景使用output生成的 PDF 统一输出到这里每次运行都写目录设计核心原则是“引擎与内容分离”。engine 和 config 属于基础设施装上就不要再碰templates 才是你真正要写代码的地方。很多人在这一步踩的坑是把打印样式直接写死在业务页面里结果业务页面一改PDF 的样式也跟着全乱了。正确做法是让 PDF 模板始终独立于业务页面这份资源目录正好就是这个结构。3. 第一次产出 PDF环境检查、核心脚本与四项必调参数3.1 环境与内核检查先花三分钟确认依赖齐了环境检查是很多人跳过的步骤。这个资源包依赖本机浏览器内核如果你直接跑脚本然后发现报错“Cannot find module”或者“Failed to launch the browser process”大多数情况都是因为系统里没有可用的浏览器或者 Node 版本太老。先跑一遍下面的检查脚本缺什么补什么# 检查 Node 环境是否可用 node -v # 检查系统里有没有可用的浏览器内核任选一条能输出路径就行 which google-chrome || which chromium-browser || ls /Applications/Google Chrome.app/Contents/MacOS/Google Chrome # 检查系统里有没有中文字体没有输出就说明缺字体 fc-list :langzh | head -5第一行检查 Node 运行时资源包的脚本基于 Node 实现没有它后面全部白搭。第二行是找浏览器内核Chrome 和 Edge 都行重点是拿到可执行文件的完整路径这个路径后面会写进配置里。第三行是查中文字体没有输出的话遇到中文内容的 HTML 导出 PDF 会出现豆腐块我在下文专门讲这个问题。这个检查步骤看起来简单但能帮你省掉大量排错时间。我见过不少人第一天拿到资源包直接跑转换脚本报错之后到处问为什么结果一查就是电脑上只有绿版的精简浏览器内核路径根本没注册。3.2 最小可运行转换脚本状态码、页数、字节数一次拿到确认环境没问题之后来看核心转换脚本。这个脚本做的事情很简单打开一个 HTML 文件等待页面就绪然后调用浏览器内核的打印接口生成 PDF。整个转换过程只有三个代码块下面是核心部分const puppeteer require(puppeteer-core); (async () { // 连接本机已安装的浏览器内核不会下载 Chromium离线环境也能用 const browser await puppeteer.launch({ executablePath: process.env.CHROME_PATH || C:/Program Files/Google/Chrome/Application/chrome.exe, headless: new }); const page await browser.newPage(); // 打开本地 HTML 文件networkidle0 表示网络空闲后再继续 await page.goto(file:///D:/templates/order.html, { waitUntil: networkidle0, timeout: 30000 }); // 生成 PDF输出到 output 目录 await page.pdf({ path: output/order.pdf, format: A4, printBackground: true, margin: { top: 10mm, bottom: 15mm, left: 8mm, right: 8mm } }); // 关闭浏览器连接释放内存 await browser.close(); console.log(PDF 生成完成); })();重点说下这里的设计思路。puppeteer-core 和完整版 puppeteer 的区别在于它不会自动下载 Chromium必须指定 executablePath 去连本机浏览器这正是它适合离线内网环境的原因。资源包在 config 里维护了一个内核路径配置你只需在第一次使用时填一次本机浏览器的实际路径即可。page.goto 的 waitUntil 参数用的 networkidle0意思是等页面所有网络请求都结束再继续。如果你的页面里有不断轮询的接口这个参数会导致超时后面我会给出替代策略。timeout 设的 30000 毫秒是兜底正常情况下页面加载用不到这么久但大页面需要给足余量。page.pdf 里的 format、printBackground、margin 是三个核心参数每个业务场景几乎都要动我单独拉出来说明见下一小节。3.3 四项必调参数pageSize、边距、背景打印与等待策略转换脚本能跑通只是第一步产品在不同场景下要对 PDF 做不同的呈现这就要动参数了。下面是四个最常调整的参数按影响面从大到小排列参数默认值适用场景调错的表现formatA4通用文档、合同、订单页面被缩放变形或裁边margin上下 10mm 左右 8mm带页眉页脚的正式文档内容顶到纸边缘打印后装订区被切printBackgroundtrue页面有背景色、渐变、图片背景背景消失浅色文字和图形直接看不见waitUntilnetworkidle0有接口请求、图片懒加载的页面空白页、元素缺失、加载到一半就输出format 看似简单但容易忽略的是它和 CSS 里 page 规则的关系。如果页面内写了page { size: A5; }那么代码里设的 A4 会被页面内规则覆盖以页面内声明为准。所以排查“为什么我设了 A4 出来却是 A5”时先看 HTML 里有没有写 page。margin 的问题则是体现在分页上。上边距设太小内容打印出来贴边页眉根本无处安放下边距太小页码会被系统截掉。一般带页眉页脚的文档上边距至少留 15mm下边距留 18mm装订边再单独加 5mm。printBackground 这个参数容易被忽略但后果很严重。很多业务系统页面背景是浅灰色或者有纹理如果设为 false背景颜色会被抹掉浅色文字直接变透明整个 PDF 像打印店缺墨了一样。默认保持 true 就没问题。waitUntil 是最需要按页面动态调整的。如果页面里有图表、地图或者延迟加载的图片networkidle0 等待的是网络请求全部结束但有些页面网络请求结束后渲染还要几百毫秒。遇到这种情况有两种做法一种是把 waitUntil 改成 domcontentloaded再加一个 1000ms 的固定延时另一种是等某个关键元素出现用 waitForSelector 定向等待。资源包的 config 里同时预留了这两个选项按需切换即可。4. 中文、字体与图片把 PDF 从截图质感拉回印刷质感4.1 中文乱码与字体嵌入从豆腐块到印刷级字符映射HTML 转 PDF 最常遇到的问题就是中文乱码这十次里有八次不是代码问题而是服务器或本机没装中文字体。浏览器渲染 HTML 时遇到系统中不存在的字符不会报错而是用系统默认的 fallback 字体代替表现就是方块、问号或者乱码。而且这个问题在开发环境往往看不出来因为你的本机有完整的中文字体一部署到瘦身过的服务器上立刻翻车。解决方式分两步检查字体是否安装没安装就装。在 Linux 服务器上执行下面的命令# Debian / Ubuntu 系安装中文字体 apt-get install -y fonts-noto-cjk # 安装完成后刷新字体缓存 fc-cache -fv # 验证字体是否被系统正确识别 fc-match Noto Sans CJK SC第一步安装的是 Google 的 Noto CJK 字体这套字体覆盖简体、繁体、日文和韩文是目前 Linux 上最稳的中文渲染选择。第二步刷新字体缓存是很多人会漏掉的步骤——装完字体不刷新缓存系统依然找不到新字体。第三步是验证如果 fc-match 输出的字体名包含了 Noto Sans CJK说明系统已经认识它了。如果是内网离线环境装不了包这个资源包在 fonts 目录里预置了字体文件你只需要把字体文件路径写进启动参数让渲染引擎在启动时注册该字体即可。我一般会在转换脚本入口处加一行字体注册代码优先加载资源包 fonts 目录下的字体这样业务服务器什么都不用装项目中自带字体生态。注意字体问题不要在 CSS 里用font-family: 微软雅黑硬指定系统里没有这个字体时照样 fallback。建议统一用Noto Sans CJK SC或者干脆不设 font-family让浏览器用系统默认中文字体渲染效果反而更稳定。4.2 图片加载的三个坑懒加载、防盗链与 base64 内联图片在 PDF 里的表现也是一门玄学页面里看着好好的图导出后变成空白框或裂图。最常见的坑有三个懒加载、防盗链、远程图片超时。先说懒加载。现在很多页面用了loadinglazy或者各种懒加载库图片在滚动到可视区域才会去加载资源而无头浏览器生成 PDF 时并不会真的滚动整个页面所以这些图片根本不会被加载。资源包的处理方式是在调用 pdf 之前强制页面滚一遍整个文档长度或者直接把懒加载属性干掉让图上全部变成即时加载。再说防盗链。部分图床会检查 Referer无头浏览器发出的请求 Referer 是空的或异常的图片服务器直接拒绝返回 403。这种情况的表现是页面预览正常PDF 里图片缺失。绕过办法是在请求拦截阶段给图片请求统一附加 Referer 头但这个做法对业务上依赖防盗链保护版权图片的场景要谨慎。最后是远程图片。有些内网页面图片地址用的是 NAT 地址在公网环境跑转换脚本时自然访问不到。最可靠的兜底方案是提前把所有图片转成 base64 内联到 HTML 里坏处是 HTML 文件变大但换来的是完全不依赖网络。资源包的 scripts 目录里有一个图片内联脚本输入原始 HTML输出一份内联好的 HTML再交给转换引擎这一招能解决绝大多数图片相关的疑难杂症。4.3 打印页面的分页控制用 CSS 保住表格与卡片完整性分页控制是“好用”和“凑合能用”的分水岭。在不设任何分页规则的情况下表格行、卡片、代码块可能会被拦腰切断上半页一个半截表格下半页接着另半截。幸好在 CSS 层面有标准解法把这套规则写进打印样式模板里即可page { size: A4; margin: 10mm 12mm; } /* 表格、卡片、代码块尽量保持完整不跨页切断 */ table, .card, pre, img { break-inside: avoid; } /* 标题后面紧跟正文标题不要孤零零落在页尾 */ h2, h3 { break-after: avoid; } /* 长表格跨页时表头在每一页重复显示 */ thead { display: table-header-group; }page 规则定义了打印物理纸张的大小和边距这里设置的尺寸优先级高于脚本里传的参数全局唯一入口建议只维护一处。break-inside 是核心它告诉浏览器这些元素内部不要断开整块挪到下一页去展示。注意这个属性不能滥用大表格动辄十几行设了 avoid 会导致前面留白一大片所以一般只对 tbody 内的行做保护或者只对卡片和代码块做保护。thead 重复表头是长表格跨页时的关键配置没有它一个 50 行的表格分到三页后第二页和第三页都没有表头阅读的人完全不知道列含义。这个 CSS 片段在资源包的 templates 目录里就是现成的你拿到业务 HTML 后直接把这段内容插在原有样式后面覆盖即可不用改业务页面本身的代码。5. 避坑清单五个高频翻车现象与排查路径5.1 中文变成方块豆腐块现象页面上正常的汉字转成 PDF 后变成方块或者一排问号英文字母和数字正常。原因系统缺少中文字体。浏览器在找不到对应字形时用 fallback 字体替代而服务器精简版系统往往只带英文字体中文没有可用的字形映射。这个和页面代码没有关系在本地开发环境很难复现部署到服务器才会暴露。解决按 4.1 的方法安装 fonts-noto-cjk装完执行 fc-cache -fv 刷新缓存最后用 fc-match 验证。如果离线环境从资源包 fonts 目录挂载字体路径在启动参数里注册字体。装完再跑一遍转换问题就消失了。5.2 PDF 内容和浏览器预览不一致整体左移或被裁切现象浏览器里打开的页面布局正常PDF 里内容整体偏移右侧被裁掉一部分缩放比例不对。原因页面没有写打印样式也没有模拟 print 媒体类型。浏览器的屏幕渲染和打印渲染是两个不同的媒价体系屏幕宽度按视口算打印宽度按物理纸张算。在不设置任何打印规则的情况下浏览器用屏幕样式硬排到 PDF 上A4 纸宽度不够右侧就被裁掉。解决在 page.goto 之后调用await page.emulateMediaType(print);强制浏览器进入打印媒体模式让页面里的media print样式生效。同时检查页面根元素的宽度不要用 100vw 这类以视口为单位的宽度改用具名尺寸或者自适应布局。5.3 长表格被分页拦腰切断现象一个完整的长表格导出后某一行被切成上下两半上半行在上一页下半行在下一页表格线也断开了。原因默认分页规则允许在任何位置断开内容浏览器不会智能识别表格行不能拆。这个现象在跨页时非常刺眼特别是带边框的表格。解决在打印样式里给表格行加上break-inside: avoid;并配合thead { display: table-header-group; }让表头在每一页重复显示。如果表格数据量很大导致一整页放不下几行可以考虑缩小行高或者换横向纸张。还有一种做法是按业务逻辑把大表格拆成多个小表格但从通用性角度CSS 方案最简单。5.4 图表、异步数据在 PDF 里是空白现象页面上图表库渲染的折线图、柱状图在 PDF 里完全空白接口返回的数据也没有展示出来。原因生成 PDF 的动作发生在图表和数据渲染完成之前。waitUntil 设的是 networkidle0只等网络请求结束但图表库拿到数据后还需要时间完成绘制150ms 后页面看起来才是完整的。如果用的是 domcontentloaded那连接口数据都没等到。解决把 waitUntil 改为针对关键元素的显式等待例如await page.waitForSelector(#chart canvas);图表容器里出现 canvas 说明绘制基本完成。如果数据是接口加载的先await page.waitForFunction(() document.querySelector(#data).children.length 0);等数据渲染出来再执行 pdf 生成。固定延时只能作为兜底准确的做法是等待业务关键元素出现。5.5 生成的 PDF 体积异常大现象一个 20 页的 PDF生成出来体积高达几十 MB打开都卡。原因字体没有子集化整个字体文件被完整嵌入了 PDF。最常见的原因是页面 CSS 里用font-face引用了 base64 格式的字体文件浏览器把整个字体都打进了 PDF而不是只嵌入用到的字符。解决检查页面里有没有font-face和 base64 字体如果有改成资源包 fonts 目录的系统字体引用方式。如果必须用自定义字体确认使用的字体文件是 woff2 格式而不是 ttf/otfwoff2 对子集化的支持更好。后处理方案是用 PDF 压缩工具对产物二次瘦身但这个只治标不治本优先从前端源头解决。6. 进阶技巧批量并发、iText 7 水印与产物三查6.1 批量转换的并发策略控制在三个并发以内跑得又稳又快单体转换跑通后批量导出是下一个真实场景。一键导出 100 张订单 PDF 时如果一次全部并发启动无头浏览器进程内存瞬间爆掉轻则转换失败重则整台服务器卡死。我一般把并发数压到 3这个数字在速度和稳定性之间最平衡。用 shell 的方式最直接# 遍历 templates 目录下的所有 HTML同时最多 3 个转换进程并行 ls templates/*.html | xargs -P 3 -I {} node scripts/convert.js {} # 如果之前有失败漏跑的增量补转 # 只处理 output 目录里不存在的 PDF for f in templates/*.html; do name$(basename $f .html) [ -f output/$name.pdf ] || node scripts/convert.js $f done第一条命令适合全量重跑-P 3 控制并行数。第二条命令是增量补转检查 output 目录里是否已有对应的 PDF 文件有就跳过、没有才转。配合定时任务可以做成每天夜里自动补转失败文件的后台流程。6.2 用 iText 7 做后处理给 PDF 批量加盖水印很多人会把 iText 7 当成 HTML 转 PDF 的首选这是个坑。iText 对 HTML 和 CSS 的还原度很差复杂页面基本不能看。它的正确位置是后处理环节——给已经生成的 PDF 加水印、合并、加密。在这个资源包里水印脚本就是基于 iText 实现的核心逻辑如下PdfReader reader new PdfReader(output/order.pdf); PdfStamper stamper new PdfStamper(reader, new FileOutputStream(output/order_watermarked.pdf)); int n reader.getNumberOfPages(); for (int i 1; i n; i) { PdfContentByte over stamper.getOverContent(i); over.beginText(); over.setFontAndSize(BaseFont.createFont(), 42); over.setColorFill(BaseColor.LIGHT_GRAY); over.showTextAligned(Element.ALIGN_CENTER, 内部资料, PageSize.A4.getWidth() / 2, PageSize.A4.getHeight() / 2, 30); over.endText(); } stamper.close(); reader.close();这段代码遍历每一页把“内部资料”四个字以 30 度旋转居中铺在页面上。getOverContent 拿的是页面上层内容水印会压在正文上层。注意水印颜色用的是浅灰深色水印会干扰正文阅读。如果你需要每页水印位置不同可以把 showTextAligned 的坐标参数按页号偏移计算。6.3 产物三查页数、字号、颜色一个都不能省最后说一个我自己摔出来的习惯。有了工具后坑往往不是“能不能转”而是“转出来对不对”。批量跑完 50 份 PDF不可能一份份打开肉眼看我用资源包里自带的校验脚本做三查const pdfjs require(pdfjs-dist); const data new Uint8Array(fs.readFileSync(output/order.pdf)); const doc await pdfjs.getDocument({ data }).promise; // 一查页数确认没有空白页、少页 console.log(总页数:, doc.numPages); // 二查字体确认中文字体被正确嵌入而不是 fallback const page await doc.getPage(1); const ops await page.getOperatorList(); console.log(字体嵌入情况:, ops.argsArray.length 0 ? 有字体数据 : 字体缺失); // 三查页面尺寸确认生成的是 A4 而不是异常尺寸 console.log(页面尺寸:, page.view, 期待值: 595.28 x 841.89 (A4));一查页数防止因为异步加载未完成导致页面内容缺失、总页数变少。二查字体数据存在性防止中文字体 fallback。三查页面尺寸防止 CSS 里 page 声明的非 A4 尺寸悄悄改变纸张大小。这三项跑完基本能覆盖 80% 的交付事故。至于字号和颜色是否清晰机器不好判断只能抽前中后各一页人工过目但配合三查已经能把风险压到很低。从那以后我每次交付 PDF 前都强制走一遍三查页数对不对、字体嵌没嵌、尺寸变没变。这个习惯是从一次交付 52 页的报表后在打印店翻车才开始坚持的——文件没报错、页数也对但第 40 页到最后的页面全部因为字体缺失变成了方块当场没客户让重印。工具能自动完成的事都交给工具剩下的肉眼检查步骤别省。希望帮到你。本文还有配套的精品资源点击获取
