【开源推广】我做了一个纯前端 File Viewer 组件，想请大家帮忙测测真实文件的兼容性

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

• 我的帖子已经打上 开源推广 标签： 是


• 我的开源项目完整开源，无未开源部分： 是


• 我的开源项目已链接认可 LINUX DO 社区： 是


• 我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是


• 以上选择我承诺是永久有效的，接受社区和佬友监督： 是

以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出

佬友们大家好，作为一个从2022年就开始做纯前端文档预览的猿，最近在重新整理一个文件预览相关的开源项目，想拿来分享一下，也希望有类似业务场景的朋友帮忙看看真实文件里的兼容性问题。

这个项目叫 Flyfish File Viewer，主要想解决的是企业后台、内网系统、资料库、工单系统里经常遇到的附件预览问题。

项目地址：

先放个 GitHub README 截图。我也在徽章里引用了咱们社区，写好了支持的生态和协议，方便大家先判断项目是不是适合自己的业务。

为什么会做这个

文件预览是一个非常普遍的需求，但是实际在业务系统中，经常会变成一个“文件格式动物园”。

很多后台系统里，附件不只是 PDF 和图片。合同可能是 Word，报表可能是 Excel，汇报材料可能是 PPT，工程资料里可能有 CAD，客户邮件里还可能带着压缩包、邮件文件、日志、配置文件等等。

然鹅，很多领导不想自己装软件，但就是想看。。。没办法，咱们作为牛马必须安排！

在这之前，服务端转码其实是最常见的路线，也有很多成熟方案，比如kkfileview。但在一些内网、私有化、离线部署场景里，服务端转码会带来不少额外的负担，比如：

• 
  

  转换服务的部署和维护

  
  


• 
  

  字体、编码和格式兼容

  
  


• 
  

  队列、缓存和临时文件管理

  
  


• 
  

  文件权限和隐私边界

  
  


• 
  

  不同客户环境里的部署差异

  
  

所以我想尝试另一条路：能不能尽量把预览能力放回浏览器端完成。

File Viewer 目前就是围绕这个方向做的：纯前端、TypeScript、尽量不依赖服务端转码；比较重的能力通过 Worker / WASM / renderer 按需加载；不同格式拆成独立模块，业务侧可以根据需要选择接入。

它不是想替代专业编辑器，也不是想把浏览器说成万能转换器。更准确地说，它希望在业务系统里提供一个“先能打开、能看个大概、部分格式尽量还原”的附件预览方案。

先放几张图

上面是 Demo 的整体效果。它现在更偏业务系统里的文件预览组件，而不是单独的文档编辑器。

Word 是后台系统里比较常见的一类文件，比如合同、制度、标书、说明文档等。

目前 DOCX 这块走的是 Worker 解析、连续阅读、目录字段缓存和异步分批渲染。老的 .doc / .dot 文件也做了一些兼容预览路径，不过这部分仍然很依赖真实文件样本。

PPTX 这块没有只做简单文本提取，而是做了一套原生渲染链路，按页输出，尽量还原主题、背景、图片裁剪、常见组合图形等。

不过 PPT 的复杂度很高，特别是动画、高级特效、历史版本 Office 生成的文件，这些还是需要用更多真实业务文件去回归。

CAD 不一定每个系统都会用到，但在工程、设备、制造、建筑、项目档案这些场景里比较常见。

当前 CAD 预览基于 @flyfish-dev/cad-viewer，DWG 走 Worker + LibreDWG WASM，DXF 走 JS parser，DWF / DWFx / XPS 也有对应的预览链路。

这部分我也特别希望有工程类业务的朋友帮忙试试，因为不同软件、不同版本导出的图纸差异会比较大。

压缩包预览也是我觉得比较实用的一块。

它会先读取目录结构，点开内部文件时再按需解压，并复用同一套文件预览能力。像客服工单、资料交付包、归档文件这类场景，应该会比较常见。

邮件格式目前支持 eml、msg、mbox，可以查看头信息、HTML / 文本正文、附件下载和附件预览。

如果是工单、客服、审计、邮件归档一类系统，可能会有一点用。

文档比对目前是一个单独入口，支持左右排版、同步滚动、搜索、定位等能力，后续还会继续完善。

