大部分前端 PDF 生成库只能在浏览器里运行，遇到服务端导出需求就不得不引入 Puppeteer 之类的无头浏览器，开销大、部署重。dompdf.js 的 WASM 内核与纯前端架构让它在 Node.js 环境同样可用：不需要浏览器进程，不需要系统级依赖，代码里判断环境、按需加载，同一个导出模块浏览器与服务端都能跑，一套代码两端复用。本文从环境判断与同构代码设计讲起，给出 Node 环境下 wasm 与 Worker 的加载注意事项，再演示 Express 导出接口的完整实现，接着讨论性能、并发与缓存策略，最后对比无头浏览器方案并总结常见问题，帮助你在服务端把 PDF 导出做成稳定的基础能力。
传统服务端 PDF 方案，比如无头浏览器截图，需要维护一个浏览器进程池，内存占用动辄几百 MB，部署环境复杂，冷启动慢，进程还要定期重启防止泄漏。dompdf.js 是纯计算型库：WASM 内核直接执行排版与编码，不需要 DOM 渲染环境，Node 里加载后即可调用，资源开销小一个数量级，这使它成为服务端导出极具吸引力的选择。
与 Puppeteer 相比，dompdf.js 没有浏览器进程可管理，也就没有进程崩溃、僵尸进程、并发受限这些运维问题；生成速度上，WASM 直出 PDF 比截图再编码快得多，千页文档的差距从分钟级缩小到秒级。对导出量大、要求稳定的后台服务，这个优势会直接转化为更低的机器成本与更少的线上告警，运维同学也会轻松很多。
还有一个工程上的好处：同一套模板与代码，浏览器端与 Node 端共用，行为一致、维护单一。前端预览用浏览器路径，服务端归档用 Node 路径，差异只在环境适配层，业务逻辑零重复，这是同构架构最实在的收益，模板的改进两端同时生效，不需要维护两份实现。
同构导出的关键是环境适配：浏览器环境调用 DOM 相关能力，Node 环境走服务端路径。封装一个统一的导出函数，内部用环境判断选择实现，对外暴露同一接口；业务代码只调用这个函数，不关心运行环境，这是同构代码的标准形态，示例里的 isServer 判断就是这条分界线的具体落点。
服务端导出接口要处理的工程问题包括：请求校验，HTML 内容大小限制、参数白名单；超时控制，大文档导出设超时并返回友好错误；限流，防止恶意请求耗尽 CPU。示例里给出了超时与错误处理的最小骨架，接口内部串行执行导出，避免并发挤压，实际部署时再按业务量补充限流与鉴权。
接口层的关键是让错误可见：导出失败返回结构化错误码，日志里记录耗时与失败原因，监控面板能直接看到导出成功率与耗时分布。把耗时超过阈值的请求单独告警，性能退化第一时间暴露，而不是等用户投诉；内容校验是安全底线，服务端接收的 HTML 可能来自不可信来源，限制大小、过滤危险内容，防止导出接口被滥用为资源消耗攻击。
// pdf-service.js —— 同构导出模块
import { DomPDF } from 'dompdf.js';
const isServer = typeof window === 'undefined';
export async function exportPdf(html, options = {}) {
const pdf = new DomPDF();
pdf.addPage(html, { format: options.format || 'A4' });
// 浏览器端：save 触发下载；服务端：由响应层处理输出
return pdf.save(options.filename || 'output.pdf');
}
// server.js —— Express 导出接口
import express from 'express';
import { exportPdf } from './pdf-service.js';
const app = express();
app.use(express.json());
app.post('/api/export-pdf', async (req, res) => {
try {
const { html } = req.body;
if (!html || html.length > 500000) {
return res.status(400).json({ error: '内容为空或过大' });
}
const timeout = setTimeout(() => res.status(504).end(), 30000);
const output = await exportPdf(html, { filename: 'report.pdf' });
clearTimeout(timeout);
res.setHeader('Content-Type', 'application/pdf');
res.setHeader('Content-Disposition', 'attachment; filename="report.pdf"');
res.send(output);
} catch (error) {
res.status(500).json({ error: String(error) });
}
});
app.listen(3000, () => console.log('export server on :3000'));Node 加载 dompdf.js 时，wasm 文件的读取方式与浏览器不同：浏览器用 fetch，Node 用文件系统读取或直接内联。库的 ESM/CJS 双格式在 Node 下都能正常导入，动态 import 可以让库在第一次导出请求时才加载，服务启动速度不受影响，内存占用也更低，这是服务端集成的第一个性能优化点。
Worker 方面，Node 的 worker_threads 与浏览器 Worker 是两套机制。dompdf.js 的浏览器管线依赖 Web Worker，在 Node 环境如果不需要并行导出，可以直接在主线程调用，省去线程管理；需要并发时再评估 worker_threads 的接入成本，多数服务端导出场景单线程串行已经足够快，不必为了并发而引入复杂度。
版本与运行时要求要提前确认：Node 的版本要满足库的运行时要求，wasm 支持在现代 Node LTS 上默认开启。部署到 Docker 等容器环境时，确认镜像包含必要的系统库，wasm 在纯计算模式下对系统依赖极少，容器化通常无障碍，镜像体积也不会因为引入浏览器而膨胀，部署体验比无头浏览器方案轻得多。
服务端导出性能的第一杠杆是缓存：相同模板与数据的导出结果可以缓存，重复请求直接返回缓存文件，命中率高的场景吞吐提升一个数量级。缓存键用内容哈希，模板或数据变化自动失效，实现简单、收益直接，对报表、发票这类内容高度重复的导出场景尤其有效，值得第一优先级落地。
并发策略上，Node 单进程内导出任务建议串行或小并发：WASM 计算吃 CPU，并发过高反而互相拖慢，吞吐不升反降。横向扩展用多进程或多实例，配合负载均衡，比单进程内疯狂开线程更可控；压测找到单实例的最优并发数，写入部署文档，容量规划就有了数据依据，线上扩容也有的放矢。
流式处理是进阶优化：超长文档分段渲染，边生成边写响应流，客户端首字节时间显著缩短。配合内容分块与进度上报，服务端导出也能有良好的用户体验；实现复杂度略高，适合导出频率高、文档特别长的系统，普通规模的导出任务先用缓存加串行就足够，不必过度设计。
无头浏览器方案的优势是渲染与浏览器完全一致，适合高度依赖 JS 动态渲染的页面；代价是资源开销大、运维复杂。dompdf.js 适合内容以 HTML/CSS 静态结构为主的文档，模板可控、渲染快、部署轻。选型的判断标准是：页面是否需要完整执行 JavaScript 才能呈现内容，需要就选无头浏览器，不需要就选 dompdf.js。
混合方案也常见：页面预览用浏览器端导出，归档批量任务用 Node 端导出；或简单文档用 dompdf.js，复杂交互页面才动用无头浏览器。两条链路共存时，把模板管理统一起来，同一份 HTML 模板两个环境都能渲染，维护成本最低，模板的版本管理也只需要一份。
最后是成本视角：无头浏览器的常驻进程与内存开销是持续性的云成本，dompdf.js 按需计算、用完即释放，服务端导出量大时成本差异显著。把两种方案各跑一轮基准，相同文档、相同机器，用数据决定架构，比经验判断更可靠，选型报告里有两组实测数据，说服力完全不同。
Q: 服务端导出时字体或图片缺失？A: 快照里的资源引用要用绝对 URL 或已内联的数据，服务端没有浏览器的相对路径解析环境；字体文件提前下载到本地或内联，图片用完整地址，导出前验证一遍资源可达性，问题即可避免。
Q: 并发导出时服务响应变慢？A: 检查是否并发过高：先用串行加缓存稳住基础吞吐，再按压测数据逐步放开并发；观察 CPU 与内存曲线，接近瓶颈就扩容实例，而不是在单进程内无限堆并发，方向正确了优化才有效。
最佳实践小结：同构代码统一封装、环境判断隔离差异；动态 import 按需加载；接口层做校验、超时、限流与结构化错误；缓存优先、串行起步、压测扩容；资源引用全部绝对化。按这几条执行，Node 端 PDF 导出就能稳定、高效、可观测，成为团队可信赖的基础能力。
下面的按钮用 dompdf.js 在浏览器端实时生成 PDF，无需后端：
这是由 dompdf.js 渲染的示例 PDF 内容。