简介一份基于Java与PhantomJS实现的URL转PDF/HTML转PDF简易Demo面向需要将网页内容或HTML模板转换为高质量PDF的Java开发人员。作者经过对比wkhtmltopdf与IText后认为PhantomJS在体积、URL转换完整度方面更具优势因此重点演示如何借助PhantomJS完成转换适合用于报表导出、网页快照、文档归档等场景。压缩包内共85个文件整体约34.65MB其中67个xml为Maven依赖管理配置5个java为Spring Boot核心源码2个js为PhantomJS脚本2个exe为PhantomJS可执行文件另含class、properties等辅助文件目录结构清晰可直接导入项目运行。资源提供完整的Maven工程结构包含核心源码与PhantomJS脚本示例展示了从HTML/URL到PDF的调用流程可帮助开发者快速理解并集成类似功能。已有1108人学习/下载适合具备一定Java基础、希望在Spring Boot中快速实现PDF转换的开发者参考。 先说丑话URL转PDF、HTML转PDF看起来就是把网页“另存为PDF”的小工具真做起来坑比你想象的多。最近我刚把一个网页批量转PDF的服务重写了一遍从选型到落地折腾了小一周。这个需求在内部工具、爬虫、文档归档系统里几乎躲不开——运营周报要定时截图存档、电商后台要把订单页面导成对账单、法律或财务场景要做网页证据保全、甚至你只是想把一个HTML模板填充数据后生成合同或简历。网上转PDF的教程不少但大多只扔给你一段代码不解释为什么这么写也不讲碰到404、502、乱码、空白页时怎么排查。这篇我把整个项目从需求、选型、代码到排查经验完整记录下来适合正在做类似功能或者准备把你那个“页面另存为PDF”的脚本升级成工程化服务的人。1. 需求拆解这个需求到底在解决什么问题1.1 最常见的几类使用场景URL转PDF、HTML转PDF本质上要解决的是“把动态网页内容固化成不可变文档”的问题。我遇到的真实场景大概分这几类报表与工单归档BI大屏、监控面板、运营看板每天定时转成PDF存到OSS或发邮箱留存历史版本。文件凭证与证据保全订单详情页、用户协议页、发票页面在某个时间点转成PDF作为合同或纠纷证据页面改动不影响归档内容。HTML模板批量出件简历、报价单、电子合同这类场景后端用模板引擎Velocity、FreeMarker、Jinja2往HTML模板里塞数据渲染完再转PDF用于下载和打印。离线阅读与分发把长篇文章或帮助中心文档转成PDF方便用户离线阅读或者打包成知识库。网上关于pdf转word、pdf转曲、pdf图片中文设置这类提问也特别多说明PDF这个东西一旦进入业务链路它前面是生成、后面必然接着转换、提取、编辑的整条生态生成端做扎实了后面能省很多事。1.2 URL输入和HTML输入是两条不同的路很多教程把URL转PDF和HTML转PDF混着讲实际上这两者有本质区别。URL输入的本质是“访问一个远程页面并复刻渲染结果”这个过程涉及网络请求、重定向、登录态、懒加载、跨域资源、反爬策略页面最终长什么样不光取决于你的代码还取决于目标网站的当前状态。HTML输入的本质是“把一段字符串排版成文档”输入是无状态的不依赖网络也能出文件难点在别处。HTML字符串里很可能有相对路径的资源比如img src/images/logo.png如果你不在某个有效页面上下文中去渲染它浏览器根本不知道/images/logo.png的根域名是哪个图片、CSS、JS全都会挂掉。所以做方案的时候第一件事就是明确你的输入源是哪种如果两种都要支持代码必须分开设计混在一块迟早出问题。2. 选型对比浏览器渲染还是纯解析渲染2.1 两条技术路线的基本原理把HTML转成PDF业内基本是两大路线。一条是浏览器渲染路线用真实浏览器内核Chromium或WebKit去加载页面执行JS、请求资源、等渲染完成然后调用浏览器的打印引擎输出PDF。代表工具有Puppeteer、Playwright、wkhtmltopdf。优点是所见即所得页面多复杂都能还原缺点是重要下载Chromium内核内存占用高而且浏览器本身是个吃资源的“胖子”。另一条是纯解析渲染路线不执行JS直接用HTML/CSS解析器把DOM排版成PDF文档。代表工具有WeasyPrint、iText、飞书云文档导出之类的。优点是轻量、启动快、依赖少适合排版讲究的正式文档缺点也明显遇到Flex/Grid布局、CSS变量、JS动态渲染就基本歇菜页面保真度远不如浏览器渲染。我见过有人试图直接用requests把HTML拉下来然后写进PDF这个思路方向不对。HTML是排版描述语言浏览器才是负责把它“画”出来的角色requests拉回来的只是一堆标签字符串离PDF还差一个渲染引擎。2.2 主流方案横向对比工具渲染内核适用场景中文字体支持部署体积主要坑点wkhtmltopdfQt WebKit老项目、轻量服务依赖系统字体中现代CSS3特性大量不支持Puppeteer/PlaywrightChromium复杂页面、高保真快照需安装中文字体大几百MB内核下载慢、内存占用高WeasyPrint自研HTML渲染正式报告、简历、文档需配置中文字体文件小不支持JS复杂布局会崩浏览器手动打印原生人工零星操作不受影响无无法自动化人力成本高这套对比做完结论已经很清晰了。如果目标是“复现一个复杂的现代网页”除了Puppeteer/Playwright没有更好的选择如果只是把自产自销的干净HTML模板变成PDFWeasyPrint反而更实用输出文件小、速度快、依赖轻不会为了一个PDF把500MB的Chromium拖进来。2.3 我的选型逻辑这次我最终用了Playwright原因是客户方需要高保真还原前端页面而且那些页面里有大量ECharts图表纯解析路线连图表都渲染不出来。选Playwright而不是Puppeteer主要看中它同时支持同步和异步API语言绑定覆盖Python和Node.js还能处理多标签页、新窗口等弹窗场景写起日志和重试也方便。选型时另外考虑过wkhtmltopdf它确实轻便但它基于老旧的Qt WebKit现代页面里的CSS Grid、flex布局支持不到位稍微复杂一点的样式就乱了。这种兼容性债务越到后期越头疼建议新项目别选它。3. 实操落地用Playwright把URL和HTML转成PDF3.1 环境准备与依赖安装我用的是Python版Playwright安装很简单pip install playwright playwright install chromium第二步会下载Chromium内核体积不小网络不好的时候容易失败。如果你是在服务器上跑一般还需要装几个基础系统库官方文档有提供对应的安装命令直接复制即可。这里有一个默认没人提的坑如果服务器是最小化安装的Linux很可能是没有中文字体的渲染出来的中文全是方块。这一条我放在最前面因为它能让你在调试乱码问题时少走一晚上的弯路提示渲染前先确认系统里有没有中文字体。Debian/Ubuntu可以执行apt install fonts-noto-cjkCentOS是yum install wqy-microhei或fonts-noto-cjk。装完重启服务进程再试。如果页面里用了特殊字体还需要在CSS里把字体栈配置好比如font-family: Noto Sans CJK SC, Microsoft YaHei, sans-serif;。3.2 URL转PDF的完整代码最简单的URL转PDF用Playwright同步API写是这样from playwright.sync_api import sync_playwright def url_to_pdf(url: str, output_path: str): with sync_playwright() as p: browser p.chromium.launch() page browser.new_page() response page.goto(url, wait_untilnetworkidle, timeout30_000) if response is None or not response.ok: raise RuntimeError(f页面加载失败状态码: {response.status if response else unknown}) page.pdf( pathoutput_path, formatA4, print_backgroundTrue, margin{top: 10mm, bottom: 10mm, left: 10mm, right: 10mm}, ) browser.close()几个参数我详细说明一下。wait_untilnetworkidle的意思是等页面所有网络请求都结束再继续。对大部分页面来说这是最稳的。但要注意有些页面有轮询接口永远不会进入networkidle状态这种页面就会一直卡到超时。我在生产环境里的做法是优先networkidle加超时超时后降级成domcontentloaded再等多几秒。print_backgroundTrue这个参数如果你不设页面上所有background-color、渐变、背景图全部都会被丢掉。这个也是很多人第一次转PDF时发现的诡异问题页面看着好好的转出来白花花一片。formatA4控制纸张大小也可以设成A3、Letter或者直接用width和height指定像素值。A4默认是210mm×297mm如果页面比较宽可以设置landscapeTrue横向输入否则右侧会被硬切掉。3.3 HTML转PDF的差异点与代码HTML转PDF和URL转PDF最大的差异在于资源定位。URL转PDF时浏览器知道当前页面地址所有相对路径资源都能正确拼出来。而直接塞HTML字符串时页面地址是about:blank图片、CSS、JS等相对路径全部不知道怎么解析。我的处理方式是先把HTML塞给页面再注入一个base标签指定资源根路径。from playwright.sync_api import sync_playwright def html_to_pdf(html: str, output_path: str, base_url: str None): with sync_playwright() as p: browser p.chromium.launch() page browser.new_page() page.set_content(html, wait_untilnetworkidle) if base_url: page.evaluate((url) { const base document.createElement(base); base.href url; document.head.appendChild(base); }, base_url) page.pdf(pathoutput_path, formatA4, print_backgroundTrue) browser.close()base_url参数就是告诉浏览器“页面的根地址是这个遇到相对路径一律以它为准”。这个技巧在官方文档里没有直接示例但实际开发中非常常用。另一点经验如果你能控制HTML模板的生成尽量在模板侧就把资源路径拼成绝对路径或者干脆把CSS和图片转成base64内联。这样运行时完全不依赖外部环境既快了又稳了尤其是内网穿透或者登录态失效的情况下外链资源最容易变成404。3.4 打印参数怎么定别忽略这些细节只要页面是自己控制的建议直接用CSSpage规则控制分页、页眉、页脚然后在代码里传prefer_css_page_sizeTrue让PDF引擎服从CSS。这样代码不用写死纸张大小样式调整也灵活。如果需要在每页底部显示页码或时间可以设置display_header_footerTrue再通过header_template和footer_template自定义内容。默认的页眉页脚是Chrome那套“网页标题日期URL”的样式在正式场景里一般是要改掉的。另外分页问题迟早会遇到。表格被拦腰截断、卡片被劈成两半这类问题多半要写打印样式media print { .no-print { display: none !important; } body { -webkit-print-color-adjust: exact; } .card, table tr { break-inside: avoid; } }break-inside: avoid意思是“这个元素尽量不要被分页断开”对表格行、卡片、标题这类元素非常有效。这个问题在纯屏幕展示时完全暴露不出来只有在打印PDF时才会出现。4. 前置校验URL有效性检查不能省4.1 为什么必须做两层校验我在接这个需求时第一版直接拿到URL就去page.goto()结果发现只要URL格式不合法浏览器会把输入当搜索词处理最终生成的PDF是一个搜索引擎结果页非常隐蔽。更危险的是像file://、javascript:这类危险协议一旦被接进Web服务就有被用来读取本地文件或执行脚本的风险。所以URL转PDF服务必须做两层校验第一层是格式校验第二层是远程连通性探测。缺一层都会出大问题。4.2 用JS做URL格式校验格式校验我推荐直接用浏览器内置的URL构造函数不要自己写正则。正则处理IDN域名、IPv6、带端口、query里带特殊字符这些情况又臭又容易出错内置构造函数帮你处理好了function isValidHttpUrl(candidate) { let parsed; try { parsed new URL(candidate); } catch (_) { return false; } return parsed.protocol http: || parsed.protocol https:; }这一个函数就挡住了大多数非法格式。注意协议白名单一定要限定在http:和https:file:、data:、javascript:、ftp:这些协议一律不允许进入后续流程。4.3 远程状态码探测与超时处理格式校验过了不代表URL真的能打开。批量任务里一个不可达的URL会白白浪费几十秒超时时间所以我在真正调用浏览器之前会先用HTTP HEAD请求探测一次async function probeUrl(url, timeoutMs 5000) { const controller new AbortController(); const timer setTimeout(() controller.abort(), timeoutMs); try { const res await fetch(url, { method: HEAD, redirect: follow, signal: controller.signal, }); return res.ok; } catch (_) { return false; } finally { clearTimeout(timer); } }个别后端服务器不支持HEAD请求会返回404或403这种情况下可以降级为带Range: bytes0-0头的GET请求只取第一个字节就断开连接既能探测连通性又不会下载完整页面。注意这一步探测通过并不代表浏览器里一定能打开。有些页面虽然返回2xx但实际内容是被WAF拦下来的验证页面。所以生产代码里我还会在渲染完成后检查PDF文件大小和页数如果文件只有几百字节或者页数为0直接判定失败走重试或告警。5. 常见报错排查404、502、乱码和空白页实录5.1 404 Not Found八成不是目标网站的问题很多人一看到404就以为是目标网站出问题了但实际排查下来大部分原因是调用方自己出的。最常见的是URL拼接错误。业务方传过来的URL可能带中文参数、带空格、带{}这类特殊字符直接丢给page.goto()会产生各种意外。正确做法是在拼接URL时对所有查询参数做encodeURIComponent而不是对整个URL做编码。另一种情况是重定向丢了。有些URL访问后会302到登录页或新的地址如果服务没有跟随重定向大部分浏览器默认跟随最终结果就可能是404。Playwright的page.goto()返回的response对象会携带最终状态码排查时先把它打印出来response page.goto(url, wait_untildomcontentloaded, timeout30_000) print(response.status, response.url)只看response.url就能知道浏览器最终停在了哪里是重定向到404页还是响应本身404一目了然。还有一种隐蔽的场景页面本身能打开但页面里某个接口404了导致部分区域空白。这种最烦人光看PDF看不出来要把浏览器控制台日志、网络请求日志全部打出来分析page.on(console, lambda msg: print([console], msg.text)) page.on(requestfailed, lambda req: print([failed], req.url, req.failure))5.2 502 Bad Gateway先查本地服务和网关502 Bad Gateway和404完全是两个性质。404至少说明请求到达了目标服务器并得到响应而502说明网关或代理拿不到上游响应通常是上游宕机、启动失败、端口未监听导致的。我在本地调试时遇到过http://127.0.0.1:1572返回502的场景最终定位是后端服务进程没起来。排查第一步永远是确认服务是不是真的在监听curl -v http://127.0.0.1:1572/health如果curl都连不上问题在服务本身不在PDF转换代码。如果curl正常但浏览器访问502那就要查看服务所在层级的访问日志和错误日志确认是不是反向代理配置把某个路径转发错了。批量调用第三方API时遇到502一般需要做重试。重试不能死磕用指数退避第一次1秒、第二次2秒、第三次4秒最多重试3次。如果对方网关持续502大概率是对方服务故障或触发了限流继续重试也没用不如直接告警。5.3 页面空白、乱码、打印不全的经典原因乱码问题大多数是中文字体缺失这个我在前面环境准备部分已经说过这里不再重复。再补充一个容易踩的如果页面用了自定义字体而字体文件是通过懒加载加载的PDF生成时字体可能还没加载完文字会先用默认字体渲染看起来像字体丢失。处理办法是等待字体加载完成page.evaluate(document.fonts.ready)空白页最常见的原因是SPA应用。现在的Web应用入口HTML基本都是空壳内容全靠JavaScript渲染。如果wait_untildomcontentloaded就去生成PDF拿到的就是空白页。解决办法是等关键DOM元素出现page.wait_for_selector(.main-content, timeout15_000)也可以强制滚动页面到底部触发懒加载让所有图片和组件渲染出来page.evaluate(window.scrollTo(0, document.body.scrollHeight)) page.wait_for_timeout(1000)这个技巧在处理无限滚动页面时几乎是必用的不滚动到底部后面一半内容永远是空的。6. 扩展玩法PDF生成后的二次处理6.1 用PyMuPDF提取图片并生成预览PDF生成之后我通常还会做一层“回读校验”手段是直接用PyMuPDF解析生成好的PDF提取文本和图片确认不是空壳。顺带还能做缩略图方便后台快速预览。import fitz # PyMuPDF def extract_pdf_assets(pdf_path, output_dir.): doc fitz.open(pdf_path) print(f总页数: {doc.page_count}) for i, page in enumerate(doc): print(f第{i1}页文本预览: {page.get_text()[:100]!r}) for img in page.get_images(fullTrue): xref img[0] pix fitz.Pixmap(doc, xref) pix.save(f{output_dir}/img_{xref}.png)上面这段就是提取PDF中图片的典型写法。实际业务里我们用它来判断如果PDF里没有任何图片而且文本内容长度是0那说明这次转换大概率失败了需要告警重试。6.2 批量转换的并发控制批量处理多个URL时不要频繁创建和销毁浏览器进程这是性能杀手。正确做法是只启动一个浏览器实例开多个页面并行处理。一个页面处理完关闭再开新页面。同时要注意并发上限我建议并发控制在3到5个页面以内。Chromium很吃内存开多了容易把服务器的内存打满反而更慢。大型批量任务还有一个隐蔽问题长时间运行后就算页面关闭了渲染进程也可能残留。稳妥的做法是每处理几百个URL主动重启一次浏览器实例释放累积的内存碎片。6.3 输出文件命名与存储时的细节从页面标题自动生成文件名时要过滤掉Windows文件系统不允许的字符否则在Windows服务器上直接保存失败const safeName title.replace(/[\\/:*?|]/g, _).slice(0, 80);中文文件名和中文PDF内容本身没有冲突但PDF内部文字如果没有字体嵌入换一台机器打开就可能乱码。Playwright的Chromium在Linux上渲染中文时只要你系统字体装好了它会自动嵌入字体子集基本不用担心这个问题。存储目录建议按日期分目录比如pdfs/2025-06-01/方便任务失败后按日期回查日志和产物。日志里一定要记录输入URL、开始时间、结束时间、状态码、输出文件大小这些在排查疑难问题时能救命。最后补一个我个人的强制习惯所有转PDF任务生成之后必须校验文件大小和页数文件小于1KB或页数为0直接判定失败重试。这个逻辑看起来多余实际上救过我很多次因为有些页面看起来一切正常导出来就是个空壳。如果你也准备在自己的项目里接入类似功能建议从最小闭环开始先拿一个URL手动转到能出PDF再逐渐加批量、并发、重试这些复杂度。坑都是一步步踩出来的越早踩越不痛。本文还有配套的精品资源点击获取