做PDF预览功能的那几天，我一直有个错觉：只要在普通网络下把组件跑通，弱网环境无非就是慢一点。后来我发现完全不是这么回事。某次我把浏览器开发者工具里的网络切到节流模式，再刷新页面，vue3-pdf-app这个内部组件直接卡在加载中，第一页始终不出来。更诡异的是，第一次刷新必现，第二次刷新又大概率恢复正常。这个"偶发"问题耗费了我整整一个下午，最后定位下来，既不是PDF文件本身损坏，也不是组件代码写错，而是节流模式下的本地缓存命中，恰好戳破了组件初始化顺序里的一个竞态。
这篇文章就把整个排查过程、根因分析、修复方案和通用排查思路完整记录下来。内容适合正在做Vue 3 PDF预览功能的开发者，也适合所有遇到过"弱网下缓存资源导致组件不渲染"问题的人。我不打算从框架原理开始讲，就直接按照我当时排查的顺序来。
1. 白屏现场：从正常网速切到节流模式后的第一个异常
1.1 最简复现路径：三步必现
这个问题的复现路径意外地简单，不需要任何特殊操作。我自己验证了很多遍，基本是三步必现：
- 把开发者工具切到Network面板，把网络节流模式改成Slow 3G，也就是模拟弱网。
- 保持DevTools打开，刷新页面。
- 观察组件区域：页面其余部分渲染正常，但PDF容器一直显示loading文案，控制台没有任何红色报错。
注意一个前提：如果DevTools没有打开，这个规律不一定每次都能复现。打开DevTools之后，页面请求的转发路径会有细微差别，缓存命中行为也不一样。这也是它容易被当成"偶发Bug"的原因之一。
如果你是在远程调试、或者用手机模拟器弱网复现，可能也需要留意类似因素。总之，只要能稳定复现，问题就成功了一半。
1.2 网络面板读出来的三条异常线索
第一次出现白屏时，我先看Network面板，而不是急着去看组件代码。因为我清楚，组件不渲染通常是数据没到位，数据请求的异常基本都能在网络面板里看出来。
打开Network面板，我注意到三条比较反常的线索：
第一，PDF资源的请求状态码是200，但Size列显示的是(memory cache)，不是正常的网络体积数字。这说明这次请求根本没走到远端服务器，而是直接命中了浏览器本地缓存。在Slow 3G节流模式下，按理说所有网络请求都会被限速，但缓存命中的请求不受节流影响，体感就是"瞬间返回"。
第二，点开这条请求的响应信息，发现响应头里带有明显的强缓存字段，比如Cache-Control: max-age=31536000。这类针对静态资源的默认缓存策略很常见，但它完全没考虑我们的PDF预览组件对数据到达时机有特定要求。
第三，也是最让我困惑的：请求体的字节数看起来正常，不是0KB，也不是截断的半个文件。这说明缓存里存的是一份完整PDF。问题是为什么组件拿到数据后没有渲染？
这条线索很重要，它把我从"数据损坏"的方向引开，转向"数据到达时序"的方向。
1.3 让我误判的"二次刷新恢复"
更让人头疼的是，页面第二次刷新就正常了。第一次刷新白屏，第二次刷新PDF正常显示，这非常容易让人认为是"偶发网络抖动"。
其实第二次刷新正常，恰好暴露了根因的一部分特征。第一次刷新时，页面是冷启动，组件刚挂载就发起了加载请求，而请求又因为强缓存被"瞬间命中"，组件内部的状态还没来得及流过完整的初始化流程。第二次刷新时，虽然请求还是命中缓存，但组件的运行时状态、监听器、渲染环境都已经准备得差不多了，再收到缓存数据就能正常走完渲染。
所以这不是什么"偶发"，而是固定模式下的初始化竞态。你越是在网速快的时候测试，越难发现它；一旦切到节流模式，浏览器对缓存资源的"本地直达"特性就把它暴露出来。
2. 深入组件内部：为什么缓存命中反而让状态卡住
2.1 组件加载PDF的四段链路
要理解这个Bug，先得知道vue3-pdf-app组件内部加载PDF的基本链路。我们内部把这条链路拆成了四段：
第一段是资源请求。组件根据传入的URL发起fetch，拿到PDF文件的二进制数据。第二段是数据校验。组件检查拿到的数据是不是合法PDF，比如文件头是否是%PDF，字节长度是否大于0。第三段是解析初始化。PDF解析内核被创建，开始加载数据并生成文档结构。第四段是渲染准备。解析器返回第一页页面对象，组件把它挂到DOM容器上，loading状态关闭，用户看到内容。
这个四段链路可以类比成"买书 - 验书 - 翻书 - 看书"。任何一段没走完，最后都不会出现内容。
2.2 "请求完成"与"渲染就绪"是两个独立事件
正常情况下，链路是顺序执行的：请求完成，然后校验，然后解析，然后渲染。但在我们组件里，存在一个容易忽略的设计：请求完成事件和渲染就绪事件不是绑定在一起的。
组件内部把加载动作拆成了两个并行的模块。一个模块负责从网络层拿二进制数据，数据处理完成后它会更新一个store；另一个模块负责监听解析器状态，解析器准备就绪后再去渲染。两个模块各自维护自己的状态，只有两个状态都满足时，组件才隐藏loading。
问题就出在这里：如果请求模块先完成、store先更新，但渲染模块的初始状态没有被正确触发，组件就会一直等。你可以想象成一个简单的"与门"逻辑：isDataReady && isRendererReady才显示内容。数据到了，但渲染模块没就绪，门就一直关着。
2.3 缓存瞬时返回对这两个事件的影响
在普通网络下，这两个模块的完成时间天然存在一个时间差。网络请求要经过DNS、TCP、服务端处理，通常需要几十毫秒到几百毫秒。这个时间差反而给两个模块提供了"缓冲窗口"：数据还没到的时候，渲染模块已经把监听器注册好了，等数据到达时事件能被正确接收。
但在节流模式+本地缓存的情况下，请求不再经过网络栈。浏览器从本地缓存里直接取出数据，Promise几乎在同一个事件循环里就resolve了。这时候组件内部的监听器可能还没注册完毕，或者渲染模块的初始化Promise还挂在队列里，数据就已经回来了。事件丢给了"空气"，组件自然就卡死了。
说难听一点，平时测试之所以顺利，不是因为代码严谨，而是网络慢掩盖了时序缺陷。一旦缓存把中间延迟抹平，缺陷就暴露无遗。
3. 根因确认：节流模式下缓存响应绕过了时序保护
3.1 正常模式下时序保护为何生效
在详细阅读代码之后，我定位到组件内部的一个具体现象。加载逻辑大概长这样：
// 这里的代码是简化后的模拟结构 async function loadPdf(url) { const cached = pdfStore.get(url) if (cached) { // 命中缓存：直接使用缓存数据 renderPdf(cached) return } const resp = await fetch(url) const data = await resp.arrayBuffer() pdfStore.set(url, data) renderPdf(data) }问题出在renderPdf(cached)这个分支上。renderPdf内部会先等待一个rendererReadyPromise，这个Promise是在组件挂载完成后的异步任务中才会resolve的。正常网速下，fetch(url)还在等待网络响应，异步任务早就跑完了，rendererReadyPromise也已经准备好了。等renderPdf被调用，自然能顺利走下去。
缓存命中时就不一样了。pdfStore.get(url)返回缓存数据，renderPdf(cached)在同步代码中几乎立刻就被调用。但此刻rendererReadyPromise可能还没进入resolved状态，renderPdf里面又在await这个Promise，于是整个流程被卡在等待队列里。
3.2 缓存命中时为什么不会等待网络延迟
可能有同学会问：本地缓存命中也是要读磁盘、解数据的，为什么就不会延迟？
这里要区分两类"缓存"。我们项目里有两层缓存，一层是浏览器HTTP缓存，一层是应用内pdfStore的JS对象缓存。HTTP缓存命中时，浏览器从本地存储读取资源，虽然也要消耗一点时间，但这个时间远小于网络往返，通常在毫秒级。所以在节流模式下，它体现为"瞬间返回"。
而应用内缓存更极端，pdfStore.get(url)就是在内存里拿一个对象，连I/O都没有。它跟网络节流没有半点关系。结果就是，节流模式只是让真正的网络请求变慢，却让应用缓存绕过网络限制，产生了一个"快得不正常的路径"。
这里最反直觉的点在于：平时网络请求慢，我们还会刻意加一些loading状态来覆盖等待期；但应用缓存这条路不需要等待，代码里反而没有做任何时序保护。慢路径没问题，快路径出问题了。
3.3 用最小实验验证根因
为了确认判断不是猜测，我做了两个最小实验。
第一个实验是绕过应用缓存。我在pdfStore.get(url)前临时加了一行日志，并且直接禁用缓存分支，强制走网络请求。切到节流模式，刷新页面，PDF功能完全正常，只是加载时间变长了。
第二个实验是反过来，强制走缓存分支。我修改了代码，故意让renderPdf在组件挂载后的第一个微任务里执行，模拟缓存命中时的瞬时调用。结果在普通网络下也复现了白屏。
这两个实验一对照，根因就非常清晰：不是缓存数据有问题，而是缓存分支的调用时机破坏了renderPdf内部的等待机制。
3.4 顺带发现的Cache-Control隐患
在排查过程中，我还发现了另一个隐患，虽然它不是这次白屏的直接原因，但值得记录。
后端返回PDF文件时，响应头里配置的是强缓存策略，max-age长达一年。这本来是为了让重复查看同一份PDF时省流量，但对一个经常更新的合同预览系统来说，这个策略很可能导致用户在PDF文件更新后仍看到旧版本。
特别是我们切到节流模式测试场景时，开发者工具不会给用户带来额外帮助；真实弱网用户遇到强缓存资源时，同样可能拿到过期版本。所以修复白屏问题之外，我建议后端同学重新评估PDF资源的缓存头，至少对动态生成的PDF使用Cache-Control: no-cache，或者加入版本号查询参数。
4. 从请求层和组件层同时加固的修复方案
4.1 请求层：PDF资源URL改为强制无缓存
第一个修复动作，是把PDF资源请求从"尽量用缓存"改成"不使用缓存"。这一步操作很简单，但对解决白屏问题最直接。
在fetch请求里我们可以通过cache选项控制浏览器缓存策略：
async function loadPdfBuffer(url) { const resp = await fetch(url, { cache: 'no-store', }) if (!resp.ok) { throw new Error(`PDF资源请求失败：HTTP ${resp.status}`) } const buffer = await resp.arrayBuffer() // 做一个基础校验：空数据直接判失败 if (!buffer || buffer.byteLength === 0) { throw new Error('PDF数据为空，请重新检查资源地址') } return buffer }cache: 'no-store'的作用是让本次请求完全不写入HTTP缓存，也不读取HTTP缓存。这样即使用户在弱网下反复刷新页面，PDF资源每一次都会真正走网络请求，不会命中"瞬间返回"的本地缓存。
当然，这里的代价是，同一份PDF在短时间内多次打开时会重复下载。考虑到PDF预览通常不是高频操作，我认为这个取舍很合理。如果你确实想保留缓存，也可以改成cache: 'no-cache'，意思是"使用时校验缓存、过期后再下载"，但这就需要在请求头或查询参数里带上版本标识，实现复杂度会更高。
4.2 组件层：数据就绪和渲染就绪双条件合并
只改请求层还不够。因为我们内部的renderPdf还有一个独立的rendererReadyPromise等待逻辑，即便强制走了网络请求，弱网场景下请求耗时较长，组件状态流也可能被某些原因打断。所以组件层也要加固。
我的做法是，把"数据就绪"和"渲染就绪"两个条件合并成一个统一的门槛。具体地说，渲染前必须同时满足两个条件：第一，PDF二进制数据已经拿到；第二，渲染器已经完成初始化。两个条件都满足时，才允许真正执行渲染。
代码层面可以这样封装：
let rendererReady = false const rendererReadyWaiters = [] function signalRendererReady() { rendererReady = true rendererReadyWaiters.forEach((resolve) => resolve()) rendererReadyWaiters.length = 0 } async function waitForRendererReady() { if (rendererReady) return await new Promise((resolve) => { rendererReadyWaiters.push(resolve) }) }这样的设计可以保证：无论数据先到还是渲染器先就绪，都会等另一个条件补齐后才执行渲染，不会出现"事件丢给空气"的问题。
4.3 增加请求序号，解决连续刷新竞态
除了上面两个修复，我还考虑到了用户快速刷新页面的场景。如果组件同时发起多个加载请求，后一次请求的结果可能覆盖前一次的结果，导致显示内容错乱。所以我在加载函数里加了一个简单的序号校验。
let loadSeq = 0 async function loadPdf(url) { const currentSeq = ++loadSeq try { const buffer = await loadPdfBuffer(url) // 如果加载期间被新的请求打断，直接丢弃这次结果 if (currentSeq !== loadSeq) return await waitForRendererReady() // 渲染前再做一次序号校验 if (currentSeq !== loadSeq) return renderPdf(buffer) } catch (error) { // 只有最新的一次请求才允许弹错误 if (currentSeq === loadSeq) { showPdfError(error) } } }这个方案解决的是请求竞态，跟缓存问题不冲突。弱网下用户最容易反复刷新，每次刷新都会产生新的请求，如果不对旧请求做抛弃处理，旧的慢请求可能在新的请求已经渲染完成后才返回，导致页面被重新覆盖成旧内容。
4.4 修复后的运行结果
修复完成后，我重新按照复现路径做了多轮验证。
在节流模式下刷新十次，没有再出现白屏。每次加载的耗时稳定在几秒到十几秒之间，loading状态会持续到渲染真正完成。第二次刷新也没有出现"偶发恢复"的情况，因为请求层已经把缓存路径堵死，每次加载都走同一个稳定流程。
另外，我把Network面板切回普通网速测试，发现修复并没有给正常场景带来额外负担。PDF文件体积如果较大，fetch仍然会正常下载，loading状态也更准确了。整体体验反而比之前"玄学式成功"稳定得多。
5. 排查"节流+缓存+组件不渲染"问题的通用Checklist
5.1 从网络面板先判断缓存状态
这类问题将来你可能还会遇到，不只是PDF组件，任何"弱网模式下资源被缓存导致组件不渲染"的问题，排查思路都类似。我把自己沉淀的一套检查清单放在下面。
第一步，先打开开发者工具的Network面板，看故障资源的请求详情。重点看三列：Status Code、Size、Time。
- 如果Status是
200，但Size显示(memory cache)或(disk cache)，说明命中了HTTP缓存。 - 如果Time接近0ms，说明数据不是从网络来的。
- 如果请求头里带了
Cache-Control相关字段且允许缓存，基本可以确认缓存参与。
第二步，在Network面板里勾选Disable cache，再刷新页面看问题是否复现。如果取消勾选后问题消失，说明HTTP缓存就是关键路径之一。
第三步，在Application面板查看缓存存储，特别是Service Worker Cache Storage。有时候问题不止来自HTTP缓存，还可能来自Service Worker的预缓存策略，这个要单独排查。
5.2 从组件状态判断时序问题
网络面板只是第一步。如果资源请求本身没有报错，数据也完整，那就要把视角切到组件内部。
重点关注三件事：请求完成的回调、渲染器初始化的回调、以及组件loading状态的切换代码。问自己三个问题：
- 请求完成回调是不是有可能在渲染器初始化回调之前执行？
- 组件loading状态的关闭是不是同时依赖这两个回调？
- 如果有多个请求并发，会不会出现旧请求覆盖新请求的情况？
台账式地把每个回调触发条件写出来，通常就能很直观地看到竞态窗口在哪里。
我遇到过不少类似的坑，表面看是"缓存导致问题"，实际是"某个Promise在错误时机resolve了"。缓存只是改变了事件的到达顺序，真正需要修的是组件对事件顺序的假设。
5.3 常见误判和我的建议
最后一个部分，说说我经历过的误判。
最常见的误判是，看到缓存命中就直接断定"是缓存头配置错了，改成不缓存就完事"。但实际上，如果组件内部时序本身就是脆弱的，即使你强制无缓存，在复杂的弱网环境下还是可能复现其他症状。所以真正的修复应该是"请求层防缓存 + 组件层防竞态"双管齐下。
第二个常见误判是，用setTimeout延时绕过问题。比如有人发现缓存命中后加一个setTimeout就能正常，于是加了个500ms延迟。我非常不建议这种写法。因为延时是拍脑袋的，无法覆盖不同设备、不同网络、不同浏览器之间的差异，只会把问题压制到一个没那么容易复现但依然存在的角落。
第三个误判是，把问题归咎于"PDF解析库不稳定"。实际上底层解析库在绝大多数情况下都是无辜的。如果数据能正常到达，解析器通常都能正常工作。排查时优先怀疑自己的封装层，再怀疑底层库，顺序不能反。
我的核心建议是，所有涉及异步初始化的组件，都应当把"数据来源"和"渲染就绪"做成显式的依赖关系，而非隐式的心存侥幸。缓存也好，节流也好，它们会让代码里所有不清晰的地方加速暴露。与其每次靠运气，不如把时序设计得严谨一些，这才是这类问题真正的解决之道。
这次之后，我还顺手把我们项目里其他几个涉及大资源加载的组件也都过了一遍，凡是存在类似"先拿数据再初始化渲染器"模式的，全部补齐了双条件等待逻辑，短期内应该不会再被这类问题困扰了。
