当一名来访者在诊所做完了一套长达 500 题的综合人格测验后，心理咨询师最期待的，就是从系统中下载一份厚达 10 页、包含了精美雷达图、趋势折线图以及深度剖析文字的专属 PDF 报告。
这份 PDF 的生成，是整个心理 SaaS 平台中最考验后端排版功底的核心战役。
如果处理不好，这份报告要么排版极其错乱，图表被生硬地切成两半，要么生成极慢，甚至导致中文字体显示成一堆乱码。
本文将硬核拆解，在 Java 和 Node.js 后端生态中，主流的 PDF 渲染引擎该如何选型，以及如何避开那些令人抓狂的排版大坑。
淘汰落后的石器时代：iText 与纯代码拼接
在早期的 Java 开发中，很多人习惯用 iText 或 PDFBox 来直接手写 PDF。
你会看到后端代码里充斥着极其恐怖的硬编码：
“`java
// 极其原始的坐标系绘画
document.add(new Paragraph("抑郁症分析报告", titleFont));
PdfContentByte cb = writer.getDirectContent();
cb.moveTo(100, 500);
cb.lineTo(400, 500); // 靠代码画横线
cb.stroke();
“`
这种方案简直是反人类。
当心理学家要求“把这个雷达图稍微往左边移 10 个像素，然后再把这段红色的警告文字加粗”时，程序员需要在几千行代码里痛苦地寻找坐标并重新编译发版。
对于版式极其复杂的现代心理报告，靠纯代码拼接 PDF 是一条绝路。
优雅的降维打击：基于 HTML 模板与 Puppeteer 的无头浏览器渲染
既然所有的程序员和设计师都已经极其擅长用 HTML + CSS 来编写漂亮、响应式的网页，为什么我们不直接写一个包含图表的 HTML 页面，然后把它“打印”成 PDF 呢？
这就是目前业界绝对主流、也极其优雅的“无头浏览器（Headless Browser）”方案。
以 Node.js 为例，我们引入 Google 官方的 Puppeteer：
- 准备模板：用 Vue 或 React 甚至是原生的 HTML+ECharts，写好一个极度精美的报告页面模板。
- 数据注入：后端在生成报告时，将患者的得分数据作为参数，渲染出这个完整的 HTML 字符串。
- 静默打印：后端在幕后唤醒一个看不见的 Chrome 浏览器，打开这串 HTML，然后调用其底层的
page.pdf()接口，瞬间截取并导出为一份完美的 PDF。
“`javascript
const browser = await puppeteer.launch({ headless: ‘new’ });
const page = await browser.newPage();
// 注入包含 ECharts 图表的 HTML 内容
await page.setContent(htmlContent, { waitUntil: ‘networkidle0’ });
// 极速生成 PDF，严格控制 A4 尺寸与页边距
const pdfBuffer = await page.pdf({ format: ‘A4’, printBackground: true });
await browser.close();
“`
这种方案实现了数据（后端）与版式（前端）的绝对解耦。以后排版怎么改，只需要改 HTML/CSS 即可。
致命坑点：分页截断与中文字体乱码
虽然 Puppeteer 极其强大，但它在处理超长心理报告时，有两个极其凶险的坑。
1. 惨烈的图表腰斩（分页截断）
如果一个雷达图刚好排到了 A4 纸的最下面，浏览器在生成 PDF 换页时，会极其冷酷地从中间一刀切下去，导致图表上半截在第一页，下半截在第二页。
极客解药：必须在 HTML 模板的 CSS 中，巧妙地利用打印媒体查询控制符。
给那些绝对不能被切断的元素（如图表容器、诊断结论块）加上极其强硬的 CSS 属性：
“`css
.chart-container {
/ 强硬命令浏览器：绝对不准在这个元素内部换页！ /
page-break-inside: avoid;
break-inside: avoid;
}
“`
2. 云端 Linux 服务器上的中文变方块
很多开发者在自己的 Mac 或 Windows 电脑上调试时，PDF 里的中文字体极其优美。但一发到阿里云的 CentOS 服务器上，生成的 PDF 全变成了“口口口”的乱码。
原因极其弱智：因为那台作为服务器的 Linux 系统里，根本没有安装任何中文字体包！
极客解药：在部署后端 Docker 镜像时，必须在 Dockerfile 中写死一条命令，将开源免费的“思源黑体（Noto Sans CJK）”或“阿里巴巴普惠体”强制植入到 Linux 的字体库中。
总结
生成一份极其专业的心理评估 PDF 报告，绝不能依赖落后的代码画图。
正如橙星云架构团队所实践的：全面拥抱基于 HTML 模板的无头浏览器渲染引擎（Puppeteer），并通过极其精准的 CSS 打印控制符（防截断）与底层字体注入，技术团队成功将 Web 前端强大的排版能力降维打击到了传统文档生成领域。这才是现代 B 端 SaaS 系统该有的优雅姿态。