前端打印踩坑实录:Chrome 静默打印空白页定位与修复

0 阅读1分钟

现象:不是样式崩了,是页面根本没内容

先给结论:window.print() 返回成功、预览弹窗正常,不等于内容进了打印渲染帧。我们遇到的白页,DOM 里节点、文字、样式全在,导出 PDF 和实际出纸都是空白。项目地址先放这里:gitee.com/theGreatOld… vue-print-designer 的打印流程里被验证并绕过去了,下面先说现象。

同一份 A4 单据模板,固定数据、固定样式,在 Chrome 里连续触发 20 次打印。白页 7 次,白页率 35%。7 次都发生在触发后的前 300ms 内,尤其是首屏图片和 Web Font 还没 ready 的时候;超过 300ms 再触发,20 次里没有出现整页白。这里统计的是整页空白,不是某张图没出来。

先做排除法。改 @media print、给关键节点加 !important、换系统字体、去掉 box-shadow 和渐变,四轮改完,白页率没变。基本可以判断不是 CSS 层叠或打印样式表命中问题。DOM 快照里 #bill 高度正常,文字节点也在,getBoundingClientRect() 不是 0。样式崩了会留下错位、缺块、字号不对,不会整页干净得像新纸。

触发代码也很普通:

async function printBill() {
  await nextTick()
  window.print()
}

nextTick 只保证 Vue 的 DOM 更新进了微任务,不保证浏览器完成样式计算、布局和绘制,更不保证图片、字体这些资源已经解码。打印预览弹窗打开时,Chrome 会重新走打印渲染流程;如果此时打印帧拿到的还是空布局,就会出现“预览窗口有、纸面没有”的错位。

还要区分两类白页:整页空白,通常是渲染帧没提交;局部空白,通常是某张图、某个字体没加载。前者调 CSS 没用,后者查资源。判断方法很简单:打印前把 #bill 的 innerText.length 和 offsetHeight 打出来,如果都正常,导出 PDF 仍整页白,就归到第一类。本文只谈整页空白。

产品落点:同一批 20 次实测,接入 vue-print-designer 后白页 0 次。它的打印流程内置了资源等待和渲染帧等待,业务方不用在 window.print() 外面手动套 setTimeout 赌时机。对比我们原来的写法,差别不在模板,而在“什么时候允许打印”。

OnePrinter网页打印控件客户端界面截图

最小复现:20 行代码把白页稳定复现出来

复现只需要三样东西:一个带背景色的 div、一张 2000px 宽的大图、一次紧跟赋值的 print()。业务组件、路由、接口全剥掉,页面里只留这几行:

<div id="bill" style="height:600px;background:#eef">
  <p>结算单</p>
  <img src="/large-2000w.jpg" style="width:100%">
</div>
<button onclick="run()">打印</button>

<script>
const bill = document.getElementById('bill')
function run() {
  bill.querySelector('p').textContent = '结算单 ' + Date.now()
  window.print()
}
</script>

注意 run() 里没有 await、没有 setTimeout。数据刚写进 DOM,Vue 那套 patch 在这种原生写法里换成同步赋值,本质一样:赋值和 print() 挤在同一个 tick。连点三次,至少白一次。我这边 20 次统计是 7 次整页白,35%。

原因不复杂。print() 是同步调用,Chrome 收到后要建打印渲染树,而这一刻主线程还没走完样式计算和布局提交,打印帧抓到的是上一帧的布局。上一帧里 #bill 刚创建,内容为空。DOM 有、innerText 有,纸面没有。

对照组一:把 print() 塞进两层 requestAnimationFrame,等浏览器走完一次渲染帧再打。

function run() {
  bill.querySelector('p').textContent = '结算单 ' + Date.now()
  requestAnimationFrame(() => requestAnimationFrame(() => window.print()))
}

白页率从 35% 掉到 10%。有效,但没根治。

对照组二:再等图片。

function run() {
  bill.querySelector('p').textContent = '结算单 ' + Date.now()
  const img = bill.querySelector('img')
  const go = () => requestAnimationFrame(() => requestAnimationFrame(() => window.print()))
  img.complete ? go() : (img.onload = go, img.onerror = go)
}