合同版本、方案版本、制度版本对比，在业务里还挺常见的，所以这块也会继续做。

目前大概支持哪些格式

目前项目中注册的格式支持 206+ 扩展名，24 条预览链路。

大概覆盖这些类型：

这些格式并不是都已经做到同样的完成度。

有些格式是浏览器原生能力为主，比如图片、音视频；有些是基于成熟库封装，比如 PDF；有些则是自己做 renderer 或者组合 Worker / WASM 来实现，比如 Office、CAD、压缩包等。

所以我们可以将它理解为一个“多格式预览框架”，而不是每个格式都已经做到专业软件级别的像素级还原。

架构上怎么拆的

项目现在没有把所有能力都塞进一个大包里，而是拆成了 core、renderer、preset 和不同前端框架组件。

大概是这样：

这块还在继续打磨，尤其是私有化部署、资源路径、MIME、CSP 这些问题，实际环境差异会比较多。

能力边界也说一下

我觉得文件预览这类项目，最需要诚实面对的就是边界。

所以如果佬友们手里有真实文件，尤其是不涉密、方便脱敏的边界样本，非常欢迎帮忙试一下。

这类项目靠我自己造测试文件其实很有限，很多问题需要在真实业务文档中才会暴露。

快速接入

如果只是想快速试完整能力，可以先用 full 包。

Vue 3：

npm i @file-viewer/vue3-full

import { createApp } from 'vue'

import FileViewer from '@file-viewer/vue3-full'

​

createApp(App).use(FileViewer).mount('#app')

<file-viewer url="/files/report.docx" />

React：

npm i @file-viewer/react-full

import FileViewer from '@file-viewer/react-full'

​

export function Preview() {

  return <FileViewer url="/files/report.pdf" style={{ height: 720 }} />

}

纯 Web / Script 标签：

<script src="https://cdn.jsdelivr.net/npm/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js"></script>

​

<flyfish-file-viewer

  src="/files/report.pdf"

  theme="light"

  toolbar-position="bottom-right"

  style="display:block;height:720px"

></flyfish-file-viewer>

如果是正式业务，我个人更建议按需接入：

npm i @file-viewer/vue3 @file-viewer/preset-office

import officePreset from '@file-viewer/preset-office'

​

const options = {

  preset: officePreset,

  theme: 'light',

  toolbar: { position: 'bottom-right' }

}

这样能力边界会更清楚，包体也更容易控制。

可能适合哪些场景

我目前想到的场景主要有这些：

• 
  

  OA、审批流、合同系统

  
  


• 
  

  知识库、文档中心

  
  


• 
  

  工单、客服、邮件归档

  
  


• 
  

  工程资料库、CAD 图纸库

  
  


• 
  

  低代码平台、表单平台

  
  


• 
  

  企业网盘、档案系统

  
  


• 
  

  内网附件中心、私有化交付项目

  
  

如果系统里附件类型比较单一，比如只看图片，直接用浏览器原生能力就够了，没有必要引入这么一套东西。

但如果附件类型越来越杂，后端转码又不太方便，或者客户环境要求内网离线部署，那这种纯前端、模块化、异步加载组件而且可自托管的方案，可能可以作为一个备选思路。

最后想请大家帮忙看看

项目协议是 Apache-2.0，商用、二开和企业内部集成都比较宽松。

我不太想把这篇写成单纯“求 star”的帖子，更希望能收到一些真实反馈。比如：

• 
  

  老 DOC、XLS 有没有明显样式问题

  
  


• 
  

  复杂 PPT 背景、图片裁剪、组合图形是否正常

  
  


• 
  

  DWG、DWF、DWFx 在实际业务图纸里能不能打开

  
  


• 
  

  内网部署时 Worker、WASM、字体资源路径有没有坑

  
  


• 
  

  手机 WebView 下 PDF、Excel、压缩包预览体验怎么样

  
  


• 
  

  还有哪些业务里常见、但现在没有覆盖好的格式

  
  

如果有佬友刚好在做像我说的这类需要丰富文件类型预览的系统，也欢迎拿 Demo 简单试一下。

佬友们遇到问题欢迎尽情提 issue，我会尽量根据真实样本继续完善，让这个组件更好用，帮助到更多的人。

Demo：

https://demo.file-viewer.app

文档站：

https://doc.file-viewer.app