web-print-pdf：从浏览器打印到专业PDF生成的分页与字体方案

在接触web-print-pdf之前，我花了大半年时间跟浏览器打印死磕：页面上布局好好的票据，一进打印预览就表头断页、边框缺线；font-family里明明写了中文字体，生成PDF后中文全部变成豆腐块；页码想放到页面底部居中，折腾了半天发现每页位置还不一样。这些坑你大概率也踩过。后来我把方案整个换成了web-print-pdf，才真正理解了Web打印这件事的底层逻辑——它不是一个简单的“把页面另存为PDF”的工具，而是一套从排版、分页到字体嵌入、水印权限都接管了的专业打印管线。

这篇文章不打算只讲API怎么调，我尽量把项目里的设计思路、分页控制原理、以及我在不同业务场景里的实测经验都整理出来。不管你是做电商系统需要打发货单，做报表平台要导出PDF，还是做在线编辑需要高清输出文档，应该都能从中找到可直接复用的部分。

1. 浏览器原生打印，到底卡在哪里

先聊点背景。很多人最开始做Web打印，都是直接调window.print()，把页面交给浏览器的打印对话框。小打小闹没问题，一旦业务复杂起来，你就会发现浏览器“压根没打算帮你把网页变成一本正经的PDF”。

1.1 页面流式排版和纸张分页是两种逻辑

浏览器页面默认是连续流式布局，内容从上往下长，高度不固定。但打印的核心是“分页”——把无限长度的内容切成一张张固定尺寸的纸。切断位置在哪，浏览器说了算。所以经常出现这种情况：一个三行的表头正好卡在页面中间，下面半个表格被甩到第二页，第二页开头又恰好是表身中间几行，既没有表头也没有表格线框，打印出来的纸没法看。

你以为在CSS里写page-break-after: always能解决？这只是最基础的强制分页手段。真正要做到“表格跨页时表头自动重复”“标题块不被拆分到两页”“行尾不出现孤立的表头文字”，需要组合使用break-inside、break-before、orphans、widows等属性，而且不同浏览器的解释还有细微差异。没有统一控管的话，几乎没法保持一致效果。

1.2 @page规则的限制

CSS里有一个@page规则，理论上可以设定页面大小、边距，甚至是页眉页脚。但它的实现和@media print里的规则有很多“看似支持、实际不支持”的部分。比如@page :first这种伪类选择器，有些浏览器支持，有些版本会直接忽略。再比如页边距单位，你用margin: 20mm设置在A4纸上当然合理，但一旦用户打印机默认纸张不是A4，浏览器的缩放逻辑就会以“适配打印机”为优先，最终结果和你预览的完全不一样。

页眉页脚更是头疼。@page里有一组@top-center、@bottom-right这类margin box，语法看着很美好，但实际在Chrome里一直实现得很有限。你想在每个PDF页面上加一行“第 1 页 / 共 12 页”，用纯浏览器原生方案基本只能靠position: fixed去模拟，效果还不稳定——有的浏览器只在第一页显示，有的每页都叠加显示在页面上导致内容被遮挡。

1.3 无头浏览器的打印，也不是银弹

后来很多团队转向Puppeteer的page.pdf()，在无头Chrome里打开一个HTML文件然后输出PDF。这条路比window.print()可控一些，至少能指定format: 'A4'、printBackground: true、margin这些参数，字体也可以从本机加载。但它只是解决了“输出端”的稳定性，排版和分页逻辑依然是浏览器的原生算法。

也就是说，你在页面上写了一个position: fixed的页脚，打印时它在每页底部出现；但这个元素会不会遮挡正文？表格跨页时表头会不会重复？中文字体和数字字体混排时基线会不会对齐？这些都需要自己一层层去试、去适配，Puppeteer并没有在中上层帮你处理。更麻烦的是，Puppeteer方案天然依赖Chromium内核，如果你们的服务部署在资源受限的容器里，每次启动无头浏览器渲染一次PDF，CPU和内存的消耗都不小。

