纯前端Markdown转PDF：从html2pdf.js到浏览器原生打印的工程实践

1. 项目背景与需求拆解

1.1 这个需求是怎么来的

做前端的人大概都遇到过这种需求：用户在页面上编辑了一段 Markdown，点一下“导出 PDF”，想要一份排版干净、能直接打印或归档的文档。早期我接手的一个内部知识库项目就是这种场景，后台管理员用 Markdown 写操作手册，前台要能一键导出 PDF 发给客户。第一反应当然是去找后端服务，让服务器去调 Pandoc 或者 wkhtmltopdf，但当时项目部署环境受限，后端不能随便加服务，于是整个需求就压到了前端这边——纯前端把 Markdown 转成 PDF。

这个约束条件一出来，方案范围其实就收窄了很多。前端世界里能把内容落成 PDF 的路子，掰着手指头数也就那么几条：html2canvas 截图方案、html2pdf.js 这类封装好的库、jsPDF 手绘式布局，以及浏览器自带的 print 到 PDF。前两种做截图式导出，后两者做矢量式导出。我这次的实践路径是从 html2pdf.js 起步，最后落在了浏览器原生打印方案上，这篇文章就把整个演进过程、踩过的坑、最终的工程化实现都梳理一遍。

1.2 技术选型的两个核心矛盾

抛开具体库的 API 差异，纯前端 Markdown 转 PDF 这件事，本质上是在解决两个矛盾。

第一是渲染管线的矛盾。Markdown 本身是纯文本标记，浏览器不认，你需要先把它解析成 HTML，再把 HTML 排版成视觉页面，最后才谈得上“变成 PDF”。第二条和第三条之间，就出现了分水岭：你是要让浏览器把页面画出来再截图，还是让浏览器把排版好的文档直接交给打印子系统。

第二是还原度与可控性的矛盾。截图像素级还原所见即所得，但生成的 PDF 是图片底子，文字不能选中复制、体积大、放大发虚；而打印方案的 PDF 是矢量文本，文字可选中、体积小、清晰度跟分辨率无关。但它也有代价——打印样式受浏览器排版引擎约束，分页控制是出了名的难伺候。

搞清楚了这两个矛盾，后续所有技术决策就都有了判断依据。我在选型时也是围绕这两对矛盾展开的，下面展开细说。

2. html2pdf.js 方案实践与分析

2.1 方案原理与依赖链条

html2pdf.js 这个库，说透了就是两件事的缝合：先用 html2canvas 把目标 DOM 节点“拍一张照”转成 canvas 位图，再用 jsPDF 把这张位图按 A4 纸的尺寸逐页贴进去，生成 PDF 文件。所以它输出的 PDF 本质上是图片集，不是真正的文本层。

依赖链条很清楚：

• 解析层：marked 或 markdown-it 负责把 Markdown 文本编译成 HTML 字符串。
• 排版层：页面里需要有一个容器元素，样式由你写好的 CSS 控制，决定字体、行距、标题大小、代码块背景等。
• 截图层：html2canvas 将容器渲染成 Canvas。
• 合成层：jsPDF 将 Canvas 按页宽高切分，逐页写入 PDF。

接入代码的核心部分长这样：

