ruoyi-vue-pro文件列表加预览，我把 kkFileView 换成了这个前端组件

先说事故。

之前给用户做系统的时候，使用了 kkFileView 来做文件预览。其实用户只是想能预览场景的 Office 文件比如ppt/pptx,xls/slsx,doc/docx、图片等。误以为是要支持很多种格式的，所以当时简单考虑了下就上了 kkFileView，但后面陆续调研了其他的方案，最终补上了 vue-office 分流预览。

基本满足使用吧。

问题点：

1. 基本都是将其他格式的转成图片或者pdf后发送给前端预览，其实有点慢的
2. kkFileView 要独立部署服务吃资源的，运行一段时间后内存有点偏高
3. 一些 doc/docx 等文件内容样式等复杂一点竟然报错，用户又需要看，只能去源码使用 aspose.words（选他效果最好最简单🥲）来进行转换

但支持的格式是真多。

这个组件是什么路子

先澄清一个容易混的点：Flyfish File Viewer 跟 kkFileView 名字像，架构完全相反。

kkFileView 是服务端方案——起一个 Java 服务，文件丢给它，后台用 LibreOffice 转成 pdf 或图片，前端 iframe 嵌它的预览页。Flyfish 反过来，转换发生在用户浏览器里。文件二进制流到前端之后，是 wasm 和 worker 在本地解析渲染的，服务端只管把字节吐出来，不参与转换。

这意味着两件事。好的那件：不用多部署任何东西，没有 LibreOffice，没有转换队列，内网离线环境拷过去就能用。坏的那件：转换的 CPU 开销转嫁到用户电脑上，文件特别大的时候老机器会吃力。我们后台用户都是办公电脑，这个代价能接受。

格式方面官方标的是 25 条渲染链路、208 个扩展名。我没逐个验证，日常碰到的是这些：Office 三件套加 csv/rtf，pdf 和 ofd，常见图片，代码和文本文件（这个意外好用，日志、sql、json 直接看），zip/rar/7z 能展开目录，dwg/dxf 图纸，drawio 和 xmind，eml 邮件，mp4/mp3 直接播。epub、geojson、sqlite 这些偏门的也在支持列表里，但我没实际文件可测。

工具栏自带下载、打印、缩放、文档内搜索，可以在配置里开关。CAD 和 3D 走 wasm，某个格式第一次打开会慢一两秒——wasm 是懒加载的，第二次就快了，这个不是 bug。

kkFileView、vue-office、OnlyOffice

不是不用，是看需求满足不满满足，有时候同时使用，但越简单功能越强大的最好。

kkFileView 给一个客户使用大半年了。格式覆盖确实广，但它是另一套要伺候的服务：JVM 内存得给够，LibreOffice 进程偶尔会僵死，转换大文件时后面的请求排队。最难受的是预览页是它自己的 UI，跟芋道的 Element Plus 风格完全两套东西，用户能明显感觉"跳出去了"。后来基本office使用vue-office来预览也还行。

@vue-office 那几个包（docx、excel、pdf 分开装）其实挺轻，纯前端，如果系统里只有 Office 文档，它是最省事的选择。问题是芋道的文件模块是个通用入口，用户传什么控制不了。今天补个 zip，明天补个 eml，每种格式引一个组件、写一套分支，维护的是 N 份预览逻辑。我懒得干这个活。

OnlyOffice 协同编辑强基本也能满足客户，但是集成部署都是活！

Flyfish 的定位很窄：一个组件，管"看"，不管"编"，格式尽量全。恰好跟文件列表的场景对上。

接进 ruoyi-vue-pro 的几个坑

跨域，最大的一个

芋道的文件 URL 长这样：

{domain}/admin-api/infra/file/{configId}/get/{path}

后端是 FileController 的 @GetMapping("/{configId}/get/**")，SecurityConfiguration 里这条路径 permitAll，所以链接直接能访问。