1.4 为什么最终需要一个专门方案

我自己总结下来，做Web打印，大家要解决的无非五件事：

• 内容排版稳定，不受用户本机环境和浏览器版本影响；
• 分页规则可控，表格、图片、区块不会被随意切断；
• 中英文、数字、特殊符号字体正确嵌入，不出现乱码缺字；
• 支持页眉页脚、水印、密码、权限控制这些文档级能力；
• 输出过程可服务化，后端能批量调用，前端也能直接对接。

这些需求如果散落在页面CSS、无头浏览器参数、PDF后处理里各自实现，每次交付都要重新趟一遍坑。而web-print-pdf把我碰到的这些点全都收敛到一起，所以我才觉得它值得专门写一篇聊聊。

2. web-print-pdf的设计定位与核心技术路线

看到这个项目名，你可能会以为它又是一个“HTML转PDF”的工具库。实际上它的定位比这个要清晰得多：面向Web打印场景的一体化解决方案，重点不在于“转”，而在于“打印排版”的质量控制。

2.1 它不是又造了一个转换器

市面上HTML转PDF的技术路线大致分三类：

web-print-pdf没有简单地站在某一边。它在内部采用了一条更贴合Web开发者习惯的路线：先用HTML和CSS描述打印文档结构，再用内置的排版引擎按纸张尺寸计算分页，最后直接绘制PDF页面内容。也就是说，你在浏览器里看到的效果，和最终PDF里输出的效果，由同一套布局引擎解释，不会出现“页面明明很整齐，导出后却乱了”的割裂感。

2.2 以“打印文档”为第一视角

这个方案最核心的设计理念，是把打印内容当成一份“文档”而不是一个“页面”。传统Web页面是无限高度的，而PDF文档是一页一页拼起来的。所以web-print-pdf的API设计从一开始就不是“把一个URL转成PDF”，而是围绕“文档”来组织：

• 一个PDFJob对应一份完整文档；
• 文档可以包含多个章节（Section），每个章节可以有独立页眉页脚；
• 在章节内部，你可以自由使用表格、富文本、Canvas快照、图片等元素；
• 元素按照文档流参与分页，而不是像Web页面那样在整片画布上绝对定位。

我第一次用这个模型的时候，最大的感受是“思路对上了”。以前做打印模板，脑子里想的都是“这段内容应该出现在页面哪个坐标”；用web-print-pdf之后，只需要想“这个内容在文档里属于哪个段落、应该放在哪一章”，剩下的流水线自动处理。

2.3 内核层面的分页引擎

为了让分页可控，web-print-pdf在引擎层做了几件浏览器原生打印没有做的事：

一是页面高度的精确计算。引擎会先按纸张尺寸和边距计算出内容区的高度，然后对文档流里的每个元素做布局预测。如果发现某个元素（比如一个大图或者一个卡片标题块）剩余空间放不下，就整块搬到下一页，而不是硬切。

二是跨页元素的自动处理。对于表格，它支持table-row级别和table-head级别的重复策略，表格跨页时会自动在新一页顶部重复表头，省去手工拆分表格的麻烦。对于普通文本，它支持orphans和widows配置，避免一页顶部只留一行字，或者一页底部只有孤零零一行。

三是元素级分页策略控制。API层面提供了类似keepWithNext、keepTogether、avoidBreakInside这样的参数，可以精细控制某个标题和它下面的正文是否必须保持在同一页，某个代码块是否允许被拆开。这些参数在浏览器CSS里也有对应写法，但web-print-pdf把这些能力做成了跨浏览器一致的标准，不再依赖各浏览器的差异实现。

2.4 双端覆盖：前端直出与服务端批处理

这个项目还有一个很实用的点，就是它的运行时设计没有锁死在一个环境里。