import html2pdf from 'html2pdf.js'; const element = document.getElementById('markdown-preview'); const options = { margin: [10, 10, 10, 10], filename: 'document.pdf', image: { type: 'jpeg', quality: 0.95 }, html2canvas: { scale: 2, useCORS: true, logging: false }, jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' }, pagebreak: { mode: ['css', 'legacy'] } }; html2pdf().set(options).from(element).save();

第一次跑通这个流程的时候，感觉确实香。只需要几行配置，一个能用的 PDF 导出功能就上线了。但随着测试深入，问题开始浮现。

2.2 分页截断问题与 remedy 方案

html2pdf 最典型的痛点就是分页截断。当整个文档高度超过一页 A4 时，它默认的做法是把 canvas 按固定高度切块，上一页的末尾直接裁断，一个标题或者一行代码可能被拦腰切断，上不了下一页。阅读体验非常糟糕。

当时网上给的补救办法，总结下来有四种，我全部试过一遍：

• 用pagebreak的css模式，配合给标题、代码块加page-break-inside: avoid。这个对块级元素有点用，但表格和长代码块照样断。
• 用pagebreak的legacy模式，内部其实也是一个元素扫描逻辑，找到高度超限的元素重新定位，实际效果不稳定。
• 手动把容器拆成多个小块，一个块一个块地调 html2pdf，最后用 jsPDF 的addPage拼接。这种可控性高点，但页面尺寸、边距全都得自己算，代码量成倍增长。
• 绕开 html2pdf，直接用 html2canvas + jsPDF 自己写分页逻辑。实际上最灵活，但也等于把插件重新造了一遍。

我最终在项目里采用的是第三种思路，单独封装了一个分段渲染器。先把渲染出来的 HTML 内容按章节拆分，每个章节独立渲染成 canvas，再按章节高度预估页数，计算每一页的偏移位置，最后拼装。这个方案能把截断问题控制到“可接受”的程度，但代价是代码复杂度飙升，而且生成一份超长手册时内存占用明显抬头——因为多个高分辨率 canvas 同时在内存中存活，低端移动设备上直接白屏。

2.3 图片、字体与跨域问题

除了分页，还有三座大山压着 html2pdf 方案。

图片跨域。html2canvas 渲染图片时受浏览器同源策略约束，外链图片如果响应头不带 CORS 许可，canvas 就会被污染，导出直接失败。解决方式要么让服务端给图片配Access-Control-Allow-Origin，要么在前端先把图片转成 base64 再注入 DOM。当时我写了个预加载器：遍历容器内所有img标签，用fetch拉取图片并转 blob，再用URL.createObjectURL替换src。这个方案在图片数量少的时候没问题，但文档里嵌入几十张截图时，等待时间明显变长，而且偶发加载失败会导致整次导出报废。

字体缺失。如果文档里用了特殊字体而系统没装，html2canvas 只能按 fallback 字体渲染，导出结果跟屏幕预览对不上。解决办法是给@font-face加unicode-range并把字体文件 base64 内联，但 base64 编码的字体文件动辄几百 KB，页面加载压力反而成了新瓶颈。

PDF 体积。canvas 是位图，scale 调得越高体积越夸张。A4 内容用 scale 2 渲染，十页文档的 PDF 轻松突破 20MB，发送给客户要等半天。尝试过压缩 JPEG 质量到 0.7 来降体积，但图片多的时候效果有限，而且质量下降很明显。

html2pdf.js 方案在这套实际业务里最终是能用的，只是维护成本高，每次改版都要针对性地调整分段策略。这种感觉就像开一辆老款手动挡车，能到目的地，但每一趟都累。

3. 转向浏览器原生打印方案

3.1 原生打印的思路转变

大概用了半年 html2pdf，有一次我在处理用户反馈时，随手点了浏览器的打印按钮，看到系统打印预览里那个清爽的 PDF 预览，突然意识到：一款经过调试的 HTML 页面，浏览器原生就能输出一份高质量的 PDF，那我为什么要费劲去截图？

浏览器原生打印的本质，是把你的网页通过排版引擎重新渲染一遍，然后输出给打印子系统。当你选择“另存为 PDF”时，浏览器等于内置了一个 PDF 生成器，而且它的排版引擎跟网页渲染是同一套，CSS 的支持度最完整，文字是矢量格式，体积小，缩放清晰。

当然，这里有一个前提：你必须为打印单独写一套 CSS。屏幕显示的样式和打印输出的样式是两套逻辑，屏幕上有交互、动效、滚动，打印时需要的是静态、整齐、连续的分页文档。这套 CSS 的写作质量，直接决定 PDF 的最终呈现水平。

3.2 @media print 与分页控制

原生打印方案的核心技术点，就是@media print媒体查询。你可以在普通样式之后追加一段打印专用样式，浏览器在打印时自动启用：

@media print { @page { size: A4; margin: 12mm 16mm; } body { background: #fff; } .no-print { display: none !important; } .pdf-content { width: 100%; margin: 0; padding: 0; } .pdf-content h1, .pdf-content h2 { page-break-after: avoid; } .pdf-content img, .pdf-content table, .pdf-content pre { page-break-inside: avoid; } }

这套样式的关键点只要掌握@page、page-break-*这两个维度，就解决了八成的呈现问题。

@page控制纸张大小和页边距。除了 A4，还能写成size: A5 landscape或者自定义尺寸如size: 148mm 210mm。页边距建议统一用毫米单位，因为打印系统的度量基准就是毫米。

page-break-before、page-break-after、page-break-inside这三个属性是分页控制的三板斧。经验法则：

• h1、h2这种标题节点加page-break-after: avoid，避免标题落在页尾而正文跑到下一页。
• pre、table、img这类不能拆分的元素加page-break-inside: avoid，防止代码行被从中间截断。
• 章节开头想强制从新页开始，加page-break-before: always。

3.3 过渡方案：插入占位节点

浏览器对page-break-inside: avoid的支持度比想象中要弱。Chrome 对块级元素的内部避断支持还行，但遇到超高代码块或者长表格时，它还是会选择截断，原因是如果元素本身高度已经超过一页，避断逻辑直接失效。

针对这个问题，我当时做了一个取巧的手段：预扫描容器内所有可能超高的节点，主动在它们前面插入一个空白分页占位节点，强制浏览器提前换页。

实现思路是用getOffsetHeight去量每个代码块的高度，超过页面可用高度阈值（A4 减去边距后的内容高度）时，就在它前面动态插入一个html2pdf-break-page的 div，样式设为page-break-before: always。实测下来，很长代码块的截断率低了非常多，几乎到了零。这个方法算不上优雅，但在生产环境里非常稳。

4. 工程化落地：Markdown 渲染到打印的完整链路

4.1 管道设计：从字符串到 PDF

真正工程化落地时，我把整条链路设计成了四个节点的管道：

Markdown 字符串 → Markdown 解析器 → 渲染容器（屏幕预览） → 打印容器（隐藏） → window.print()

这里有一个容易被忽略的细节：屏幕预览的 DOM 和打印用的 DOM 不能是同一个节点。原因有两个：一是屏幕样式和打印样式的类名、结构可能是冲突的，二是打印容器需要临时插入一些分页占位节点和补充元素，如果直接操作预览容器，会影响屏幕上的展示效果。

所以我在初始化时创建了一个离屏容器#print-root，它常驻 DOM 但visibility: hidden。在打印前把渲染好的 HTML 克隆一份塞进去，再在克隆副本上做分页优化处理，最后调用打印。这样屏幕预览和打印输出互不干扰，逻辑职责也清晰。

代码如下：

function preparePrintContent(html) { const printRoot = document.getElementById('print-root'); printRoot.innerHTML = html; insertPageBreaksForOversized(printRoot, 232); // 232mm 是 A4 减去边距后的内容高度 return printRoot; } document.getElementById('export-pdf').addEventListener('click', () => { const html = preview.innerHTML; // 预览容器里的渲染结果 preparePrintContent(html); window.print(); });

4.2 Markdown 解析层的细节处理

Markdown 渲染我选的是 markdown-it，相比 marked 它插件生态更丰富，对 GitHub 风格语法支持更完整。除了基础语法外，生产环境里还必须处理四个增强点：

• 代码高亮：用 highlight.js 做前端高亮。注意 highlight.js 的 CSS 要手动引入，而且打印时深色主题的背景会被print-color-adjust拦掉，所以打印样式里要覆盖回浅色主题。
• 数学公式：用 katex 插件做公式渲染，它渲染出的 HTML 结构比较稳定，打印还原效果好。MathJax 虽然更强大，但渲染是异步的，打印前需要等它 reflow 完成，不确定性太大。
• 表格：Markdown 表格到 HTML 之后默认没有边框，打印样式里必须补上.table的边框、表头底色。
• 图片懒加载：如果 Markdown 里的图片还没加载完就触发打印，PDF 里会出现空白占位。打印前要用Promise预加载所有图片。

图片预加载的实现我直接用了一个简单的 Promise 包装：

function waitForImages(container) { const images = Array.from(container.querySelectorAll('img')); return Promise.all(images.map(img => { if (img.complete && img.naturalWidth > 0) return Promise.resolve(); return new Promise((resolve) => { img.onload = () => resolve(); img.onerror = () => resolve(); // 加载失败也继续，避免阻塞打印流程 }); })); }

4.3 封装统一的导出组件

为了让页面不用关心底层实现，我封装了一个独立的导出类MarkdownExporter，对外只暴露一个方法export(markdownOrDom, options)。

几个设计要点：

• 支持两种输入：直接传 Markdown 字符串（内部走 markdown-it 渲染），或者传已经渲染好的 DOM 节点（复用别人渲染的结果）。
• 所有打印样式通过动态插入<style>标签实现，不污染项目的全局样式表。
• 导出结束后，把临时容器清空并移除内联样式。

这样每个业务页面只需要三行代码就能接入导出能力：

const exporter = new MarkdownExporter(); await exporter.export(markdownText, { filename: '帮助文档.pdf' });

5. 两套方案的核心参数与性能对比

5.1 技术特性对照

这段我用一个表格把 html2pdf.js 和浏览器原生打印的核心差异理清楚，便于后面选型参考：

从这张表能直接看出，矢量与位图的差异是决定性因素。如果你做的是文档管理、合同签署、报告导出这类需要回看、复制、搜索的场景，位图 PDF 在功能上是残缺的。

5.2 体积与性能实测数据

我在同一台机器、同一份约 30 页的 Markdown 文档上跑过一次实测对比：

• html2pdf.js 方案：scale 2 下生成 PDF 约 18MB，导出耗时约 12 秒（含图片预加载和分段渲染）。
• 原生打印方案：同一份文档导出 PDF 约 1.2MB，预览弹出时间大概 1~2 秒，确认后生成几乎瞬间完成。

体积差了 15 倍。这背后的原因很简单：位图每个像素都要记录，而矢量文本只记录字符信息和位置。对于文字为主的文档，矢量方案在体积上有碾压性优势。

内存占用方面，html2pdf 在渲染超长文档时，canvas 对象在合成阶段是整页级别的，Chrome 的内存峰值经常会冲到 300MB 以上；原生打印的排版和栅格化由浏览器打印引擎完成，几乎不增加 JS 堆的内存压力。

5.3 兼容性红线说明

原生打印方案的短板也很明确：浏览器差异化明显。

• Chrome/Edge 对@page的支持最好，分页行为稳定。
• Firefox 对page-break-inside: avoid的支持相对较弱，长代码块截断概率高。
• Safari 在@page的 margin 控制和打印背景色方面历史遗留问题较多，需要额外加-webkit-print-color-adjust: exact来强制背景色显示。

如果项目用户群体固定是内部管理系统，用的都是公司统一配发的 Chrome 或 Edge，原生打印方案完全够用。如果是要开放给所有浏览器用户，建议在打印入口加一个浏览器嗅探，非 Chromium 内核时降级回 html2pdf.js 方案。这个双轨策略在我的实践里是最稳的。

6. 实战踩坑记录与排查方法

6.1 打印时背景色消失

第一次用原生打印时，我写好的代码块浅灰色背景、表头深灰色背景，在屏幕上预览正常，打印出来全变白板了。原因很简单：浏览器的打印引擎默认不打印背景色和背景图，以节约油墨。

这一步翻了浏览器规范，要给目标元素显式设置print-color-adjust: exact，Chrome 对应-webkit-print-color-adjust: exact。建议在打印样式的最前面粗暴地给所有元素开启：

@media print { * { -webkit-print-color-adjust: exact; print-color-adjust: exact; } }

实测这段代码解决 90% 的背景色丢失问题。个别场景下想局部强制关闭背景色，也可以单独覆盖这个属性。

6.2 分页后标题孤立在页面底部

标题孤悬页尾、正文跑到下一页，是非常常见的排版问题。解决分两路：一是给标题设置page-break-after: avoid，这能解决大多数情况；二是如果标题前面是段落，当标题和前文一起落入页尾时，规避效果不稳定，此时要在标题上加一个padding-top: 1px的小技巧，让标题和上一段之间有一丝间隙，打印引擎往往就会因为这一像素的间隙触发自动断页。

这听起来是个歪招，但确实是我在多个项目里实测有效的方案，对于 WebKit 内核的浏览器尤其管用。

6.3 页面页脚内容对不上

系统自带的页眉页脚打印出来是浏览器的默认信息——URL、日期、页码，既不好看，还会和文档正文冲突，特别是我们自己的文档里已经写了页码时，两套页码叠在一起非常乱。

设置@page的margin能解决一部分，但用户手动勾选的“页眉页脚”选项优先级更高。如果目标用户是内部员工，可以直接在打印前调matchMedia('print')检测打印状态，然后在打印样式中把浏览器默认页眉页脚的显示位压掉：

@page { margin: 12mm 16mm; }

这只能保证在“另存为 PDF”时默认不带页眉页脚，但用户如果勾选“背景图形”或者自己打开了页眉页脚开关，浏览器会覆盖站点设置。我最终的做法是在文档正文顶部加一个id="pdf-header"的隐藏元素，用position: running(header)这种 CSS 高级特性自定义页眉，但这里涉及@page的 margin boxes，Chrome 目前支持还不完善，实际上生产环境还是建议靠用户端设置配合默认关闭页眉页脚解决。

6.4 大文档打印预览卡顿

当 Markdown 文档很长，比如 100 页以上，打印预览的渲染速度会明显变慢。实测主要瓶颈在大量img加载和代码高亮的 DOM 节点数。对策有三个：

• 对图片做按需加载：屏幕预览时只加载可视区的图片，打印前才统一加载全部。
• 精简打印容器 DOM：避免直接把整个预览容器克隆，而是一次性用innerHTML字符串构建。
• 关闭 highlight.js 的无关语言高亮：引入highlight.js/lib/core，只注册需要的语言，能显著降低标记数量。

7. 最终落地的经验总结

整套从 html2pdf.js 迁移到浏览器原生打印的过程，我最大的体会是两件事。

第一，方案选型要看内容形态。如果你的内容偏图文混排、注重像素级还原，html2pdf.js 哪怕是位图，也还是有它的价值；但如果你的内容以文字、代码、表格为主，原生打印方案在体积、清晰度、可复制性上的优势是压倒性的。

第二，所有分页问题本质上是 CSS 问题，而不是“PDF 问题”。你在屏幕上看到的页面和打印出来的 PDF，底层是同一个排版引擎在负责布局，你需要的是用打印媒体样式告诉引擎“在什么位置分段、什么元素不能拆”。一旦把思路转换到这个层面，很多问题就不再是无解的玄学。

最后分享一个生产中很实用的小细节：导出 PDF 按钮的点击事件里，一定要先触发一次window.focus()，再调用window.print()。有些浏览器在页面失焦状态下打开打印预览会出现样式刷不出来或者错乱的状况，先聚焦能避开这个雷区。另外，在afterprint事件里记得清理临时容器，不然一个隐藏容器长期挂在 DOM 上，内存占用和 CSS 污染迟早会反噬。