若依集成vue-office无法预览PDF文件

Question

在若依（RuoYi）框架中集成 vue-office 预览 PDF 文件时，常见问题为页面空白或提示“PDF.js 加载失败”。该问题多因未正确引入 PDF.js 依赖或静态资源路径配置错误导致。vue-office 依赖 PDF.js 解析渲染 PDF，若未通过 CDN 或本地 node_modules 正确加载 PDF.js，浏览器将无法解析文件内容。此外，若部署在非根路径下（如 /ruoyi/），而未配置 publicPath 或 base 路径，也会造成资源加载 404。需检查 webpack 或 Vite 构建配置，确保 PDF.js 资源可正常访问，并确认 Vue 组件中 file 属性传入的 PDF 路径有效且支持跨域。

Answer 1

1. 问题现象与初步排查

在若依（RuoYi）框架中集成 vue-office 实现 PDF 文件预览时，开发者常遇到页面空白或浏览器控制台提示“PDF.js 加载失败”的问题。该现象通常出现在构建部署后，开发环境可能表现正常。

• 检查浏览器开发者工具的 Network 面板，确认是否存在 PDF.js 相关资源加载 404 错误。
• 查看 Console 日志是否报错：Cannot find module 'pdfjs-dist' 或 Failed to load PDF worker。
• 验证前端组件中传入的 :file 属性是否为有效 URL 或 Blob 路径。

2. 根本原因分析

深入分析表明，该问题主要由以下两类核心因素导致：

分类	具体原因	影响范围
依赖缺失	未正确安装或引入 pdfjs-dist	本地开发即失败
路径配置错误	publicPath、base 或 CDN 地址不匹配部署路径	生产环境 404
跨域限制	PDF 文件服务未开启 CORS	文件无法读取
构建工具配置不当	Webpack/Vite 未处理静态资源输出	worker.js 加载失败

3. 解决方案层级递进

1. 安装必要依赖：确保项目已安装 vue-office 和 pdfjs-dist。

   npm install vue-office@^3.0.0 pdfjs-dist@^3.4.120

2. 全局注册插件：在 main.js 中引入并使用：

   import VueOfficePdf from '@vue-office/pdf'
   Vue.use(VueOfficePdf)

3. 配置 Webpack publicPath：若部署路径为 /ruoyi/，需设置：

   // vue.config.js
   module.exports = {
     publicPath: '/ruoyi/',
     configureWebpack: {
       output: {
         publicPath: '/ruoyi/'
       }
     }
   }

4. Vite 构建适配：对于 Vite 版本 RuoYi：

   export default defineConfig({
     base: '/ruoyi/',
     build: {
       outDir: 'dist',
       assetsDir: 'static'
     }
   })

5. 指定 PDF.js Worker 路径：

   import * as PDFJSLib from 'pdfjs-dist'
   PDFJSLib.GlobalWorkerOptions.workerSrc = '/ruoyi/static/pdf.worker.min.js'

4. 部署路径与资源映射关系

当应用部署在子路径下时，必须保证所有静态资源路径前缀一致。可通过以下流程图说明请求流转过程：

graph TD
    A[用户访问 /ruoyi/index.html] --> B[Nginx 服务路由]
    B --> C{资源请求?}
    C -- 是 --> D[/ruoyi/static/*.js]
    C -- 否 --> E[API 请求代理]
    D --> F[返回对应 JS/CSS 资源]
    F --> G[vue-office 动态加载 pdf.worker.min.js]
    G --> H{路径是否包含 /ruoyi/?}
    H -- 否 --> I[404 错误]
    H -- 是 --> J[成功加载 Worker]
    

5. 跨域与安全性考量

若 PDF 文件来自不同域名的服务端，需确保后端响应头包含：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

同时，在前端调用前可封装校验逻辑：

async function validatePdfUrl(url) {
  try {
    const res = await fetch(url, { method: 'HEAD' });
    if (!res.ok) throw new Error('File not accessible');
    const contentType = res.headers.get('content-type');
    if (!contentType.includes('application/pdf')) {
      throw new Error('Invalid MIME type');
    }
    return true;
  } catch (err) {
    console.error('PDF validation failed:', err);
    return false;
  }
}