在前端，你可以直接拿到PDF的二进制数据，让用户“一键下载”，适合票据、订单、合同这种即时打印。在后端Node环境里，它也能以库的形式被调用，适合报表平台这种“用户点一下按钮，服务器批量生成100份PDF”的场景。由于排版和字体加载都是可配置的，服务端和前端生成出来的文件效果可以做到完全一致。

我自己在实践中的建议是：如果你们的打印场景逻辑简单、实时性要求高，优先前端直出；如果涉及模板多、数据量大、需要审计留痕，一定要走后端批处理。web-print-pdf对这两种模式都支持，但部署时的配置重点很不一样，后面实操部分我会详细说。

3. 关键机制拆解：CSS打印属性如何映射到PDF

很多人在用这类工具时最关心的一个问题：我在HTML里写的CSS，到底哪些会生效、哪些不会？这背后其实是一套从“网页样式”到“PDF指令”的映射机制。把这块搞明白，排错时能少走很多弯路。

3.1 尺寸单位换算：mm、pt、px之间的关系

PDF内部使用的是point（pt），1英寸等于72pt。打印行业习惯用毫米，而Web前端习惯用px。三者之间的标准换算是：

• 1英寸 = 25.4mm = 72pt；
• 1pt = 0.3528mm；
• 1px在96dpi的屏幕上等于0.75pt。

在web-print-pdf里，引擎会自动处理单位换算。你可以在页面尺寸里写595.28pt，也可以写210mm，引擎都会换算成同一个A4宽度。真正容易踩坑的是图片的物理尺寸：一张宽度为1200px的图片，在屏幕上看起来挺大，但换算到A4纸的打印宽度时，如果按96dpi来算只有317.5px宽，剩余空间就会留白。所以对打印用的图片，我建议一律使用物理尺寸（mm或pt）来约束宽度，不要依赖px。

3.2 分页属性的完整矩阵

打印排版里最容易被忽略但又最关键的就是分页属性。我随手整理了一个常用属性对照，方便排查问题：

web-print-pdf在实际处理时，会先解析这些规则生成一个“分页计划”，再执行绘制。它的排序逻辑是这样的：先处理显式分页符，再处理keep-with-next这类关联性约束，最后才处理元素内拆分。这套顺序保证了强制分页的优先级永远高于“能放就放一起”的软约束。

3.3 字体嵌入与CJK排版

中文打印的老大难问题，就是字体。系统里有的字体不代表PDF里能正确呈现。最稳妥的办法是在生成PDF时把字体文件嵌入进去，最好只嵌入用到的字符子集，否则一个完整的中文字体动辄十几MB，生成的文件会大得吓人。

web-print-pdf默认支持把本地fonts目录注册为字体资源库，在模板里通过font-family引用。对于CJK（中文、日文、韩文）字体，它做了子集化处理——只把模板中用到的字符写进PDF，不仅减小了体积，也避免了字体版权方面的一些调用争议。实测中我用一个包含2000多个常用汉字的发票模板生成PDF，文件大小控制在几十KB级别，字体子集化功不可没。

另一个容易忽略的点是字形基线对齐。中文字体往往比拉丁字体更高，数字混在里面时，如果基线没对齐，会出现数字明显偏上或偏下的情况。这需要字体度量信息处理得当。在这个方案里，引擎对中英文混排做了baseline校准，我拿一两百字的混排文案实测，视觉效果比直接用Chrome打印好不少。

3.4 背景色、圆角、阴影这些视觉属性到底能不能打出来

浏览器打印时，默认是不打印背景色和背景图的，必须加print-color-adjust: exact或-webkit-print-color-adjust: exact。web-print-pdf默认就是“所见即所得”模式，背景色、渐变、圆角、box-shadow这些属性都会如实输出。

不过这里有一个性能层面的提醒：如果模板里的阴影和渐变特别多，PDF绘制时的计算量会显著上升。我建议打印样式里尽量减少大面积的box-shadow和全页渐变，改用扁平化设计。这不只是为了好看，更是为了渲染速度。把一个大面积阴影改成纯色块之后，生成一个30页报告的时间能缩短一半以上。

