pdf-js本地预览正常，线上环境加载失败

Question

问题：PDF.js在本地预览正常，但线上环境加载失败，常见原因是生产环境的MIME类型配置缺失或CORS策略限制。本地服务器默认允许文件读取，而线上未正确配置静态资源的Content-Type（如未将`.pdf`或`application/pdf`正确映射），导致PDF二进制流解析失败。同时，若通过跨域接口获取PDF，未设置`Access-Control-Allow-Origin`也会引发加载中断。需检查Nginx/Apache或CDN的MIME类型支持及响应头配置。

Answer 1

1. 问题现象与初步排查

在使用 PDF.js 实现前端 PDF 预览功能时，开发人员常遇到一个典型问题：本地开发环境（如 localhost）中 PDF 文件可正常加载和渲染，但部署至线上生产环境后，PDF 加载失败或白屏。通过浏览器开发者工具（F12）观察网络请求，通常会发现以下异常：

• HTTP 状态码为 404 或 403，表示资源未找到或权限不足。
• 状态码为 200，但响应体为空或为 HTML 错误页。
• 控制台报错：No "Access-Control-Allow-Origin" header present 或 Failed to fetch PDF。

这些现象提示我们，问题并非源于 PDF.js 本身的逻辑错误，而是与服务器环境配置密切相关。

2. 深层原因分析：MIME 类型与 CORS 策略

PDF.js 依赖于浏览器正确解析从服务器获取的 PDF 二进制流。若服务器未正确设置 MIME 类型或跨域策略，将导致解析失败。具体可分为两类核心问题：

2.1 MIME 类型配置缺失

MIME（Multipurpose Internet Mail Extensions）类型决定了浏览器如何处理特定文件扩展名。若服务器未将 .pdf 映射为 application/pdf，浏览器可能将其识别为 text/plain 或 application/octet-stream，从而无法交由 PDF.js 正确解析。

常见服务器默认配置对比：

服务器类型	.pdf 默认 MIME 类型	是否需手动配置
Node.js (Express)	需中间件支持	是
Nginx	通常已配置	视版本而定
Apache	依赖 mime.conf	可能需要
CDN（如 Cloudflare）	部分支持	需检查缓存规则
IIS	需手动添加	是

2.2 跨域资源共享（CORS）限制

当 PDF 文件存储在独立的静态资源服务器或对象存储（如 AWS S3、阿里云 OSS）时，若前端页面与 PDF 资源不在同一域名下，浏览器将触发 CORS 安全机制。若响应头中缺少 Access-Control-Allow-Origin，则 Fetch 请求被阻断。

典型错误信息：

Access to fetch at 'https://cdn.example.com/docs/report.pdf' 
from origin 'https://app.example.com' has been blocked by CORS policy: 
No 'Access-Control-Allow-Origin' header is present on the requested resource.

3. 解决方案实施路径

针对上述两类问题，需分别从服务器配置和响应头策略入手。

3.1 Nginx 配置示例

确保 /etc/nginx/mime.types 包含以下条目：

types {
    application/pdf pdf;
}

并在 server 块中启用 CORS 支持：

location ~* \.pdf$ {
    add_header Access-Control-Allow-Origin "*";
    add_header Access-Control-Allow-Methods "GET, OPTIONS";
    add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control";
    expires 1y;
    add_header Cache-Control "public, immutable";
}

3.2 Apache 配置方法

在 .htaccess 或虚拟主机配置中添加：

<FilesMatch "\.pdf$">
    Header set Access-Control-Allow-Origin "*"
    Header set Content-Type "application/pdf"
</FilesMatch>

# 确保 MIME 模块已启用
AddType application/pdf .pdf

3.3 CDN 层面的注意事项

使用 CDN 时，即使源站配置正确，CDN 缓存可能忽略或覆盖响应头。需在 CDN 控制台显式配置：

• 缓存规则：对 *.pdf 设置合理的缓存时间（如 1 年）。
• 响应头注入：强制添加 Access-Control-Allow-Origin: * 和 Content-Type: application/pdf。
• 回源配置：确保回源请求能正确获取带 CORS 头的响应。

4. 调试与验证流程图

graph TD A[PDF加载失败] --> B{是否跨域?} B -- 是 --> C[检查响应头是否有Access-Control-Allow-Origin] C -- 缺失 --> D[配置Nginx/Apache/CDN添加CORS头] C -- 存在 --> E[检查MIME类型] B -- 否 --> E E -- Content-Type非application/pdf --> F[配置服务器MIME映射] E -- 正确 --> G[检查PDF二进制完整性] F --> H[重启服务并测试] D --> H G --> I[使用curl或Postman验证响应] H --> I I --> J[浏览器重试加载]

5. 进阶建议与最佳实践

对于具备高可用要求的系统，建议采取以下措施提升鲁棒性：

1. 使用预签名 URL（如 S3 Presigned URL）替代公开 CORS，增强安全性。
2. 在前端实现 fallback 机制：当 PDF.js 加载失败时，降级为 iframe 嵌入或提供下载链接。
3. 监控日志中 PDF 请求的 HTTP 状态码分布，及时发现配置漂移。
4. 利用 Service Worker 缓存 PDF 资源，减少重复请求与网络依赖。
5. 对敏感文档启用 JWT 鉴权 + 动态代理，避免直接暴露存储地址。
6. 定期审计 CDN 与源站配置一致性，防止更新后遗漏头信息。
7. 使用 fetch 前先做 OPTIONS 预检探测，提前判断 CORS 可用性。
8. 在 CI/CD 流程中集成静态资源头检测脚本，实现自动化验证。
9. 对大型 PDF 文件启用流式加载（PDF.js 支持 Range Requests），优化用户体验。
10. 结合 Sentry 或类似工具捕获前端 PDF 渲染异常，形成闭环监控。