从“Stream must have data”出发：深度剖析PDF.js文件加载失败的全链路排查

1. 当PDF.js抛出"Stream must have data"时究竟发生了什么

第一次在控制台看到这个错误时，我盯着屏幕愣了三秒——明明文件已经上传成功，为什么PDF.js会提示"没有数据"？这就像你去ATM取钱，银行卡插进去了密码也输了，机器却告诉你"账户不存在"。后来在多个项目中反复踩坑后，我才理解这个看似简单的错误背后，其实藏着从客户端到服务端的完整数据链路问题。

PDF.js的工作原理其实很像一个快递系统：当你调用pdfjsLib.getDocument()时，它会发起一个"取件请求"，这个请求需要完整经历以下环节：

1. 前端正确构造请求（填写快递单）
2. 网络稳定传输（快递运输）
3. 服务端返回有效PDF数据（包裹完好）
4. 浏览器正确解析响应（签收验货）

最近在调试一个Vue项目时遇到典型场景：本地开发环境预览正常，但部署到测试环境就报错。用Chrome开发者工具检查Network面板才发现，生产环境的API地址配置错误导致实际请求404，但PDF.js只笼统地报了"Stream must have data"。这就是为什么我们需要建立系统化的排查思维——错误提示只是结果，真正的病因可能藏在任何环节。

2. 构建全链路排查框架：从浏览器到服务器的六层检查

2.1 前端请求层：你的请求真的发出去了吗？

先分享一个真实案例：某次我花了两个小时排查"数据缺失"问题，最后发现是前端路由配置错误，根本没触发PDF预览请求。所以第一步永远要确认——请求是否真实发出？

在Chrome开发者工具中，我会重点检查：

• Network面板是否有PDF相关请求（过滤XHR或Fetch类型）
• 请求URL是否包含特殊字符需要encodeURIComponent处理
• 请求头是否携带必要认证信息（如Authorization）
• 如果是POST请求，查看payload数据格式

javascript复制// 典型的问题请求示例 - 未处理特殊字符
const badUrl = `/api/pdf?name=${fileName}`; // 当fileName含#等字符时会截断

// 正确的请求构造方式
const safeUrl = `/api/pdf?name=${encodeURIComponent(fileName)}`;

2.2 网络传输层：数据包真的到达服务器了吗？

曾经有次在排查CDN问题时，发现某些地区用户始终加载失败。通过Charles抓包工具，我们最终定位到是某运营商中间节点丢弃了大于10MB的文件。网络层的问题往往最隐蔽，建议检查：

• 使用在线工具（如WebPageTest）多地域测试
• 检查Response Headers中的Content-Length是否与文件实际大小一致
• 大文件分片上传时是否所有chunk都成功（查看浏览器Network的瀑布流）

提示：当遇到跨域问题时，除了配置CORS头，还要注意服务器可能返回302重定向，这时需要确保重定向后的地址也在白名单中。

2.3 服务端响应层：返回的真是PDF文件吗？

有次运维同事"优化"了Nginx配置，导致所有PDF请求都被当作文本文件返回。这类问题需要检查：

• Response Headers中的Content-Type必须是application/pdf
• 状态码应该是200（如果是206要确认Range请求是否完整）
• 直接访问PDF链接，用hexdump查看文件头是否包含"%PDF"魔数

bash复制# 快速验证PDF文件完整性的命令行技巧
curl -I http://example.com/doc.pdf  # 检查headers
head -c 4 doc.pdf | xxd -p  # 应输出25504446（即%PDF的16进制）

3. 高级排查技巧：当常规方法都失效时

3.1 内存与性能分析：被忽视的资源瓶颈

在移动端项目中，我们遇到过iOS Safari频繁加载失败的情况。最终发现是浏览器内存限制导致——当同时渲染多个PDF页面时，Safari会静默丢弃部分数据。这类问题需要：

• 使用performance.memoryAPI监测内存使用
• 分页加载大型PDF文件
• 添加加载进度条和错误重试机制

3.2 PDF文件本体检测：隐藏在二进制中的陷阱

某些"表面正常"的PDF其实内部已经损坏。推荐使用以下工具深度检测：

• qpdf --check线性化验证
• mutool clean修复损坏文件
• PDFtk重建文件结构

javascript复制// 前端快速验证PDF完整性的代码片段
async function validatePDF(buffer) {
  const arr = new Uint8Array(buffer);
  // 检查文件头尾标识
  const headerValid = arr[0] === 0x25 && arr[1] === 0x50; 
  const footerValid = String.fromCharCode(...arr.slice(-5)) === '%%EOF';
  return headerValid && footerValid;
}

4. 防御式编程实践：构建健壮的PDF预览功能

经过多次惨痛教训后，我现在会给所有PDF预览功能添加三层防护：

1. 预处理校验（文件类型、大小限制）
2. 加载过程监控（超时中断、进度反馈）
3. 错误恢复机制（自动重试、降级方案）

javascript复制// 增强版的PDF加载示例
async function safeLoadPDF(url) {
  try {
    const loadingTask = pdfjsLib.getDocument({
      url,
      rangeChunkSize: 1024 * 256, // 优化大文件加载
      disableAutoFetch: true       // 精确控制流量
    });
    
    // 设置10秒超时
    const timer = setTimeout(() => loadingTask.destroy(), 10000);
    const pdf = await loadingTask.promise;
    clearTimeout(timer);
    
    return pdf;
  } catch (error) {
    if (error.name === 'TimeoutError') {
      console.warn('PDF加载超时，尝试分页加载');
      return fallbackLoadByPage(url);
    }
    throw error;
  }
}

在最近一次金融项目上线前，这套防护机制成功拦截了三个潜在的生产环境事故。记住，好的开发者不仅要会解决问题，更要设计出不让问题发生的系统。