本文介绍在 web 应用中将 tiptap 富文本内容可靠、高效导出为 pdf 的最佳实践，重点推荐服务端 puppeteer 渲染方案，并对比分析客户端方案的局限性，附可落地的代码示例与关键注意事项。
本文介绍在 web 应用中将 tiptap 富文本内容可靠、高效导出为 pdf 的最佳实践，重点推荐服务端 puppeteer 渲染方案，并对比分析客户端方案的局限性，附可落地的代码示例与关键注意事项。
将 TipTap 文档导出为 PDF 是许多内容协作类应用的核心需求，但实现方式直接影响输出质量、文件体积和跨浏览器兼容性。实践中需明确一个关键前提：TipTap 本身不提供原生 PDF 导出能力，必须通过 HTML → PDF 的转换流程完成。因此，核心挑战在于如何将 TipTap 的 JSON 或 HTML 内容，结合样式与布局，渲染为符合打印语义的 PDF。
❌ 客户端方案的典型缺陷（不推荐用于生产）
常见误区是依赖 html2canvas + jsPDF 组合：先将编辑器 DOM 截图为 Canvas，再转为 PDF。该方法存在严重问题：
- 文件体积爆炸：Canvas 本质是位图，9 页文档达 100MB 是典型表现；
- 失真与缩放异常：字体抗锯齿、CSS Flex/Grid 布局、分页控制完全失效；
- 无法正确处理长文档分页、页眉页脚、页码等印刷级需求。
window.print() 虽能触发浏览器原生打印对话框并支持 CSS @media print，但无法直接生成 PDF 文件流供程序自动下载或后端处理，且用户干预不可控，不适合自动化导出场景。
✅ 推荐方案：服务端 Puppeteer 渲染（高保真 + 可控）
最成熟、可扩展的方案是在服务端使用 Puppeteer 启动无头 Chromium，将 TipTap 输出的 HTML（含完整内联样式或嵌入 CSS）注入页面，执行精准 PDF 渲染。此方式具备以下优势：
- 输出为矢量 PDF，体积小（同等内容通常
- 完全支持 CSS 分页（page-break-before/inside/after）、@media print、自定义页边距与纸张尺寸；
- 可统一注入品牌 CSS、水印、页眉页脚等业务样式；
- 与前端框架解耦，React/Vue/Next.js 等均可调用。
以下为 Next.js API Route 示例（app/api/export-pdf/route.ts）：
import { NextResponse } from 'next/server';
import puppeteer from 'puppeteer';
export async function POST(req: Request) {
const { htmlContent, cssStyles = '' } = await req.json();
// 构建完整 HTML（确保包含 DOCTYPE、基础样式重置及业务 CSS）
const fullHtml = `
<meta charset="utf-8"><style>
/* 基础重置与打印适配 */
* { margin: 0; padding: 0; box-sizing: border-box; }
@media print {
body { font-size: 12pt; line-height: 1.5; }
h1 { page-break-after: avoid; }
.page-break { page-break-before: always; }
}
${cssStyles}
</style>${htmlContent}
`;
const browser = await puppeteer.launch({
args: ['--no-sandbox', '--disable-setuid-sandbox']
});
const page = await browser.newPage();
try {
await page.setContent(fullHtml, { waitUntil: 'networkidle0' });
const pdfBuffer = await page.pdf({
format: 'A4',
printBackground: true,
margin: { top: '20mm', right: '15mm', bottom: '20mm', left: '15mm' },
preferCSSPageSize: true
});
await browser.close();
return new NextResponse(pdfBuffer, {
status: 200,
headers: {
'Content-Type': 'application/pdf',
'Content-Disposition': 'attachment; filename="document.pdf"'
}
});
} catch (error) {
await browser.close();
throw error;
}
}
? 关键注意事项：
- HTML 安全性：务必对 htmlContent 进行严格 XSS 过滤（如使用 DOMPurify.sanitize()），禁止执行任意脚本；
- 样式注入：避免依赖外部 CSS 文件链接（网络延迟/跨域失败），所有样式应内联或预编译为字符串；
- 字体嵌入：若使用自定义字体（如 @font-face），需确保字体文件可被 Puppeteer 访问（建议转为 base64 内联）；
- 性能优化：对长文档，可启用 puppeteer.launch({ headless: 'new' }) 及合理超时设置；生产环境建议复用 Browser 实例（如通过 puppeteer-cluster）；
- 前端调用示例：
const exportPdf = async () => { const html = editor.getHTML(); // TipTap editor 实例 const response = await fetch('/api/export-pdf', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ htmlContent: html, cssStyles: '.tiptap { font-family: "Segoe UI", sans-serif; }' }) }); const blob = await response.blob(); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'my-document.pdf'; a.click(); URL.revokeObjectURL(url); };
综上，服务端 Puppeteer 方案在质量、可控性与可维护性上显著优于客户端 hack 方式。虽需额外服务端资源，但其输出的专业性与稳定性，使其成为企业级文档导出的事实标准。对于轻量需求，亦可考虑 playwright（API 更现代）或托管服务（如 DocRaptor、PDFShift），但 Puppeteer 在生态成熟度与定制自由度上仍具首选优势。
