最快上手是pdfkit（依赖wkhtmltopdf），但易崩；puppeteer更可控但启动慢；window.print()非真PDF；Flying Saucer适合静态报表；核心难点是业务验收细节。
Python 用 pdfkit 转 HTML 最快上手但容易崩
它本质是调用系统里装的 wkhtmltopdf，不是纯 python 实现，所以不装二进制就直接报错：ioerror: wkhtmltopdf not found。常见于 macos 用 homebrew 装了但路径没加进环境变量，或 windows 没勾选“add to path”。
实操建议：
- 先在终端跑
wkhtmltopdf --version确认能执行；不行就重装，macOS 推荐brew install --cask wkhtmltopdf，Windows 去官网下完整安装包（别下“no dll”版） - Python 里指定路径更稳：
config = pdfkit.configuration(wkhtmltopdf='/usr/local/bin/wkhtmltopdf') - 中文乱码？加这两行：
options={'encoding': 'UTF-8', 'page-size': 'A4'}，再确保 HTML 里有<meta charset="UTF-8"> - 页面里含 JS 渲染的内容（比如 Vue 组件），默认不等 JS 执行完就截图，得加
--javascript-delay 2000到 options 的configuration
Node.js 用 puppeteer 转 PDF 更可控但启动慢
它启动真实 Chromium，能等 DOM 加载、JS 执行、甚至模拟滚动触发懒加载，适合转 SPA 页面。但每次调用都启浏览器进程，冷启动要 1–2 秒，不适合高并发场景。
实操建议：
- 别用
launch({ headless: true })默认值——新版本 Chromium 默认就是 headless，显式写反而可能出兼容问题；直接launch()就行 - 转本地 HTML 文件时，用
file://协议会触发 CORS，改用page.setContent(htmlString)或起个最小 Express 服务再goto('http://localhost:3000') - 字体缺失？Linux 服务器常缺中文字体，
apt-get install fonts-wqy-zenhei或把字体文件用@font-face内联进 HTML - 页眉页脚想用动态内容（如页码），只能用
page.pdf({ displayHeaderFooter: true, headerTemplate: '...' })，且模板里不能用 JS，只支持有限 CSS
前端直接用 window.print() 不是真 PDF
它只是唤起浏览器打印对话框，用户点“另存为 PDF”才生成，无法自动化、不可控格式、不保证跨浏览器一致。有人误以为加 @media print 就算转 PDF，其实只是优化打印样式。
立即学习“前端免费学习笔记（深入）”；
实操建议：
- 如果真要前端生成 PDF，别碰
window.print()，改用jsPDF + html2canvas组合，但注意：Canvas 截图会丢失 SVG、CSS transform、fixed 定位元素，且长页面要手动分页 -
html2canvas对跨域图片报错？加useCORS: true并确保图片服务返回Access-Control-Allow-Origin: * - 生成的 PDF 文字不可选、搜索不了——这是 canvas 截图的固有缺陷，纯文本 PDF 必须走服务端
Java 后端用 Thymeleaf + Flying Saucer 适合报表类静态 PDF
Flying Saucer（即 core-renderer）只支持 CSS 2.1，不支持 Flex/Grid、position: sticky、现代伪类，适合转表格、单页通知这类结构简单的内容。
实操建议：
- Maven 依赖别引错：
org.xhtmlrenderer:flying-saucer-pdf-itext5（适配 iText 5），iText 7 需换用flying-saucer-pdf-itext5的 fork 版本 - HTML 必须是严格 XHTML（闭合标签、小写、无自定义属性），否则解析失败；用 Thymeleaf 时加
th:fragment比用th:replace更安全 - 中文字体必须显式注册：
FontResolver resolver = new FontResolver(); resolver.addFont("/path/to/simhei.ttf", "SimHei", true);，否则全是方块 - 页边距、分页靠 CSS：
@page { margin: 2cm; }和div.page-break { page-break-after: always; }，但break-inside: avoid支持不稳定
真正难的不是“怎么转”，而是“转出来能不能被业务接受”：页眉对不齐、表格跨页断裂、中文字体渲染发虚、JS 动态数据没等上……这些细节不会报错，但一上线就被运营打回来改三次。