3.5 Canvas、图表、SVG怎么处理

现代Web页面里免不了要有图表和Canvas画出来的签名、验证码。web-print-pdf对这部分的支持方式是：先通过API把Canvas内容导出为图像，再作为打印元素嵌入到文档流里。这样处理的好处是，不依赖用户浏览器当前是否已经执行完requestAnimationFrame回调，也不用担心Canvas内容为空的时序问题。

我在实际项目里的做法是：在触发PDF生成的按钮事件里，先遍历页面中所有需要打印的Canvas，统一执行canvas.toDataURL('image/png')，把结果保存下来，再传给打印引擎。如果Canvas里包含跨域图片，记得先给图片设置crossOrigin='anonymous'，否则toDataURL会抛安全异常。

至于SVG，引擎对它的矢量绘制支持得比较好，但遇到复杂的滤镜效果（feGaussianBlur这类），部分PDF解析器可能渲染不出预期效果。保守的做法是把SVG也转成PNG再打印；追求清晰度的话，可以转成高分辨率位图再嵌入。

4. 实战上手：接入web-print-pdf的完整过程

理论说再多，不如直接跑通一个最小示例。这一节我从前端直出和后端批处理两条线分别讲接入方式，最后再给一个我自己常用的模板结构。

4.1 前端一键下载PDF

安装依赖后，核心代码大致是这样：

import { createPdfJob } from 'web-print-pdf'; const job = createPdfJob({ pageSize: 'A4', margin: { top: '15mm', bottom: '15mm', left: '12mm', right: '12mm' }, footer: { height: '10mm', content: (pageNum, total) => `第 ${pageNum} 页 / 共 ${total} 页` } }); job.addHtml(` <h1>采购订单</h1> <table class="order-table"> <thead> <tr><th>商品</th><th>数量</th><th>单价</th></tr> </thead> <tbody></tbody> </table> `); const pdfBuffer = await job.render(); const blob = new Blob([pdfBuffer], { type: 'application/pdf' }); const url = URL.createObjectURL(blob); const link = document.createElement('a'); link.href = url; link.download = 'order.pdf'; link.click();

这里有两个细节值得说。第一，job.addHtml()里接收的是字符串模板，所以数据渲染需要自己先拼好，或者绑定一个小型模板引擎。第二，job.render()返回的是一个ArrayBuffer，可以自由转成Blob、Buffer或者Base64，不绑定任何框架，你可以在React、Vue、原生JS里用同样一套API。

4.2 服务端批处理：Node环境下的集成方式

服务端场景和前端有一个显著差异：不需要考虑浏览器兼容性，但必须考虑模板管理、并发控制和字体资源加载。我在一个报表项目里的做法是这样：

