File Viewer v2.2.2 实战：208 种文件预览与 Worker/WASM 自托管-育师

企业后台的附件预览通常会经历三个阶段：

先支持 PDF；
再拼接 Word、Excel、PPT 和图片；
最后被旧 Office、CAD、压缩包、大文件和内网部署击穿。

File Viewer v2.2.2 的目标，是让这些格式共享同一套组件 API，并把重型 Worker、WASM、字体和 vendor 资源完整交付到自己的网络中。

本文以 Vue 3 + Vite 为例完成接入，再说明非 Vite、子路径和私有化环境应该怎样部署。

1. 先看新版工作台

新版 Demo 重新整理了文件来源、操作工具和预览画布。样例库、最近打开、明暗主题、移动端“更多”入口和?url=沉浸模式都在同一套布局中。

支持矩阵当前包含：

208 个不重复扩展名；
25 条 renderer 预览链路；
54 个 npm 发布目标；
8 个官方 Full 入口：Web、Vue 3、Vue 2.7、Vue 2.6、React、React legacy、Svelte、jQuery。

2. Vue 3 + Vite 完整接入

2.1 安装同版本组件和插件

pnpmadd@file-viewer/vue3-full@2.2.2pnpmadd-D@file-viewer/vite-plugin@2.2.2

Full 包包含完整 renderer 矩阵；Vite 插件负责把对应版本的 Worker、WASM、字体和 vendor 文件发布到构建产物中。

2.2 配置 Vite

import{fileViewerRenderers}from'@file-viewer/vite-plugin'importvuefrom'@vitejs/plugin-vue'import{defineConfig}from'vite'exportdefaultdefineConfig({plugins:[vue(),fileViewerRenderers({copyAssets:true})]})

2.3 在页面中使用

<script setup lang="ts"> import FileViewer from '@file-viewer/vue3-full' </script> <template> <FileViewer url="/files/contract.docx" style="height: 720px" /> </template>

2.4 鉴权接口返回二进制

接口没有公开 URL 时，可以先获取 Blob，再补一个可信文件名：

constresponse=awaitfetch('/api/files/42/download',{headers:{Authorization:`Bearer${token}`}})constblob=awaitresponse.blob()constfile=newFile([blob],'quarter-report.xlsx',{type:blob.type})

文件名用于选择正确 renderer。不要把没有扩展名的下载接口地址直接当作类型依据。

3. 非 Vite 项目怎样交付运行时资源

Webpack、Rspack、Rollup、Vue CLI 和 Umi 项目需要执行 Full 包自带的同版本 CLI：

npx --no-install file-viewer-copy-assets ./public/file-viewer

默认资源地址是<部署基址>/file-viewer/。如果业务使用其他静态目录，可以统一覆盖：

import{setDefaultFullAssetBaseUrl}from'@file-viewer/vue3-full'setDefaultFullAssetBaseUrl('/static/file-viewer/')

需要一起部署的并不只有 JavaScript 入口，还包括：

PDF、DOCX、Spreadsheet Worker；
PPT/PPTX Worker、WASM 和 CJK 字体；
CAD/OCCT Worker 与 WASM；
Typst 编译器和字体；
Archive、Draw.io、SQLite 等 vendor 资源。

只复制入口 IIFE 或只安装 renderer 代码，不属于完整格式支持。

4. 新支持矩阵怎样理解

办公与版式

DOC/DOCX、XLS/XLSX、PPT/PPTX、PDF、OFD、RTF、ODT、Typst 等格式分别进入对应 renderer。旧.ppt使用独立二进制链路，不复用 PPTX 的 OOXML 解析。

工程、模型与绘图

DWG、DXF、DWF/DWFx、STEP/STP、IGES/IGS、BREP、GDS、XMind、draw.io、Mermaid 等能力按需加载 Worker/WASM/WebGL/SVG。

STEP/IGES/BREP 会通过本地 OCCT Worker/WASM 完成真实三角化，再生成 Three.js 网格，不需要先调用公共转换服务。

压缩包与邮件

ZIP、7Z、RAR、TAR、ISO、APK、CBZ/CBR 等先展示目录；用户点击内部文件后再按需解压，并继续复用统一预览器。EML、MSG、MBOX 支持头信息、正文和附件查看。

文本、媒体与数据资产

代码、日志和大文本使用有界虚拟化；CSV/TSV 自动识别 UTF-8、GBK、GB18030。图片、音视频、PSD、SQLite、Parquet、Avro、字体和 WASM 使用对应按需解析链路。

5. v2.2.x 处理的生产问题

上传 PDF 下载为 0 字节

PDF.js 会把ArrayBuffer转移给 Worker。新版下载逻辑会回退到仍完整的原始File，避免渲染成功后下载空文件。

复杂 DOCX 锚点偏移

@file-viewer/docx升级到 0.3.21，修复 WPS/WPG、图片锚点、嵌套组变换和页面/段落锚点混排造成的巨大空白。

Shadow DOM 与子路径

PPTX 样式会进入实际 ShadowRoot；Worker 不再固定请求根路径。PDF 在全宽、flex grow 和外层滚动容器中的居中缩放也完成修复。

EPUB 依赖安全

EPUB 引擎改为包内懒加载，固定安全 XML DOM 版本，并在发布时执行npm pack、全新安装、npm audit、manifest、哈希和许可证检查。

6. 上线前检查清单

组件、Vite 插件和运行时资产版本一致；
生产环境可以访问/file-viewer/或自定义资产基址；
.mjs返回application/javascript；
Nginx 没有用 HTML fallback 响应 Worker/WASM 文件；
鉴权二进制被包装为带可信文件名的File；
使用真实 DOCX、PPT、DWG、压缩包和大文件回归；
未完整支持的 IFC、3DM 等格式向用户显示真实边界；
Excel 虚拟表格不强行显示不完整的打印操作。

结语

File Viewer 自研源码与组件包采用 Apache-2.0；完整发行物中的独立运行时和第三方依赖保留各自 LICENSE/NOTICE。v2.2.2 的重点不是简单累计扩展名，而是让每个格式拥有明确 renderer、能力边界和可交付资源。

GitHub：https://github.com/flyfish-dev/file-viewer
Demo：https://demo.file-viewer.app
文档：https://doc.file-viewer.app

File Viewer v2.2.2 实战：208 种文件预览与 Worker/WASM 自托管