在现代 Web 开发中，生成 PDF 文档早已超越了“保存文件”这一单一需求，它成为了构建数字化工作流中至关重要的一环。无论是为用户自动生成复杂的电子发票、在金融科技场景中发送合规的系统报告，还是在内容平台上将在线文章保存为精美的离线文档，我们作为开发者都面临着同样的技术挑战：如何将流式、动态的 HTML 内容完美地转换为静态、基于页面的 PDF 格式，同时兼顾性能与成本？
虽然市面上有许多昂贵的 SaaS 服务，但在 Node.js 生态系统中，我们其实拥有非常强大且灵活的本地解决方案。这不仅能降低数据隐私风险，还能让我们更精细地控制渲染细节。今天，我们将深入探讨两种最具代表性的实现方式：基于现代渲染引擎的 INLINECODE5d3b652b 和经典的 INLINECODEdd7becb9。但不仅仅是“怎么用”，我们要站在 2026 年的技术视角，结合现代工程化理念、AI 辅助开发实践，去分析它们的工作原理、配置细节以及在不同业务场景下的最佳实践。
目录
为什么 HTML 到 PDF 的转换并不简单？
在深入代码之前，让我们先拆解一下这个问题的本质。HTML 本质上是一种流式布局语言，它依赖浏览器的渲染引擎进行动态计算，且在不同设备上表现各异；而 PDF 是一种基于页面的固定布局格式，其核心在于精确的分页和排版。将前者转换为后者，涉及到复杂的 DOM 树解析、CSS 规则映射、字体渲染以及最为棘手的分页算法。
因此，选择正确的库至关重要。在我们的技术选型雷达上，这两个库代表了两个时代：
- pdf-creator-node：这是现代的首选方案。其背后依托的是 Puppeteer（Headless Chrome）。这意味着它拥有与 Chrome 浏览器几乎一致的渲染能力，完美支持现代 CSS（Grid、Flexbox、Custom Properties 等）。对于复杂的 UI 还原，它能保证“所见即所得”。
- html-pdf：这是一个较为老牌的库，依赖于 PhantomJS（通过
phantomjs-prebuilt）。虽然它非常轻量，但由于 PhantomJS 已经停止维护，它在处理现代 CSS 特性（如 Grid 布局）时会遇到严重的兼容性问题。
通常情况下，我们强烈推荐优先使用基于 Chromium 的方案。如果你的环境资源极度受限，且 HTML 结构非常简单（比如仅仅是文本堆砌），html-pdf 才是一个备选方案。
方法一：使用 pdf-creator-node 构建稳健的 PDF 系统
pdf-creator-node 不仅仅是一个转换工具，它更像是一个模板引擎。它允许我们利用 HTML 模板生成 PDF，核心优势在于支持复杂的模板语法（如 EJS 或 Handlebars 风格的变量绑定）以及极高的渲染保真度。
准备工作
首先，我们需要初始化一个项目并安装必要的依赖。打开你的终端，执行以下命令：
mkdir node-html-to-pdf-project
cd node-html-to-pdf-project
npm init -y
# 安装核心库
npm install pdf-creator-node fs-extra
注意：pdf-creator-node 依赖于 Puppeteer，因此在首次安装时可能会自动下载 Chromium 二进制文件，这可能需要一点时间，请耐心等待。如果网络环境受限，建议配置国内镜像源。
基础实现：从 HTML 模板到 PDF
让我们从一个最简单的例子开始，模拟我们在实际业务中生成“用户协议”的场景。
第一步：创建 HTML 模板
创建一个名为 template.html 的文件。在我们的实践中，HTML 结构越规范，生成的 PDF 效果就越好。
服务协议
/* 使用 system-ui 保证在各系统下的字体回退机制 */
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
padding: 40px;
color: #333;
line-height: 1.6;
}
.header {
text-align: center;
border-bottom: 2px solid #eee;
padding-bottom: 20px;
margin-bottom: 20px;
}
.content {
background-color: #f9f9f9;
padding: 20px;
border-radius: 8px;
}
.highlight {
color: #007bff;
font-weight: bold;
}
{{title}}
生成日期：{{date}}
尊敬的用户 {{name}}：
感谢您选择我们的服务。本协议由我们于 {{year}} 年制定。
请注意，本文档是由 Node.js 自动生成的。
第二步：编写 Node.js 转换脚本
接下来，我们编写 app.js 来读取这个模板并将其转换为 PDF。
// app.js
const fs = require(‘fs‘);
const pdf = require(‘pdf-creator-node‘);
const path = require(‘path‘);
// 1. 读取 HTML 模板文件
// 使用 __dirname 确保路径的正确性，避免在不同目录运行时出错
const html = fs.readFileSync(path.join(__dirname, ‘template.html‘), ‘utf8‘);
// 2. 准备注入的数据
const data = {
title: ‘用户服务协议 v2.0‘,
name: ‘张三‘,
date: new Date().toLocaleDateString(),
year: new Date().getFullYear()
};
// 3. 配置 PDF 选项
// 这里我们定义了纸张大小、方向以及边距
const options = {
format: ‘A4‘, // 标准 A4 纸张
orientation: ‘portrait‘, // 纵向
border: ‘10mm‘, // 页面边距
// 定义页眉和页脚，这在多页文档中非常实用
header: {
height: ‘20mm‘,
contents: ‘内部机密文件 - 请勿外传‘
},
footer: {
height: ‘10mm‘,
contents: {
first: ‘封面‘,
default: ‘{{page}} / {{pages}}‘, // 动态页码
last: ‘结束页‘
}
}
};
// 4. 定义文档对象
const document = {
html: html, // HTML 源码字符串
data: data, // 注入的数据对象
path: path.join(__dirname, ‘output.pdf‘) // 输出文件的绝对路径
};
// 5. 生成 PDF
// 这是一个异步操作，使用 Promise 处理结果
pdf.create(document, options)
.then((res) => {
console.log(‘PDF 生成成功！‘);
console.log(‘文件保存位置:‘, res.filename);
})
.catch((error) => {
console.error(‘生成 PDF 时出错:‘, error);
});
运行 node app.js，你会看到一个格式规范的 PDF 文件。
进阶技巧：处理复杂布局与分页难题
在实际业务中，我们经常需要处理动态长度的列表，比如生成“订单发票”。这将考验 PDF 引擎对分页和表格的处理能力。让我们思考一下这个场景：如果表格内容跨页，我们不希望某一行被切成两半。
HTML 模板 (invoice.html)
在这个例子中，我们加入了循环逻辑和 CSS 分页控制。
table { width: 100%; border-collapse: collapse; margin-top: 20px; }
th, td { border: 1px solid #ddd; padding: 12px; text-align: left; font-size: 14px; }
th { background-color: #f2f2f2; font-weight: bold; }
.total { text-align: right; margin-top: 20px; font-size: 18px; font-weight: bold; }
/* 关键 CSS：避免表格行在分页处被断开 */
tr { page-break-inside: avoid; }
/* 避免标题单独出现在页面底部 */
h1 { page-break-after: avoid; }
商业发票 #{{invoiceId}}
客户：{{customerName}}
日期：{{invoiceDate}}
商品名称
单价
数量
小计
{{#each items}}
{{this.name}}
¥{{this.price}}
{{this.quantity}}
¥{{this.total}}
{{/each}}
总计: ¥{{totalAmount}}
Node.js 逻辑 (create_invoice.js)
const fs = require(‘fs‘);
const pdf = require(‘pdf-creator-node‘);
const path = require(‘path‘);
const html = fs.readFileSync(path.join(__dirname, ‘invoice.html‘), ‘utf8‘);
// 模拟从数据库获取的复杂数据
const invoiceData = {
invoiceId: ‘INV-2026-001‘,
customerName: ‘未来科技有限公司‘,
invoiceDate: ‘2026-05-20‘,
items: [
{ name: ‘云服务器实例 (xLarge)‘, price: 500, quantity: 12, total: 6000 },
{ name: ‘企业级 SSD 存储‘, price: 200, quantity: 5, total: 1000 },
{ name: ‘CDN 流量包‘, price: 50, quantity: 20, total: 1000 },
{ name: ‘高级技术支持服务‘, price: 1000, quantity: 1, total: 1000 },
// 添加更多项以测试分页效果
{ name: ‘数据库迁移服务‘, price: 300, quantity: 2, total: 600 },
{ name: ‘SSL 证书续费‘, price: 150, quantity: 1, total: 150 }
],
totalAmount: 9750
};
const options = {
format: ‘A4‘,
orientation: ‘portrait‘,
border: {
top: ‘10mm‘,
right: ‘10mm‘,
bottom: ‘10mm‘,
left: ‘10mm‘
},
// 类型定义可以让你的代码在 IDE 中更智能
type: ‘pdf‘,
// 渲染超时设置，对于内容复杂的页面很重要
timeout: 30000
};
const document = {
html: html,
data: invoiceData,
path: path.join(__dirname, ‘output_invoice.pdf‘)
};
pdf.create(document, options)
.then(res => {
console.log(‘发票已生成:‘, res.filename);
})
.catch(err => {
console.error(‘生成失败:‘, err);
});
生产环境下的挑战与工程化实践
在本地跑通 Demo 只是第一步。当我们把这段代码部署到生产环境（特别是 Docker 容器或 Serverless 环境）时，真正的挑战才刚刚开始。
1. 常见问题：字体与图片渲染
你可能会遇到两个经典问题：中文变成方块（乱码），或者图片显示不出来。
- 中文字体乱码：这通常是因为 Linux 基础镜像（如 Alpine）极其精简，默认不包含中文字体。
* 解决方案：不要依赖系统默认字体。在 Dockerfile 中，我们需要显式安装字体包。例如，对于 Alpine 镜像，可以添加 INLINECODE35f6e648。或者在 CSS 中使用 INLINECODEcb07a80e 显式加载 Base64 编码的字体文件，虽然这会增加文件体积，但能保证 100% 的还原度。
- 图片加载失败：如果 HTML 中包含
* 解决方案：最佳实践是将图片转换为 Base64 编码直接嵌入 INLINECODEddf1a659，或者搭建一个简单的本地文件服务器，通过 HTTP 协议（如 INLINECODEc3287a5c）来加载图片。
2. 性能优化：不要阻塞主线程
PDF 生成是 CPU 密集型操作。如果你在处理 HTTP 请求时同步生成 PDF，恶意用户很容易通过发送大量请求拖垮你的服务器。
架构演进（2026 视角）：
在微服务架构中，我们建议将 PDF 生成服务独立出来。即使是单体应用，也应该使用异步任务队列。
- 开发阶段：你可以使用
async/await，但要确保设置合理的超时时间。 - 生产阶段：引入消息队列。当用户请求 PDF 时，Node.js 服务只负责验证权限并生成一个“任务 ID”，然后推送到 RabbitMQ 或 Redis 队列中。后台的 Worker 进程（可以是单独的 Node.js 实例，也可以是专用的微服务）从队列中取出任务，慢慢渲染 PDF，渲染完成后上传至 S3/OSS 并发送邮件通知用户。这种非阻塞的异步模式才是应对高并发场景的唯一正解。
3. 替代方案：Serverless 与 Edge Computing
如果你的应用部署在 Serverless 环境（如 AWS Lambda 或 Vercel），传统的 Puppeteer 方案会遇到严重的冷启动问题（因为启动 Chrome 需要几秒甚至更久）。
在这个场景下，我们可能需要考虑 WASM (WebAssembly) 方案（如 print-pdf）或者直接使用云端无头浏览器服务（如 Browserless）。虽然在 2026 年 WASM 渲染 PDF 还未完全成熟，但对于简单的文档，它提供了极快的启动速度。
方法二：html-pdf 的局限性与适用场景
虽然我们已经推荐了 pdf-creator-node，但在某些边缘计算场景（如树莓派或极度精简的容器）中，几百兆的 Chromium 可能是无法承受的负担。
这时候，html-pdf 依然有一席之地。它基于 PhantomJS，体积小，启动快。
const pdf = require(‘html-pdf‘);
const html = ‘极简报告
这是一个不需要 CSS3 的简单页面。
‘;
const options = {
format: ‘Letter‘,
border: ‘10mm‘
};
// 仅在资源极度受限时使用
pdf.create(html, options).toFile(‘./simple.pdf‘, (err, res) => {
if (err) console.error(err);
console.log(res.filename);
});
警告：如果你发现生成的 PDF 样式错乱（特别是使用了 Flexbox 或 Grid 时），请立即停止使用该库，切换回 Chromium 方案。不要试图在旧引擎上强行模拟现代布局，那是无底洞。
总结：从代码到架构的思考
在这篇文章中，我们探讨了从简单的 API 调用到生产级架构设计的完整路径。选择技术方案时，我们不仅要看它的 API 是否友好，更要看它的底层引擎是否健壮，以及它是否能适应未来的业务变化。
作为开发者，我们的目标是写出可维护、高性能的代码。当你回到项目中面临选择时，可以参考以下决策指南：
- 优先使用 Chromium 方案（如 INLINECODE1bb484c2 或直接使用 INLINECODE185d0b69），它能保证“所见即所得”，减少 90% 的样式调试时间。
- 处理好字体和资源：这是生产环境中最常见的坑，务必在 Docker 镜像中预装字体或使用 Base64。
- 实施异步化：永远不要在请求主线程中同步生成 PDF，拥抱消息队列和微服务。
希望这篇指南能帮助你更好地解决 PDF 生成问题，构建更稳健的应用系统。祝编码愉快！