const express = require('express'); const { createPdfJob } = require('web-print-pdf'); const app = express(); app.post('/api/report/export', async (req, res) => { const { rows, title } = req.body; const job = createPdfJob({ pageSize: 'A4', fonts: { // 注册服务端自带的字体文件 'Noto Sans SC': './fonts/NotoSansSC-Regular.otf', 'Noto Sans SC Bold': './fonts/NotoSansSC-Bold.otf' } }); job.addHtml(buildReportTemplate(title, rows)); const pdf = await job.render(); res.setHeader('Content-Type', 'application/pdf'); res.setHeader('Content-Disposition', 'attachment; filename=report.pdf'); res.send(Buffer.from(pdf)); });

服务端部署时，我强烈建议把字体资源提前下载好，不要依赖操作系统字体。原因是大多数Linux服务器默认是没有中文字体的，一旦模板里出现了指定字体名称，但字体文件不存在，引擎会回退到默认字体，导致中文全部变成方框。把字体文件放进项目目录，并明确在fonts配置里声明，可以彻底规避这个问题。

4.3 模板编写的最佳实践

用HTML设计打印模板时，很多人会沿用网页设计的习惯：div嵌套、flex布局、绝对定位满天飞。但打印模板的排版逻辑更接近传统文档，我建议遵循三条铁律：

第一，优先使用文档流布局，少用绝对定位。绝对定位的元素容易在分页时“跑偏”——它不知道自己在哪一页，打印时可能覆盖其他内容，或者落在页面外面。如果非要定位，建议只用在页眉页脚这类固定区域内。

第二，表格是打印的骨架。复杂单据用表格组织信息最稳妥，但一定要给<thead>里的行设置重复表头标志（很多方案里是repeat-header属性或repeat类名）。这样表格跨页时，新页面顶部会自动补全表头。

第三，字号不宜过小。打印和屏幕不一样，屏幕上的12px在纸上看起来刚刚好，但打印出来的实际物理尺寸和观看距离完全不同。一般情况下正文字号不要低于9pt，表格内容不要低于8pt，否则打印出来费眼睛。

4.4 一个可复用的发货单模板

我把自己常用的一个简易发货单模板贴出来，这份模板可以直接塞进job.addHtml()里跑：

<style> .doc { width: 100%; font-family: 'Noto Sans SC', sans-serif; } .doc h1 { font-size: 18pt; text-align: center; margin: 0 0 12pt; } .summary { width: 100%; border-collapse: collapse; margin-bottom: 12pt; } .summary td, .summary th { border: 1px solid #333; padding: 6pt 8pt; font-size: 10pt; } .items { width: 100%; border-collapse: collapse; } .items thead th { background: #f0f0f0; border: 1px solid #333; padding: 6pt 8pt; font-size: 10pt; } .items tbody td { border: 1px solid #333; padding: 6pt 8pt; font-size: 9pt; } .items thead tr { repeat-header: always; } .no-break { break-inside: avoid; page-break-inside: avoid; } </style> <div class="doc"> <h1>发货单 #20240001</h1> <table class="summary no-break"> <tr><th>收货人</th><td>张三</td><th>联系电话</th><td>13800000000</td></tr> <tr><th>收货地址</th><td colspan="3">北京市朝阳区某街道某号</td></tr> </table> <table class="items"> <thead> <tr><th>商品编码</th><th>商品名称</th><th>数量</th><th>单价</th><th>金额</th></tr> </thead> <tbody> <!-- 动态渲染 --> </tbody> </table> </div>

注意我用了一个非标准的CSS声明：repeat-header: always。这种声明在纯浏览器打印里是不生效的，但web-print-pdf的引擎能识别它并转换为跨页表头重复逻辑。如果你使用原生浏览器打印，还是老老实实依赖display: table-header-group那套标准写法。

5. 分页策略的精细化控制与踩坑记录

前面说了那么多分页原理，最重要的还是实际跑起来怎么调。这一节我按问题类型来整理，覆盖我实际遇到的高频场景。

5.1 不同页面的页眉页脚差异化设置

真实业务里，一份PDF往往不是从头到尾都长一样。比如第一章封面页不要页码，第二章起才开始标注“第 1 页”，最后一章后面附加的附件页又不需要页眉。web-print-pdf把这种需求拆成了“文档-章节-页面”三层结构。

我之前做一份项目投标文件，就用到了章节级页眉页脚配置：

const job = createPdfJob({ pageSize: 'A4', margins: { top: 20, bottom: 20, left: 15, right: 15 } }); job.addSection({ title: '封面', showHeader: false, showFooter: false, html: `<div style="text-align:center;margin-top:180mm;"><h1>投标文件</h1></div>` }); job.addSection({ title: '正文', showHeader: true, header: { content: '某项目投标文件', fontSize: '8pt', color: '#666' }, footer: { content: (pageNum, total, sectionInfo) => `第 ${pageNum} 页 / 共 ${total} 页`, fontSize: '8pt' }, html: `<p>正文内容...</p>` });

这里的关键是：每个章节可以独立声明showHeader/showFooter，并且页脚回调函数里能区分“本文档总页码”和“当前章节内页码”，这对多章节合并输出的场景特别有用。

5.2 跨页表格的三种处理思路

跨页表格是打印里最经典的问题。我见过三种处理思路，各有适用场景：

• 重复表头：表格跨页时，新一页顶部自动补一趟<thead>内容。适用于列数不多、列名清晰的清单，是大多数情况下的首选。
• 重复关键列：当表格列数很多，跨页后很容易看错行时，可以把首列（比如序号、商品编码）设为跨页重复列，这样翻页后还能对上行。
• 禁止行拆分：让每行内容完整地放在同一页，宁可某页底下留白，也不让半行文字卡在页缝里。适合行内容比较高的场景，比如备注、说明类字段。

我自己的经验是：表格行数少（比如10行以内）时，直接break-inside: avoid整个表格；表格行数多时，务必开启重复表头，同时给每行设置avoidBreakInside，保证行内不拆。两件事一起做，表格打印才好看。

5.3 卡片、代码块、图片不被意外切开

这个问题在实际打印中太常见了：一张卡片顶部在上一页，下半截跑到下一页；一段代码块在页面中间齐刷刷被切断；一张大图只显示了上面三分之一。

web-print-pdf里对应有三个参数可以控制。最常用的是break-inside: avoid，它告诉引擎“这个元素尽量完整地放在同一页”。但如果元素本身高度超过一页内容区，这个规则就无论如何也保护不了。我见过很多人在这里浪费时间，其实办法是“化整为零”：把大卡片拆分成多个小模块，每个模块单独加break-inside: avoid，这样即使整体跨页，也是以模块为单位断，不会留下半截卡片这种观感。

还有一种技巧是给元素增加“换页前不拆”的语义：比如章节标题，我希望标题和它下面第一段内容永远保持在同一页，避免标题孤零零地待在页面底部。对应参数是keepWithNext。它和break-inside: avoid协同使用，基本能覆盖绝大多数内容块的防拆需求。

5.4 元素过高被硬切怎么办

如果某个元素高度确实超过一页，无论怎么设置break-inside都没用，引擎只能硬切。这时你需要接受这个现实，然后想办法让“切”的位置更合理。

我处理这类问题时，会在模板里做“分段防拆”：把一个超长表格按数据条数手动分割成多个表格块，每个块控制在页面内容区高度的80%以内，每个块单独设置break-inside: avoid。渲染时引擎会优先尝试把每个块放到当前页，放不下就整体挪到下一页。这样最终的断页位置永远在块与块之间，看起来就是有规律的、整洁的分页。

5.5 分页异常的常见原因与排查顺序

遇到分页效果怪怪的，我一般按下面的顺序排查：

• 第一步，确认纸张尺寸和边距是否和预期一致。很多“断页错乱”其实是A4和Letter默认尺寸不同导致的。
• 第二步，检查是否存在height: 100vh、min-height: 100vh这类视口单位样式。打印环境里没有“屏幕视口”的概念，这类样式容易导致元素高度异常。
• 第三步，检查片段化属性有没有拼错。break-inside在部分旧浏览器里需要写成page-break-inside，引擎虽然会兼容，但如果里外两层元素属性和语义冲突，会很难排查。
• 第四步，检查页眉页脚元素是否有position: fixed残留。在部分打印方案里fixed会变成“每一页都显示”，多个页脚叠加会让内容区高度计算失控。

大多数分页诡异问题，追根溯源都是这四类原因。

6. 高保真呈现与特殊场景处理

能让PDF“打出来”只是第一步，真正拉开差距的是“打出来像不像设计稿”。这一节我把高保真方面容易踩的点集中说一下。

6.1 颜色模式与打印色差

屏幕使用RGB颜色，印刷行业通常用CMYK，但PDF文件本身可以同时包含RGB和CMYK信息。web-print-pdf默认按RGB处理网页里定义的颜色，这在数码打印、激光打印上问题不大，如果对接的是印刷级喷绘设备，就要考虑色彩管理了。

我在处理对外印刷类文档时，会在模板里有意识地使用安全色，比如纯黑用#000而不是#111111，大面积为底色时不要用太浅的灰，否则打印出来容易显得脏。另外，字体的颜色对比度在屏幕上可能够用，但打印出来后因为纸张吸墨，浅灰色字会淡到看不清。打印模板里正文最好用#222或#333，不要用#999。

6.2 二维码、条形码打印必须控制尺寸与容错

单据打印里二维码是个高频元素。二维码有个特点：一旦尺寸太小，扫码设备很难识别。应用了纠错级别的二维码，在同样内容下，最小可识别尺寸和打印机的分辨率直接相关。

我的一般建议是：以300dpi为基准，二维码的实际打印尺寸不要小于20mm×20mm，条形码宽度尽量不小于40mm。如果二维码和文字放在同一个表格单元格里，记得给单元格配置固定的宽高，避免二维码被压缩变形。web-print-pdf对图片元素是按原始宽高比缩放的，只要你不给图片同时设置width和height去强制拉伸，二维码就不会变形。

6.3 大文件性能优化策略

生成的PDF文件太大，无论是网络传输还是下载后打开，体验都很差。文件大小通常由两个因素决定：图片分辨率过高、字体子集太大。

图片方面，很多人从页面上拿到的截图是2倍图、3倍图，原图可能4000px宽。打印到A4纸上的物理宽度一般不超过200mm，按300dpi计算，也只需要约2362px。我建议在上传打印前先做一次图片压缩，把宽度缩到2400px以内，并转成JPEG（照片类）或PNG-8（图形类），能把PDF体积压缩好几倍。

字体方面，尽量只嵌入模板用到的子集字符。web-print-pdf默认会分析页面文本内容来生成子集，但如果你在模板里动态插入了用户输入的长文本，记得触发字体子集重建，否则之前生成的子集里没有新字符，前端显示正常，PDF里就会出现“口口”。

6.4 页面水印与文档权限

客户往往希望PDF里带水印，尤其是合同、报价单这类文件。web-print-pdf支持两种水印模式：文本水印和图片水印，可以设置倾斜角度、透明度、字号。我常用的是45度斜排、透明度15%~25%的文本水印，既不影响阅读，又起到提示作用。

权限控制方面，支持设置打开密码和权限密码。权限密码可以限制打印、复制、编辑，适合需要分发但不想被随意改动的文档。设置密码后的PDF在主流阅读器里都有良好的兼容性。

我建议在生成合同类PDF时，至少设置一个只读权限密码，防止用户另存后篡改内容。但密码本身要妥善管理，因为PDF的加密是有损的——一旦丢失密码，没有官方后门可走，测试时要专门备份一个无密钥版本。

6.5 输出文件的后处理衔接

有时候PDF生成出来只是一个中间产物，后续要合并多个PDF、拆分特定页、转图片预览或者转Word。web-print-pdf允许你在渲染完成后拿到原始PDF二进制，后续操作可以直接交给其他库处理。我做报价系统时会把每个分项生成独立PDF，再用合并逻辑拼成一个总文件。这样分项可以单独缓存、复用，总文件则动态生成，性能和灵活性都兼顾了。

7. 从几个真实项目里总结的取舍经验

前面讲的偏技术细节，最后这部分我想跳出具体API，聊聊在项目落地时的选型思考和个人经验。因为打印需求往往不是孤立存在的，它和你们团队的部署环境、业务量级、模板变更频率都有关系。

7.1 什么样的情况适合前端直出

如果满足下面几个条件，我建议直接在前端生成PDF：

• 模板数量不多，三五个以内；
• 实时性要求高，用户点击后希望秒出；
• 模板变更频繁，需要快速迭代样式；
• 并发量不高，不担心浏览器内存占用。

前端直出的优势是零部署成本，不需要额外起服务。劣势是如果模板特别复杂，渲染耗时会阻塞页面；而且不同浏览器自带的字体和渲染能力不同，你不一定能完全控制最终效果。用web-print-pdf能抹平一部分差异，但宿主环境的影响依然存在。

7.2 什么样的情况必须走服务端

反过来，如果你们是报表平台、电商ERP、电子合同这类业务，我强烈建议服务端生成。原因有三点：

第一，数据安全性。前端生成PDF时，数据要拉到用户的浏览器里；服务端生成则可以做到数据不出内网，只下发一个PDF文件。合同评审、报价单这类敏感数据尤其要注意。

第二，一致性和审计。服务端生成的PDF可以集中记录生成日志，给每个文件打上固定的页眉、水印、编号，方便审计追溯。

第三，批量产能。一个客户可能要一次性下载1000张发票，前端生成个三五份还行，1000份直接卡死页面；服务端则可以队列化处理，生成完了打包Zip下载。

7.3 模板变化频繁时如何组织代码

打印模板最大的维护成本是样式和数据结构经常变。我的做法是建立在“模板字符串 + 数据对象”的思路上：每个模板单独建立一个目录，目录里包含template.html、schema.json和一份示例数据。schema.json描述了这份模板需要哪些字段，后端渲染时用同一份schema做数据校验，前端预览时用示例数据渲染。

这样做的好处是：业务人员调整表格列、改字号颜色，只需要改template.html；后端加字段时先跑schema校验，数据不齐直接报错，不会等到PDF生成出来才发现缺字段。这个流程一旦跑顺，模板迭代效率会高出很多。

7.4 与现有系统的集成方式

最后聊聊集成。web-print-pdf本身是库级别的能力，前端和后端都可以用，不绑定框架。我在一个Vue3项目里是通过一个封装的usePrintPdf组合式函数来复用的，内部统一处理了数据加载、渲染按钮loading态、PDF下载等逻辑。在另一个Node.js服务里则是用了一个独立的路由模块，对外只暴露POST /api/pdf/render这一个接口，路由内部再去读模板、合并数据、生成PDF。

集成时最需要提前规划的不是技术栈兼容性，而是模板从哪来、数据从哪来、文件传到哪去这个链路。把这三个问题理清楚，剩下的都只是API调用层面的组装。

8. 写在最后的几条实战忠告

如果前面这些内容你一时消化不掉，先记住我最后这几点经验，可以帮你少走很多弯路。

第一，不要试图用一套模板满足所有打印需求。A4合同、80mm小票、带二维码的面试单，物理尺寸都不一样，混合在一起只会让样式维护成本爆炸。宁可多维护几个模板，也不要做一个“万能样式表”。

第二，打印模板里尽量少依赖JavaScript计算布局。虽然web-print-pdf内部可以执行部分脚本能力，但脚本运行时机和模板调试的复杂度成反比——脚本越少，模板越容易预览和排错。数据层面的计算尽量在外部提前完成，模板只管展示。

第三，任何打印方案的验证都要基于真实打印机输出，而不是只看PDF预览。PDF在屏幕上的显示和打印出来还是有差别的，尤其是颜色深浅、字体大小、边距的观感。团队内部有条件的话，定一个标准型号的打印机作为验收基准。

第四，生成PDF的异常要记录足够的信息。线上环境里用户反馈“下载不了PDF”时，你需要在服务端能看到具体是模板编译报错、字体缺失、还是数据字段为空。提前把页面尺寸、模板ID、数据版本这些上下文打进日志，排查问题能省一半时间。

Web打印做了这么久，我最大的体会是：这件事没有“一招鲜”的银弹，真正可靠的是把分页、字体、模板、权限每一环都拆开，分别用可靠的组件去解决。web-print-pdf把这条链路串了起来，让你可以把更多精力放在业务本身，而不是反复和浏览器的打印对话框较劲。希望我这几千字的整理，能让你在做下一个打印需求时，少踩几个我已经踩过的坑。