做前端时间久了你会发现把内容导出成 PDF这个需求像幽灵一样无处不在。早些年接内部工具平台时产品经理甩过来一句用户写的 Markdown 笔记导出的时候最好直接变成 PDF别让用户自己折腾 Word我还没意识到这里面的水有多深。当时的第一反应就是搜库于是遇见了 html2pdf.js又在连续踩了它几个坑之后开始研究浏览器原生打印。这篇文章把这条完整的折腾路线写下来解析器怎么选、html2pdf.js 怎么配、打印样式怎么写、分页怎么控、常见坑怎么排最后给出我现在的选型结论。如果你是那种接到类似需求就头大、想直接找可行方案的人这篇应该能让你少走不少弯路。1. 需求与方案选型1.1 需求从哪来纯前端把 Markdown 转 PDF典型场景就三类在线笔记平台要提供导出笔记按钮后台管理系统要生成带格式的报表博客或文档站想让访客一键下载离线版。共同点是内容已经在浏览器里渲染好了不想再发回服务端绕一圈有的是出于文档内容隐私考虑有的纯粹是省服务器资源还有的是产品要求导出过程必须无感快速。这件事表面上是格式转换实际上难在两点第一Markdown 渲染成 HTML 这步必须稳定可控语法扩展、代码高亮、数学公式一个都不能少第二PDF 输出的效果要能看分页不能切在代码块正中间表格不能只画半张中文不能变成豆腐块。这两点决定了你选什么库、怎么写样式也决定了下游所有坑的分布位置。1.2 三条主流路线对比我做调研的时候把所有能想到的路子都列了一遍最后剩下三个主流候选路线核心原理优点缺点html2pdf.js用 html2canvas 把目标区域截图成 canvas再由 jsPDF 把图片封装成 PDF纯前端一键导出文件用户无感知生成的 PDF 本质是图片文字不可选中复杂内容分页能力弱清晰度依赖 scale 参数浏览器原生打印window.print() 调起打印预览用户选择另存为 PDF文字矢量清晰可复制文件体积小分页由浏览器内核处理需要用户手动操作一步不同浏览器打印样式有差异服务端转换Puppeteer 等无头浏览器加载页面后直接输出 PDF效果稳定可控适合大批量不是纯前端要维护服务链路和资源消耗这三条路线的核心区别不在代码多少而在谁负责把连续页面切成一张张纸。html2pdf.js 本质是一个一个方块地拼浏览器打印本质是排版引擎做分页。复杂文档面前后者的专业度远高于前者。1.3 选型背后的思路我一开始毫不犹豫选 html2pdf.js就因为需求方要求一键导出不许弹任何框。html2pdf.js 确实能做到无弹窗直接下载文件但很快我就意识到它把 HTML 变成 canvas 图片再塞进 PDF 的这一底层逻辑天然决定了它的天花板文档短还凑合一旦有长表格、超长代码块、数学公式图片方式的渲染质量和分页效果就非常不可控。后来我换了个思路把导出 PDF按钮改成触发 window.print()同时给页面写一套专门的打印样式。用户点击后浏览器弹出打印预览打印机选另存为 PDF出来的效果反而比 html2pdf.js 干净得多。于是我的项目里就出现了两条路线并存的情况后面我把这两条路的实操细节都展开讲一遍你可以根据自己产品的交互约束来判断走哪条。2. 把 Markdown 渲染成可打印的 HTML不管最终走哪条导出路线第一步都是把 Markdown 渲染成 HTML。这步如果打好了基础后面至少少踩一半坑。很多翻车现场问题根源其实不在 PDF 生成环节而是 Markdown 转出来的 HTML 本身就有兼容隐患。2.1 解析器选型marked 还是 markdown-itMarkdown 解析器我用过两款marked 和 markdown-it。marked 轻、快、API 简单适合内容结构单一的场景比如只解析标题、段落、列表、粗斜体markdown-it 严格遵循 CommonMark 规范插件生态丰富可以扩展数学公式、自定义容器、脚注等高级语法。我最终选了 markdown-it不是因为它的 API 更好看而是它的渲染管线里可以嵌入自定义逻辑。比如给每个代码块包一层带语言标签的容器方便打印样式里针对性配色再比如给外链自动补 target_blank 和 relnoopener。这些活 markdown-it 做起来很干净。代码高亮这块我用 highlight.js 配合 markdown-it 的 highlight 配置。这里必须提醒一个安全细节高亮回调返回 HTML 字符串时如果代码内容本身包含尖括号比如用户写了一段 HTML 示例一定要用 markdown-it 的 escapeHtml 先转义否则轻则样式错乱重则脚本注入。我见过不止一个项目栽在高亮函数直接返回 innerHTML这种写法上。2.2 数学公式的接入时机如果文档里会出现数学公式很多人的第一反应是先加个公式插件再说。实际上公式插件的选择直接影响后续 PDF 导出难度。Markdown 里写公式通常用 LaTeX 语法行内公式 $...$块级公式 $$...$$。markdown-it 默认解析不了这类语法需要装 markdown-it-katex 或 markdown-it-texmath。我推荐 markdown-it-katex因为它底层绑定 KaTeX渲染速度快输出的是干净的 HTML 加 CSS 类名。但这里有一个打印场景才暴露的问题KaTeX 依赖自己的字体文件如果你在导出前没有等字体加载完成截图或者打印时公式里的字符就会用系统字体替代表现成乱码或字母错位。所以无论走哪条导出路线触发导出前都要等 document.fonts.ready 这个 Promise 兑现。这个细节在第五章排查表里我还会重点说。2.3 代码高亮、引用块和 callout现在的 Markdown 内容早就超出了标准语法范围。GitHub 风格的 callout 提示块也就是 [!NOTE] 这种写法用的频率越来越高。我通过 markdown-it-container 插件扩展了一个 note 类型容器渲染成一个带浅色背景和左边框的区块。这样导出的 PDF 里提示、警告、引用三者有明确的视觉层次。代码高亮在打印场景有个典型问题highlight.js 的主题大多是为屏幕设计的很多主题是深色背景配亮色文字。屏幕上看很有科技感打印到纸上就成了大黑块费墨还看不清。我单独写了一套针对打印环境的代码块配色在 media print 内部把代码块背景换成近白色文字换成深色。这事不做用户导出的 PDF 里代码区域基本不能看。3. html2pdf.js 路线从网页到 PDF 文件如果你的产品确实不能接受打印预览弹窗html2pdf.js 是目前纯前端方案里最省事的库之一。它把网页截图、PDF 封装两步合并成一行 API。但它的简洁是建立在牺牲部分可控性之上的这一节把我自己和身边同事踩过的坑都整理出来。3.1 基本接入与核心参数配置html2pdf.js 的常规用法是拿到一个 DOM 节点传入配置对象执行导出。一个接近生产环境的配置大概是import html2pdf from html2pdf.js; const element document.getElementById(pdf-content); html2pdf() .set({ margin: [10, 10, 10, 10], filename: markdown-export.pdf, image: { type: jpeg, quality: 0.95 }, html2canvas: { scale: 2, useCORS: true, logging: false, backgroundColor: #ffffff }, jsPDF: { unit: mm, format: a4, orientation: portrait } }) .from(element) .save();参数里最容易纠结的是 scale。它决定截图分辨率scale 为 1 时文字边缘会有明显锯齿为 2 时肉眼基本看不出区别但处理时间会翻倍长文档的 canvas 尺寸也大得多移动端直接可能内存爆掉。我的经验是桌面端用 2移动端降到 1.5 或者 1同时尽量压缩文档长度。margin 这个参数也需要理解清楚它跟 CSS 里的 margin 是两码事它控制的是 PDF 页面四周留白单位跟随 jsPDF 的 unit。如果你在 CSS 里又设置了容器的 padding最终 PDF 内容区域会显得特别小所以要养成容器内边距清零PDF 边距通过参数控制的习惯。3.2 图片和表格最大变量图片跨域是 html2pdf.js 翻车概率最高的问题。Markdown 里的外链图片如果没有被正确设置 CORShtml2canvas 在绘制时会把 canvas 标记为被污染导出的 PDF 里图片位置就是一片空白。我的处理套路是渲染阶段给所有外链图片加上 crossOriginanonymous 属性同时要求图片服务器返回 Access-Control-Allow-Origin 响应头。useCORS: true 配置能自动处理一部分但服务器不配合的时候谁也没办法只能走代理或者把图片先转成 base64。表格问题更严重。html2canvas 对长表格的分页支持很弱表格一旦跨页后半部分大概率直接消失。我实际测试过一张 20 行的表导出后第一页只有前几行分页之后的内容全没了。社区里的 hack 方案包括把大表格拆成多个小表格、降低 scale 强行压缩但效果都一般。如果你的产品里表格是高频内容我建议直接放弃 html2pdf.js 走原生打印这不是库不好是 canvas 截图这条路的物理限制。3.3 字体、动画和长文档的坑字体渲染是第二个深坑。html2canvas 对 web font 的截图支持不稳定中文环境下表现尤其明显。系统字体还好但在使用自定义字体——比如思源黑体、某些品牌字体时截图后经常出现字形偏移、加粗失效甚至乱码。我后来导出的页面一律使用标准字体栈不在导出区域引入任何 web font。动画和懒加载的问题比较隐蔽。如果页面里存在 CSS transition 或者图片懒加载截图时可能抓到一个中间状态比如半透明的按钮、还没加载的图片。我的处理方法是导出前给根节点临时加一个 .exporting 类所有动画在这个类下被禁用图片则用 Promise 全部等待 load 完成后才允许触发导出。这套逻辑在原生打印路线里同样适用。还有一个内存问题文档超过二三十页时html2canvas 生成的 canvas 尺寸可能是屏幕分辨率的几倍移动端崩溃率极高。有些项目按 section 分批截图再用 jsPDF 的 addPage 和 addImage 手动拼页代码量不小但确实能缓解内存压力。这种方案我在一个报表项目里实现过属于能跑但维护成本高的典型。4. 浏览器原生打印路线浏览器原生打印的底层逻辑其实很朴素浏览器本身就是个力量强大的排版引擎它懂得怎么把一张连续页面切成符合纸张大小的逻辑页。我们要做的是给它一套针对性样式让它切得好看一点。这条路线的核心就是 media print。4.1 media print 基本框架先给页面写一套打印专用样式骨架如下media print { body { width: 100%; margin: 0; padding: 0; background: #ffffff; } .no-print { display: none !important; } .print-content { width: 100%; font-size: 14px; line-height: 1.6; } }页面上的导航栏、工具栏、按钮、广告位统一加上 no-print 类名打印时它们会自动消失。这里有个隐蔽问题浏览器打印时自身会有一个默认页边距同时你的容器如果还有 padding最后效果就是内容整体缩了一圈。我的习惯是打印样式里把 body 的 margin 和 padding 全部清零具体留白交给打印对话框的边距选项去控制这样所见即所得。4.2 分页控制break-* 属性分页控制是原生打印最值钱的能力对应 CSS 属性主要是 break-before、break-after、break-inside。我实际用下来的经验media print { /* 每个一级章节另起一页 */ section.chapter { break-before: page; } /* 表格行、代码块、图片内部不允许拆散 */ tr, pre, img, blockquote, .callout { break-inside: avoid; } }break-before: page 适合放在一级标题所在的 section 上让每个大章节从新一页开始PDF 的结构感立刻出来。break-inside: avoid 是保护性规则主要防表格行被拦腰切断、代码块在中间断行、图片被切成两半。还有一个进阶技巧如果你不想每个章节都强制另起一页可以用 break-after: avoid 和 break-before: avoid 的组合告诉浏览器尽量让我跟相邻元素在一起但实在放不下可以拆。这种相对宽松的约束适合二级标题以下的内容能有效减少页尾大片留白。4.3 颜色、链接和边距的隐藏细节打印样式里颜色是个容易出歧义的点。浏览器默认在打印时会去掉背景色以省墨所有带背景色的元素——比如代码块、表头、提示框颜色会直接消失。解决办法是在打印样式中给需要用背景色的元素加 -webkit-print-color-adjust: exact但如果整个页面是深色模式打印之前强烈建议切换成浅色否则打印出来的 PDF 会是一坨墨。链接的处理也值得单独做一条规则。文档类内容打印出来后用户如果想顺着链接继续查资料纸面上没有任何提示是不方便的。我给所有正文链接加了一个伪元素输出完整 URLmedia print { a[href]::after { content: ( attr(href) ); color: #666; } }注意这条规则要配合类名过滤避免按钮链接、锚点链接、纯功能链接后面拖一串多余文字。我是在渲染时给正文区域的链接加了 .text-link 类只对这个类生效而不是全局 a 标签。4.4 触发打印的时机与体验细节触发打印本身一行代码就够window.print();难点不在触发在时机。如果页面内容是异步渲染的——Markdown 解析、图片加载、KaTeX 公式渲染、代码高亮这些任务全部完成前调用打印用户会看到残缺或样式错乱的打印预览。我写了一个等待函数集合所有异步任务完成后才调用async function waitForContentReady() { await document.fonts.ready; const imagePromises Array.from(document.images).map((img) { if (img.complete) return Promise.resolve(); return new Promise((resolve, reject) { img.onload resolve; img.onerror reject; }); }); await Promise.all(imagePromises); } async function handleExportPdf() { await waitForContentReady(); window.print(); }这里有个体验细节window.print() 是同步阻塞的打印预览关闭后页面状态要恢复正常。我一般建议在调用前给 body 加一个 .is-printing 类把页面上的交互元素禁用或者隐藏再用 afterprint 事件清理掉这个类。如果使用 iframe 方式打印还要记得打印完把 iframe 移除避免内存泄漏。5. 常见问题排查速查表这一节把我在真实项目里遇到过的高频问题整理成速查表每一条都是实际踩过的坑附上原因和解决路径方便你对照排查。5.1 表格内容被截断或错乱现象是打印时表格宽度超出页面右半部分被切掉或者表头只在第一页出现。根因通常是表格的默认宽度跟随内容尤其是连续英文或数字长字符串不换行时会把表格撑破。解决办法是给表格加 table-layout: fixed给单元格加 word-break: break-word。多页表格的表头重复可以用 thead 配合现代浏览器的打印分页机制多数浏览器会自动在每页重复表头如果不生效可以考虑在分页位置手动插入重复表头行。5.2 数学公式渲染异常现象是 KaTeX 公式在屏幕正常导出到 PDF 后变成乱码或者字符错位。原因几乎都是字体加载时序问题公式使用了专属字体导出前字体未完全载入截图或打印时就用了回退字体。解决路径是触发导出前等待 document.fonts.ready同时确保打印样式里显式声明了 KaTeX 的 font-family。如果问题反复出现还有一个备用方案是把 KaTeX 输出切换到 SVG 模式SVG 在打印场景下比字体模式稳定得多。5.3 图片跨域与清晰度现象是外链图片在 PDF 中显示空白本地图片则模糊。空白必然指向 CORS 问题解决思路是给图片加 crossOriginanonymous 并让服务端返回允许跨域的头模糊则基本是分辨率设置过低html2pdf.js 里调高 scale 即可。但如果你走原生打印路线图片清晰度这件事基本不存在——浏览器打印输出的图片是矢量级重新采样清晰度上限远高于 canvas 截图。5.4 中文字体与打印性能现象是使用系统默认字体打印中文没问题换成思源黑体这类大体积字体后打印预览卡顿甚至字距异常。原因是打印引擎需要嵌入完整字体文件中文字体动辄几 MB嵌入过程开销很大。经验做法是打印样式里优先用系统中文字体栈比如 macOS 的苹方、Windows 的微软雅黑品牌字体一定要用的话建议评估服务端方案而不是让每个用户的浏览器硬扛几 MB 的字体嵌入。5.5 页面参差不齐的大段留白现象是每个章节末尾的空白特别大仿佛排版偷懒。原因多半是 break-before: page 用得太激进内容只有几行也被强制推到新一页。解决思路是分页规则要有层级感一级章节用强制分页二级以下用 break-after: avoid 和 break-before: avoid 这种宽松约束让浏览器根据实际空间灵活排版。必要时还可以给正文容器加一个最终页检测的逻辑在内容明显能塞进当前页时去掉强制分页类。6. 我的最终选型建议与实践心得如果你问我到底用哪条路线我的答案非常直接只要产品能接受用户多一步操作浏览器原生打印就是纯前端方案里最稳的选择。它输出的是真正的矢量文字PDF 里的文字可以选中、复制、搜索文件体积小而且分页能力由排版引擎把关复杂表格和代码块的表现远好于 canvas 截图。html2pdf.js 更适合必须静默生成文件、不允许任何弹窗的交互约束但你要为它在复杂内容上的脆弱性买单。我在实际项目里的最终做法是一套组合方案默认导出按钮走 window.print()并且用一个 iframe 加载渲染好的文档副本只在 iframe 里触发打印这样主页面交互完全不受影响如果产品坚持要静默导出才退回 html2pdf.js 作为兜底同时把导出文档控制在简化结构范围内比如限制表格行数、压缩代码块长度、禁用自定义字体。这套策略让两条路线的价值都能发挥代价是两套样式和两套测试路径但换来的是不同交互场景下的可靠输出。最后分享一个小经验无论你选了哪条路线开发阶段一定要用超长文档做压力测试。我见过太多方案在小样上完美运行一放进几十页的真实文档就崩掉——不是分页乱了就是内存爆了。Markdown 转 PDF 这件事真正的难点从来不是能不能转出来而是大文档能不能还保持好看。把精力投入在分页、字体、表格、公式这几个硬骨头上你的导出功能就成功了一大半。