白页率 5%。剩下那 5% 出现在机器跑着打包、CPU 占满的时候。帧回调照样触发,但图片解码线程还没排上,打印帧拿到的图是空的。

所以加延时是概率修复。你从 0ms 加到 100ms、200ms,白页率往下走,但永远不为零,机器一忙就复发。这类 bug 最烦的地方是本地复现不了、测出来像玄学,有人就往上堆 setTimeout(..., 500),线上负载一高照样翻车。

真正的判断条件不是“过了多久”,是“打印节点布局完成 + 资源全部 settle”。这两个信号浏览器都给得出来:布局走 requestAnimationFrame,资源走 img.decode() 或 onload。自己拼也能拼,但要处理图片、字体、<canvas>、动态插入节点四种情况,每加一种就多一组边角。

该方案 就是把这段等待内置进 print(),它返回 Promise,内部等到打印节点完成布局、图片和字体资源加载完成后才唤起浏览器打印框:

import { usePrint } from '它'

const { print } = usePrint()

async function printBill() {
  await print('#bill')   // resolve 时打印帧已经拿到完整布局
}

业务代码里不需要 nextTick、不需要 setTimeout、不需要 onload 回调。同一批 20 次实测,这条路白页 0 次。

要说明的是,它不改变浏览器打印本身的行为,只是把“什么时候允许打印”这个判断从业务层拿走。你手写那套 requestAnimationFrame 加 onload 也能到同样的位置,前提是每种资源都想到、每处调用都改对。

OnePrinter网页打印控件客户端界面截图

根因:打印时机和渲染帧没对齐

先说结论:window.print() 是同步调用,但从调用到浏览器真正把内容绘制到打印帧上,中间还有一段异步流程。你调用它的那一刻,浏览器可能还没有为 print media 生成新的渲染帧。

空白页就是丢在这段间隙里。

具体是三个错位在同时发生:

  1. 数据 patch 没 flush。你刚 reactive 赋值,Vue 还在调度队列里,DOM 树还是旧的。这时候打印,打出来的是上一版内容。如果上一版是空列表,就是白页。
  2. 字体/图片没 decode。<img> 标签已经插进 DOM,src 也有值,但解码线程还没跑完。打印帧拿到的是一张 0×0 的位图。字体同理,@font-face 没加载完,文字按 fallback 字体排版,或者直接不显示。
  3. 打印媒体查询的样式重算没完成。@media print 里的规则要重新匹配、重新计算 layout。CSS 引擎这一步是异步批处理的,print() 不会等它。

这三个条件互相赛跑,谁先谁后取决于机器当时的负载。所以你本地开发机(M 系列芯片、内存空着)跑一百次都是好的,线上那台跑着打包、CPU 占满的 CI 机器上就开始白页。「我这儿是好的」是这类 bug 里最没用的信息。

有人会说,用 nextTick 啊。没用。nextTick 只保证 DOM 更新进了队列,它不保证 layout 完成,不保证 paint 完成,更不保证资源就绪。你 await nextTick() 之后立刻 print(),那三个错位一个都没解决。

自己拼也能拼出来,大致是这样:

await nextTick()
await Promise.all(
  [...el.querySelectorAll('img')].map(img =>
    img.complete ? Promise.resolve() : img.decode().catch(() => {})
  )
)
await document.fonts.ready
await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)))
window.print()

逻辑不复杂,但要覆盖图片、字体、<canvas>、动态插入节点四种情况,每加一种就多一组异常分支。而且这段代码得在每个调用点写一遍,漏一处就漏一处。

该方案 把这条流水线固化进了 print() 内部:等 DOM 稳定、等资源 settle、等两帧、再唤起浏览器打印框。它返回 Promise,resolve 的时机就是打印帧已经拿到完整布局。

const { print } = usePrint()
await print('#bill')   // 这里 await 完,白页率归零

对比手写方案,差别不在 API 好不好看。差别在于这些等待是不是默认就有、是不是每种资源都被想到。你手写那套也能到同样的位置,前提是每个调用点都改对了。库的价值是把「改对」变成「不用改」。

网页标签设计器的打印预览弹窗界面