但注意，FileViewer 不吃 URL，它吃 File 对象。得自己把内容下载下来再构造：

function buildDownloadUrl(file) {
  if (file.configId && file.path) {
    const path = file.path.split('/').map(encodeURIComponent).join('/');
    return `/infra/file/${file.configId}/get/${path}`;
  }
  return file.url ?? '';
}

const blob = await requestClient.download(buildDownloadUrl(file));
previewFile.value = new File([blob], file.name || file.path, {
  type: file.type || blob.type,
});

为什么非要走芋道自己的代理接口，而不是直接用 file.url？因为存储配成 OSS 或 MinIO 时，file.url 是对象存储的域名，浏览器 fetch 过去就是跨域。走 /infra/file/.../get/... 是同源，没这个问题。

还有一个细节：path 要分段 encode，不能整段 encode，也不能不 encode。芋道自己的单测里就有中文文件名的 case（avatar/中文 100% 文件.txt 这种），漏了会 404。我第一版就是整段 encodeURIComponent，把 / 也编了，路径全乱。

Vite 插件，漏了会白屏

import { fileViewerRenderers } from '@file-viewer/vite-plugin';

fileViewerRenderers({ preset: 'all', copyAssets: true })

这个插件干的事是把 pdf.worker、CAD 的 wasm、drawio 的脚本这些静态资源拷到 public/ 下面。不加它，组件能引进来，简单的 txt、jpg 也能看，但 pdf 中文乱码、dwg 白屏、控制台一片 404——因为资源根本没被拷过去。

验证方法：构建完看 public/flyfish-viewer-assets.json 有没有生成，里面每条资产的 copied 是不是 true。我有一次 CI 上构建用了缓存目录，资源没拷全，靠这个文件查出来的。

样式隔离必须开

芋道的全局 CSS 很重，el- 系列样式会渗进预览区，表格线、字号全乱。配置里 styleIsolation: 'shadow' 打开，FileViewer 用 Shadow DOM 把自己包起来，外面的世界影响不到它。这个选项我试过关掉，五分钟后加回来了。

弹窗关掉要销毁

文件列表的预览一般放 Dialog 里。组件销毁时 FileViewer 实例也要跟着销毁（vben 的 Modal 设 destroyOnClose: true，原生 el-dialog 用 destroy-on-close）。不关干净的话，看完一个大 pdf 再开几个别的，Chrome 内存能上到七八百 MB，用户机器风扇起飞。

permitAll 那条路径，自己掂量

/infra/file/*/get/** 免鉴权是芋道的默认行为，图的是图片外链方便。但这也意味着知道 URL 就能下载，文件涉密的话光靠路径里那串随机名不够。要么加签名，要么换短期 token。这是芋道文件模块本身的问题，跟预览组件无关，但既然预览也走这个口，顺手评估一下。

preset 体积

preset-all 全量引入，构建产物明显变胖，CI 第一次跑会多几分钟（拷字体和 wasm）。业务确定只看 Office 的话，换 @file-viewer/preset-office 能小很多。文件模块是公共入口的话我建议还是 all，省得后面业务方提一种格式你补一次。

依赖和配置，贴一份

pnpm add @file-viewer/vue3 @file-viewer/preset-all
pnpm add -D @file-viewer/vite-plugin

import allRenderers from '@file-viewer/preset-all';
import { FileViewer } from '@file-viewer/vue3';
import '@file-viewer/vue3/dist/file-viewer3.css';

const viewerOptions = {
  preset: allRenderers,
  rendererMode: 'replace',
  theme: 'light',
  styleIsolation: 'shadow',
  cad: {
    wasmPath: '/wasm/cad',
    workerUrl: '/wasm/cad/dwg-worker.js',
    dwfWasmUrl: '/wasm/cad/dwfv-render.wasm',
  },
  drawing: {
    viewerScriptUrl: '/vendor/drawio/viewer-static.min.js',
  },
  toolbar: { position: 'bottom-right', download: true, print: true },
};