服务端 PDF 生成与转换的工程实践：字体、并发与一致性

服务端生成 PDF（报表导出、合同出稿、账单推送）是典型的「看起来一天做完，实际维护两年」的需求。三类工程问题决定了这个模块的稳定性。

问题一：字体——缺失与嵌入

服务器上渲染 PDF，第一坑永远是字体：开发机有的字体服务器没有，导出的 PDF 中文变方块或被静默替换成默认字体。两个工程纪律：

字体文件随应用分发——把用到的字体（正文、加粗、数字等宽各一）打包进部署产物，不依赖系统字体表；生成时全量嵌入——PDF 的字体嵌入分「子集嵌入」和「全量嵌入」，服务端生成选子集嵌入（体积小），但必须验证嵌入成功：嵌入失败的 PDF 在无该字体的客户端上直接露馅。上线前跑一次「缺字体检测」清单，比事后接客服投诉划算一百倍。

问题二：模板渲染与动态填充的取舍

生成 PDF 有两条路线：HTML 模板渲染转 PDF（改样式快，前端工程师零学习成本）和结构化库直接绘制（位置精确，改一个行距要改代码）。选型经验：版式固定、数据动态的（账单、报表）走模板；版式随内容变化的（自动排版的报告）走结构化绘制。两条路线并存的团队要定一条纪律：同一业务只用一条路线，否则同一个报表两种渲染，排查问题时两边互相甩锅。

问题三：并发转换的资源控制

PDF 转换是 CPU 密集+临时文件密集的混合负载。裸奔的并发转换会同时炸掉 CPU 和磁盘：转换库临时文件写满盘、进程互相争内存。控制三板斧：信号量限并发（按 CPU 核数设上限）、临时目录配额（每个任务一个独立子目录，完成即清，配额监控进告警）、队列化削峰（批量导出请求进队列慢速消化，保交互请求优先）。

问题四：一致性——同输入永远同输出

最容易忽略的工程指标：同一份输入，今天生成的 PDF 和下周生成的必须逐字节一致（或至少渲染一致）。破坏一致性的因素：模板版本漂移、字体库升级、渲染库版本变化。解法是把「生成结果快照」纳入回归——每次模板或依赖升级，用固定输入集重生成、与基线比对。合同类文档尤其需要这条：两个版本行距不同，签署页对不齐就是事故。

验收清单

四个数字验收这个模块：缺字体检测通过率（100%）、并发峰值资源占用（不超配额）、快照回归一致率（100%）、转换失败率（<0.1%）。PDF 生成模块的工程价值，全在「每次都一样」这四个字上。