html-pdf-chrome 实战指南HTML 转 PDF【免费下载链接】html-pdf-chromeHTML to PDF or image (jpeg, png, webp) converter via Chrome/Chromium项目地址: https://gitcode.com/gh_mirrors/ht/html-pdf-chrome导出的 PDF 排版总跑版、截图脚本总抢跑页面加载html-pdf-chrome 是一款基于无头 Chrome 渲染的 HTML转PDF 工具把一段 HTML 或一个 URL 交给真实的 Chrome 内核输出 PDF 或 PNG/JPEG/WebP 图片接口全量 TypeScript 标注。 快速上手最小配置完成第一次转换最短路径指到一台已经跑着的 Chrome 的端口传进 HTML调toFile落盘。如果你完全不给 host 和 port它会自动拉起一个 Chrome、用完即杀——适合一次性尝鲜但每次启动都有固定开销不适合放进生产链路。import * as htmlPdf from html-pdf-chrome; const options: htmlPdf.CreateOptions { port: 9222 }; const pdf await htmlPdf.create(pHello, world!/p, options); await pdf.toFile(test.pdf);生成后直接打开文件先确认链路通了再谈调参。返回的 CreateResult 还能用toBase64()、toBuffer()、toStream()转换后面要过 HTTP 时Buffer 或 Stream 更方便。 按场景使用三种任务各改哪几个参数不同任务只是在同一个 CreateOptions 配置对象上多改两三个参数下面的三节各对应一个具体任务。报表怎么印成带页眉页脚的正式 PDF正式文档看三样纸张、边距、页码。landscape切横竖排paperWidth/paperHeight定纸型单位是英寸四个 margin 管四边留白。要页码就得先把displayHeaderFooter打开再给页眉页脚写模板——模板里用date、title、url、pageNumber、totalPages这几个 class 名占位Chrome 打印时会自动替换需要 Chrome 65 及以上。一个坑模板里的图片必须 base64 内联外部路径不会生效。const options: htmlPdf.CreateOptions { port: 9222, printOptions: { displayHeaderFooter: true, footerTemplate: span classpageNumber/span / span classtotalPages/span, paperWidth: 8.5, paperHeight: 11, marginTop: 0.4, marginBottom: 0.4, marginLeft: 0.4, marginRight: 0.4, }, };只打印特定区间时用pageRanges写1-5这类范围scale用来整体微调内容大小。网页怎么拍指定尺寸、移动端的截图只要配置里带上screenshotOptions输出就从 PDF 变成图片不写 format 默认 png。要 jpeg 或 webp 就显式指定jpeg 可以配quality控压缩。想只截页面的一部分用clip给 x、y、width、height 画个框。想拍移动端效果就再挂一组deviceMetricswidth、height 写清视口deviceScaleFactor设 2 能让像素密度翻倍mobile: true触发移动端模拟。最常见的尺寸翻车原因就是漏了 deviceMetrics——不设置时 Chrome 用默认视口截出来的图不是你想要的宽。生产环境怎么连接并稳住 Chrome生产上让 Chrome 单独常驻别依赖库每次现起。用 pm2 托管最合适崩了自动拉起无头版空闲内存大约 65MB成本很低。pm2 start google-chrome --interpreter none -- \ --headless --disable-gpu \ --hide-scrollbars \ --remote-debugging-port9222代码侧只需把 options 的 port 写成同一个端口。其余参数按环境裁剪即可唯一硬性要求是--remote-debugging-port和配置对上。另有一条安全边界这个库不该接受不可信的用户输入别让终端用户直接把 URL 传进来。⚡ 配置速查关键参数与建议取值下表只列最常用的几项没列出的都有默认值开箱能跑。参数作用建议取值host / port连接 Chrome 调试端口的地址两者都不填则自动拉起指向常驻实例的 9222chromePath自动拉起时指定 Chrome 可执行文件路径系统默认即可找不到再填chromeFlags自动拉起时的启动参数默认已含无头、禁 GPUprintOptionsPDF 打印选项核心纸张、四边边距、页眉页脚报表类四边边距都写全screenshotOptions截图格式、质量、裁剪范围默认 png需压缩用 jpeg qualitydeviceMetrics模拟设备宽高与移动端模式移动端给 mobile: true deviceScaleFactor: 2completionTrigger转换前的等待条件看页面特性见下一节timeout整体超时毫秒到点报错退出复杂页面给 30000clearCache加载前清空 Chrome 缓存内容不确定就置 truecookies注入页面的 Cookie登录态页面必配extraHTTPHeaders随请求附带的 HTTP 头带 Authorization 等鉴权用runtimeConsoleHandler / runtimeExceptionHandler接收页面 console 消息与未捕获异常的回调生产环境建议都接上落日志⏱️ 页面准备好了吗五种等待机制怎么选抢跑的本质是转换发生在页面就绪之前。先诊断你的页面慢在哪个环节环节能说出来对应的 CompletionTrigger 等待机制就选得出来。慢在哪个环节用这个写法示例渲染时长不确定但两三秒内总能好Timernew CompletionTrigger.Timer(3000)内容要等某个元素出现在 DOM 里Elementnew CompletionTrigger.Element(#app, 5000)页面自己会在完成时派发自定义事件Eventnew CompletionTrigger.Event(ready, #app, 10000)只需网络与渲染都平息下来LifecycleEventnew CompletionTrigger.LifecycleEvent(networkIdle)JS 会在页面里置一个全局变量表示完成Variablenew CompletionTrigger.Variable(pageLoaded, 8000)两条常识一是每个触发器的第二个参数是它自己的超时默认只有 1000 毫秒不改很容易撞见 CompletionTrigger timed out.所以务必显式写二是 Variable 默认盯一个叫 htmlPdfDone 的全局变量你在页面脚本里把数据渲染完把它置为 true工具侦测到就会继续。页面不落在上面任何一类也可以继承基类自己写判定逻辑。️ 生产避坑清单连接、超时、内存生产环境最常出的问题都围绕连接、时间、内存三件事合并成一张清单连接复用别让库每次生成都现起 Chrome启动开销远大于一台常驻实例超时档位简单静态页 5~10 秒、复杂 SPA 30~60 秒、图片密集页 60 秒以上timeout 管整体时长触发器的超时管等待时长两层会叠加内存与缓存开clearCache避免打印到旧缓存内容Chrome 定期重启防止长期运行后内存漂移连不上调试端口九成是端口没监听或配置写错先确认再怀疑库运行中途断连它会抛 ConnectionLostError中文乱码在 HTML 头部加meta charsetUTF-8多数乱码是编码没声明结语最短路径是先跑通上面的示例、确认端口能连、文件能生成再去 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），仅供参考
