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.2Full 包包含完整 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