昨天半夜两点，我盯着屏幕上的那个红色报错框，心里真是有一万头草泥马奔腾而过。又是网页生成pdf失败。这已经是本周第三次了。客户那边催得紧，说是要把这一整篇长达五十页的技术文档转成PDF归档，结果转出来全是乱码，图片还缺胳膊少腿的。
说实话，现在市面上那些号称“一键转换”的工具，吹得天花乱坠。什么AI智能识别，什么高清无损，全是扯淡。真到了生产环境，稍微复杂点的页面，立马现原形。
我干了五年前端，也搞过不少后端服务，这种坑踩过无数回。今天不整那些虚头巴脑的理论，就聊聊我这次是怎么把这个烂摊子收拾干净的。如果你也遇到网页生成pdf失败的问题，不妨看看下面这几步，或许能救你的命。
第一步，先别急着换库。很多人一报错，第一反应是“jsPDF不行”、“html2canvas太烂”，然后换这个换那个。其实，大部分时候，问题出在CSS上。特别是那些用了Flex布局或者Grid布局的页面，渲染引擎根本看不懂。你得去检查你的样式表。有没有用绝对定位？有没有用z-index堆叠？这些在DOM转Canvas的时候，全都会乱套。我这次就是发现了一个隐藏的iframe，里面嵌了个视频，结果视频帧直接导致内存溢出，生成直接失败。把视频换成静态封面图，瞬间搞定。
第二步，异步加载的内容，必须等它渲染完。这点太关键了。很多现代前端框架，比如Vue或者React，数据是异步拉取的。你调用生成函数的时候，数据还没回来呢，DOM还是空的或者只有一半。这时候生成的PDF，当然也是半成品。我之前的做法是加个setTimeout，那是偷懒的做法，不靠谱。正确的做法是监听DOM变化。用MutationObserver，或者更简单的，等你那个异步请求的Promise resolve之后，再触发生成逻辑。别嫌麻烦，这是基本功。
第三步，分页处理是个玄学。默认的插件，对分页的支持烂得一塌两断。文字被拦腰切断，图片被切成两半，客户看了直骂娘。这时候，你得手动干预。在CSS里加上page-break-inside: avoid;，告诉浏览器，别把表格或者卡片切成两半。虽然不能保证100%完美，但能解决80%的尴尬情况。还有，如果页面特别长，别试图一次性生成。分段生成，然后合并。虽然代码复杂了点，但稳定性提升不止一个档次。
我这次还发现一个隐蔽的坑，就是字体。有些特殊字体，在服务器上没安装，或者WebFont加载失败，生成的PDF里就会变成默认字体，甚至显示成方块。解决办法很简单，把字体文件转成Base64，直接内嵌到CSS里。虽然会让CSS文件变大几KB，但为了不出错，这点代价值得。
最后，别迷信前端生成。如果页面复杂到一定程度，比如包含大量图表、复杂交互，前端生成的质量真的很难保证。这时候，不如把HTML发给后端，用Puppeteer或者Headless Chrome在服务端生成。虽然部署麻烦点，但渲染效果是浏览器原生的，绝对靠谱。
总之，网页生成pdf失败，真的不是单一原因。它可能是CSS的锅，可能是异步加载的锅，也可能是字体或者分页的锅。别一遇到问题就换工具，先静下心来，看看控制台，看看DOM结构，看看网络请求。
这事儿急不得。我花了一晚上排查，最后发现就是一个小小的CSS属性没写对。如果你也在为这个问题头疼，不妨从最简单的样式入手，一步步排除。别慌，总能解决的。
记住，代码是写给人看的，顺便给机器执行。把逻辑理顺了，机器自然就听话了。别再问为什么又失败了，看看你的代码，是不是又偷懒了？
