html-pdf-chrome HTML 转 PDF 实战3 步搞定生产级转换【免费下载链接】html-pdf-chromeHTML to PDF or image (jpeg, png, webp) converter via Chrome/Chromium项目地址: https://gitcode.com/gh_mirrors/ht/html-pdf-chromehtml-pdf-chrome 是一个基于 Chrome 内核把 HTML 转成 PDF 或图片的 Node.js 库。读完全文你就能跑通从安装、连接 Chrome、配置参数到输出第一份生产级 PDF 的完整流程。它解决了什么问题wkhtmltopdf 这类老工具渲染不了现代 CSS3页面一有 JS 就容易排版错乱、内容缺失而 Puppeteer 之类则要拖着整个浏览器框架依赖偏重。html-pdf-chrome 恰好卡在中间它通过 Chrome DevTools Protocol 直接跟真实 Chrome 对话渲染效果和你浏览器里看到的一致依赖却只是轻量的 CDP 客户端。报表、分享图、网页截图凡是HTML 进、成品出的需求都适用。快速上手 先安装npm install --save html-pdf-chrome。再启动一个开着调试端口的 Chrome命令行加上--headless --remote-debugging-port9222然后import * as htmlPdf from html-pdf-chrome; const html h1Hello, world!/h1; const options: htmlPdf.CreateOptions { port: 9222, // 指向正在监听的 Chrome 调试端口 }; const pdf await htmlPdf.create(html, options); // 传入 HTML开始转换 await pdf.toFile(out.pdf); // 把结果保存成文件结果对象还提供了toBuffer()、toStream()、toBase64()怎么交付就怎么取。核心配置拆解CreateOptions 最常用的 4 个参数port/host→ 决定连接去向。填了就连已有的 Chrome两个都不填库会临时起一个 Chrome 跑完即弃适合跑通 demo生产环境请常驻 Chrome 并固定port: 9222找不到默认路径时再补chromePath。printOptions→ PDF 输出的所有旋钮透传给 Chrome 的printToPDF横竖版是landscape页眉页脚要displayHeaderFooter: true配合headerTemplate/footerTemplate模板里可用pageNumber、totalPages占位符纸张和边距由paperWidth、paperHeight、marginTop等控制单位是英寸。screenshotOptions→ 有它就切换成出图而非 PDFformat支持png、jpeg、webpjpeg 可加qualityclip指定裁剪区域。它通常和deviceMetrics搭配——先用width、height、deviceScaleFactor定义视口截图再按视口裁剪。completionTrigger→ 决定页面什么时候算就绪。最常用的是new htmlPdf.CompletionTrigger.Timer(3000)等 3 秒、Element(#app-loaded)等元素出现、LifecycleEvent(networkIdle)等网络空闲。它和timeout: 60000配合使用触发器管何时开始总超时装最慢多久坏页面不会拖死服务。两个真实场景场景一转一个带鉴权的在线报表create的第一个参数除了 HTML 字符串也接受 URL。报表页需要登录态那就把凭证放进请求头const options: htmlPdf.CreateOptions { port: 9222, extraHTTPHeaders: { Authorization: Bearer your-token }, printOptions: { printBackground: true, marginTop: 0.5 }, completionTrigger: new htmlPdf.CompletionTrigger.Timer(2000), timeout: 60000, }; const pdf await htmlPdf.create(https://report.example.com/monthly, options); await pdf.toFile(report.pdf);这里的关键是extraHTTPHeaders会随该页所有请求发出服务端鉴权能过PDF 才能拿到和浏览器里一样的数据。场景二SPA 异步渲染完成前抢跑截图单页应用数据是异步拉取的load 之后立刻出图只能截到骨架屏。让页面自己声明我好了const options: htmlPdf.CreateOptions { port: 9222, // 等页面脚本把全局变量 dataReady 置为 true completionTrigger: new htmlPdf.CompletionTrigger.Variable(dataReady, 10000), screenshotOptions: { format: png, clip: { x: 0, y: 0, width: 800, height: 600 } }, }; const shot await htmlPdf.create(/app/summary.html, options); await shot.toFile(summary.png);这里的关键是Variable触发器把渲染完成的判断权交还给页面本身比固定等几秒更稳而且到 10 秒不满足会直接抛超时异常不会静默挂死。踩坑与对策 ⚠️症状PDF 内容缺失页面动态数据没加载出来 →处理别等 load 就出图加一个completionTriggerElement / Variable / LifecycleEvent 均可等真实渲染完成。症状create 卡住或抛连接错误 →处理确认 Chrome 用--remote-debugging-port跑着且传入的port一致想省事就port留空让库自己临时启动 Chrome。症状批量生成越跑越慢、内存持续上涨 →处理用 pm2 这类进程管理器让 Chrome 常驻并定期重启进程避免每次冷启动和长期累积泄漏。另外记住官方提醒这个库不接受不可信的用户输入直接把用户提交的 URL 喂进去等于把 SSRF 大门敞开。html-pdf-chrome 把 HTML 转 PDF 变成一行调用完整参数说明见 src/CreateOptions.ts卡住了就去翻它。【免费下载链接】html-pdf-chromeHTML to PDF or image (jpeg, png, webp) converter via Chrome/Chromium项目地址: https://gitcode.com/gh_mirrors/ht/html-pdf-chrome创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
