html-pdf-chrome把网页直接变成 A4 PDF 和高清截图【免费下载链接】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/Chromium 内核的 HTML 转 PDF 与网页截图工具走 Chrome DevTools Protocol 驱动浏览器渲染结果和浏览器里看到的一致。读完你能带走最短可跑通的配置、常见场景的参数写法以及上生产的几个坑。三步跑通第一份 PDF整个流程就三件事连上浏览器、指定输出、卡个超时。连接方式上host/port都不设时工具会临时拉起一个 Chrome任务跑完自动杀掉要复用常驻实例就填上它的调试端口。输出目标上传 HTML 字符串或直接传 URL 都行拿到的结果可以toFile、toBuffer、toStream。最后用timeout毫秒兜底防止页面卡死时任务挂起。import * as htmlPdf from html-pdf-chrome; const pdf await htmlPdf.create(h1你好/h1, { port: 9222, timeout: 30000 }); await pdf.toFile(out.pdf); 报表场景设置纸张尺寸与边距做发票、对账单这类文档核心在printOptions。纸张单位是英寸A4 就是 8.27×11.69landscape: true切横向。边距四个方向各一个字段页眉页脚要先开displayHeaderFooter模板里用pageNumber、totalPages这类 class 名注入动态值。还有一个容易踩的坑CSS 背景色默认不打出来必须显式开printBackground。const pdf await htmlPdf.create(html, { port: 9222, printOptions: { paperWidth: 8.27, paperHeight: 11.69, printBackground: true, marginTop: 0.5, marginBottom: 0.5, displayHeaderFooter: true, footerTemplate: div第 span classpageNumber/span 页/div, }, }); 网页截图格式、质量与移动模拟传了screenshotOptions就走截图分支格式支持 png、jpeg、webpquality只对 jpeg 生效clip可以只截取页面的一块区域。想要高清图靠deviceMetricswidth/height决定视口大小deviceScaleFactor: 2出两倍像素的图mobile: true模拟触摸设备方便截移动端页面。const img await htmlPdf.create(url, { port: 9222, screenshotOptions: { format: png, clip: { x: 0, y: 0, width: 800, height: 600 } }, deviceMetrics: { width: 375, height: 667, deviceScaleFactor: 2, mobile: true }, }); await img.toFile(shot.png);⏱️ 选对页面加载等待机制原则一句话先看你的页面是怎么加载的再选等待方式别无脑死等定时器。所有触发器都带超时参数等不到就整体失败这比拿到半张图好排查。触发器什么时候用它LifecycleEvent等网络静默如networkIdle适合请求多的页面Element等某个元素出现在 DOM 里Event等自定义事件触发Variable页面 JS 把全局变量置为trueTimer没有明确信号时的保底completionTrigger: new htmlPdf.CompletionTrigger.LifecycleEvent(networkIdle, 10000)完整清单见源码 src/CompletionTriggers/ 目录也可以继承基类写自定义触发器。认证头、Cookie 与调试回调页面需要登录态时extraHTTPHeaders负责给请求挂 token 等头部cookies负责注入会话 Cookiename、value、domain 等字段。调试期最实用的是两个回调runtimeConsoleHandler把浏览器控制台输出转出来runtimeExceptionHandler接住页面未处理异常——PDF 内容不对劲时先看这两个有没有报错。const options { port: 9222, extraHTTPHeaders: { Authorization: Bearer xxx }, cookies: [{ name: sid, value: abc, domain: .example.com }], runtimeExceptionHandler: (e) console.error(页面异常, e), };上生产的 3 个要点实例复用。用 pm2 之类让 Chrome 常驻启动参数加--remote-debugging-port代码里填这个端口。每次调用都冷启动 Chrome 的开销远大于复用一个闲置实例后者空闲大约只占 65MB 内存崩了还能被进程管理器拉起。超时分级设置。timeout别一刀切静态文档 5–10 秒足够重型 SPA 给 30–60 秒。给大了排障慢给小了误杀任务。缓存与内存。对缓存敏感的任务开clearCache: true生成前清浏览器缓存避免拿到旧内容。另外别并发压太多任务定期重启 Chrome 进程长期跑更容易出内存问题。高频问题连不上 Chrome—— 确认 Chrome 已带--remote-debugging-port启动且代码里的端口与之一致两个都没配则会自行拉起临时实例。PDF 中文乱码—— 在 HTML 头部加上meta charsetUTF-8并确保传入的字符串本身按 UTF-8 处理。页面渲染不完整—— 多半是等待不足就截了图换成更贴切的completionTrigger比如LifecycleEvent(networkIdle)而不是只靠默认的 load。全部参数的类型定义和注释都在 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），仅供参考
