企业官网建设流程全解析

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('<p>Hello, 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 class="pageNumber"></span> / <span class="totalPages"></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 画个框。

想拍移动端效果，就再挂一组deviceMetrics：width、height 写清视口，deviceScaleFactor设 2 能让像素密度翻倍，mobile: true触发移动端模拟。最常见的尺寸翻车原因就是漏了 deviceMetrics——不设置时 Chrome 用默认视口，截出来的图不是你想要的宽。

生产环境怎么连接并稳住 Chrome

生产上让 Chrome 单独常驻，别依赖库每次现起。用 pm2 托管最合适：崩了自动拉起，无头版空闲内存大约 65MB，成本很低。

pm2 start google-chrome --interpreter none -- \ --headless --disable-gpu \ --hide-scrollbars \ --remote-debugging-port=9222

代码侧只需把 options 的 port 写成同一个端口。其余参数按环境裁剪即可，唯一硬性要求是--remote-debugging-port和配置对上。另有一条安全边界：这个库不该接受不可信的用户输入，别让终端用户直接把 URL 传进来。

⚡ 配置速查：关键参数与建议取值

下表只列最常用的几项，没列出的都有默认值，开箱能跑。

⏱️ 页面"准备好了"吗：五种等待机制怎么选

"抢跑"的本质是转换发生在页面就绪之前。先诊断：你的页面慢在哪个环节？环节能说出来，对应的 CompletionTrigger 等待机制就选得出来。

两条常识：一是每个触发器的第二个参数是它自己的超时，默认只有 1000 毫秒，不改很容易撞见 "CompletionTrigger timed out."，所以务必显式写；二是 Variable 默认盯一个叫 htmlPdfDone 的全局变量，你在页面脚本里把数据渲染完把它置为 true，工具侦测到就会继续。页面不落在上面任何一类，也可以继承基类自己写判定逻辑。

🛠️ 生产避坑清单：连接、超时、内存

生产环境最常出的问题都围绕"连接、时间、内存"三件事，合并成一张清单：

• 连接复用：别让库每次生成都现起 Chrome，启动开销远大于一台常驻实例
• 超时档位：简单静态页 5~10 秒、复杂 SPA 30~60 秒、图片密集页 60 秒以上；timeout 管整体时长，触发器的超时管等待时长，两层会叠加
• 内存与缓存：开clearCache避免打印到旧缓存内容；Chrome 定期重启，防止长期运行后内存漂移
• 连不上调试端口：九成是端口没监听或配置写错，先确认再怀疑库；运行中途断连它会抛 ConnectionLostError
• 中文乱码：在 HTML 头部加<meta charset="UTF-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