企业官网建设流程全解析

纯前端文件预览：File Viewer 直开 221 种文件

【免费下载链接】file-viewerBrowser-native Office / PDF / CAD / archive viewer for internal web apps, with Vue, React, Svelte, jQuery, Web Components, and no server-side conversion.项目地址: https://gitcode.com/gh_mirrors/file/file-viewer

附件预览最真实的痛点不是"打不开"，而是文件得先离开内网：传统方案里，预览一个 DWG 或合同 DOCX，要么部署转码后端，要么把文件上传到 SaaS 转换接口。File Viewer 是一个纯前端文件预览组件，用 Worker 和 WASM 在浏览器里完成解析与渲染，不走服务端转码。它注册了 221 个扩展名，对应 32 条预览管线，全部在客户端执行。

⚙️ 它到底是怎么做到的（一句话架构）

File Viewer 一共四层，从框架组件到本地资源自上而下排布，30 秒能建立完整心智模型。

• 最上层是各框架组件（Vue、React、Svelte、jQuery、Web Component），只负责挂载、卸载和事件转发。
• 第二层@file-viewer/core框架无关，负责渲染器注册表、生命周期、工具栏、搜索、打印这些统一契约。
• 第三层是渲染器：PDF、Word、Excel、CAD、压缩包等每个格式族一个独立包，preset 则是渲染器的"产品级组合"。
• 最底层是本地资源：Worker、WASM、字体、vendor 文件都可以自托管，内网环境零外网依赖。

框架组件 (Vue / React / Svelte / jQuery / Web Component) │ @file-viewer/core（注册表 · 生命周期 · 工具栏 · 搜索 · 打印） │ preset / 单个 renderer（PDF、Word、Excel、CAD、压缩包、邮件…） │ 本地 Worker · WASM · 字体 · vendor 资源（可自托管）

说白了：组件只跟协议打交道，格式能力像插件一样插拔，重解析资源全部留在本地。

🚀 最小可运行示例

下面这段代码做三件事：装依赖、引入 Vue 3 组件、渲染第一个文件。

npm install @file-viewer/vue3-full

<script setup lang="ts"> import { FileViewer } from '@file-viewer/vue3-full' </script> <template> <FileViewer url="/files/contract.docx" :options="{ theme: 'light', watermark: { text: '内部资料' } }" /> </template>

Full 包已内置preset-all与同版本 Worker/WASM 资源，不需要再装任何 preset。Vite 项目可另外注册@file-viewer/vite-plugin自动发现已装 preset 并拷贝资源。React、Svelte、jQuery、原生 Web Component 都有对应包，options 契约完全一致。

三个典型工作流

按使用频率挑了三个动作：翻页看文档、看图纸、翻压缩包。

在页面里直接翻页看合同：PDF 与 Office 文档前端渲染

• 开启pdf.navigation，左侧显示页码缩略图与大纲树，点击即可跳页
• 文档内搜索高亮命中项，支持上一条 / 下一条导航
• pdf.bbox可在首屏定位并高亮"合同金额"这类区域，缩放旋转后高亮不丢
• pdf.streaming支持按 Range 渐进加载，不必等整个文件下载完
• 挂载前用precheckFileViewerSource()校验 PDF/Office 文件签名，坏文件提前拒绝

Office 文档前端渲染实际预览效果

让工程师不装 CAD 就能在浏览器里预览 DWG：LibreDWG WASM 解析

• DWG / DXF / DWF / DWFx 通过 WASM 在浏览器端解析，不需要桌面 CAD
• cad.renderer默认自动选择 webgl / canvas2d，低配终端可强制 canvas2d
• cad.workerTimeoutMs给大图纸的解析设超时上限
• cad.wasmPath等资产可自托管，内网部署零外网请求
• STEP / glTF / STL 等 3D 模型走独立的 3D 渲染器，STEP 用本地 OCCT 建网格

DWG 图纸在浏览器内直接解析

把压缩包里的文件列出来但不想真的解压：archive 渲染器

• ZIP / RAR / 7Z / TAR / ISO 等 20+ 压缩格式直接展示目录结构，不要求完整解到磁盘
• 点进嵌套文件走同一套渲染器注册表，zip 里的 .docx 照样按文档渲染
• archive.cache启用 IndexedDB 缓存，反复切换不重复解析
• archive.entryActions.download可按路径规则禁用嵌套文件的下载按钮
• maxArchiveSize/maxEntryPreviewSize限制内存占用，防止压缩炸弹

官方演示主工作区

"免服务端转码预览"和老办法差在哪

一句话：把转码服务搬进浏览器，后端只剩静态资源托管。

221 个扩展名的完整格式矩阵

代价也要讲清楚：重型格式（CAD、3D、超大 PDF）在浏览器里占内存，文件越大越容易吃紧；Full 包首屏体积大于单渲染器组合，建议按 renderer 拆包（chunkStrategy:'renderer'方便排查体积）；它是只读预览工具，不是 Office / CAD 编辑器，视觉保真度随文件结构和嵌入字体而异。

按需装配：纯前端文件预览的包体积控制

设计意图是"组件做薄壳，能力按包装"：preset 是产品级组合（lite / office / engineering / all），单个 renderer 是格式级组合，粒度自己选。

# 最小集：组件 + 办公预设（PDF / Word / Excel / PPT / OFD） npm install @file-viewer/vue3 @file-viewer/preset-office # 全集：一个包搞定 npm install @file-viewer/vue3-full

Vite 项目注册@file-viewer/vite-plugin后，preset 会被自动发现、Worker/WASM 资源自动拷贝，业务代码零手工 import。具体体积数字官方未公布，以你打包器的 build report 为准。

🛡️ 安全与合规边界

• 数据不出浏览器：文件字节由你自己的前端拉取，解析全在客户端完成；严格 CSP 场景下把所有资产放在同一受信源即可。
• 隔离机制：标准组件默认走 Shadow DOM，宿主页面样式进不去也出不来；重解析在 Worker 里跑，主线程保持响应。
• 水印与审计：文本 / 图片水印（打印输出同样保留）；beforeOperation可给下载、打印等操作挂权限校验，toolbar.permissions是硬闸门，直接调 API 也会被拦。

🐛 踩坑与排障清单

• 查看器空白：宿主容器高度不稳定，或文件扩展名无法识别 → 给容器固定高度，必要时显式传type。
• Full 包报 "libarchive Worker 未加载"：资产 404 后 SPA 返回了 HTML 兜底（状态码 200 但内容不是 JS）→ 检查/file-viewer/vendor/libarchive/worker-bundle.js是否返回真实 JS；前缀非默认时用setDefaultFullAssetBaseUrl()指一次。
• WASM 实例化失败：服务器 MIME 类型不对 → 给.wasm/.js/ 字体 / JSON 清单配置正确 MIME。
• 升级后 DOCX 版式不变：旧 Worker 或旧资源被缓存 → 重新部署同版本资产，清 CDN 与服务 Worker 缓存，确认请求的是新版docx.worker.js。
• 扩展名在矩阵内但页面显示"安装提示"：对应渲染器没装配 → 装对应 preset 或单个 renderer 包。
• npm 11 报Cannot read properties of null (reading 'matches')：同一目录混用了 pnpm / bun 等包管理器 → 统一一个包管理器，重置node_modules重装。

🔌 接入你现有的系统

三条路径，NPM 是主路径，iframe 只用于特定场景。

• NPM 包（推荐）：按技术栈选对应包，五个框架共享同一份 options 契约，只有组件写法不同。
• CDN / IIFE：@file-viewer/web-full提供入口 script，或直接整目录部署它的dist/——只拷入口 IIFE 不算完整部署。
• iframe 嵌入：官方明确不推荐标准集成走 iframe，仅用于嵌入官方演示或静态站场景，文件经postMessage(Blob)交接：

<iframe src="/file-viewer/iframe.html?url=/files/demo.docx" style="width:100%;height:720px;border:0" allow="fullscreen" ></iframe>

私有化 / 离线部署：官方提供 Docker 镜像（docker pull flyfishdev/file-viewer），可镜像进内网 registry，详见 Docker 部署文档 与 离线分发说明。

生态与后续演进

• 重型格式（CAD、3D、大文档）的 WASM 性能持续优化，目标是压低低配终端的解析耗时。
• 格式矩阵维持"全部稳定"状态（当前 221 扩展名、0 实验性），新格式以渲染器包形式增量加入。
• 移动端触控交互与无障碍支持（虚拟行号、屏幕阅读器）继续完善。
• 社区报兼容性问题时，提供脱敏样本文件 + 浏览器版本最有价值，截图不能替代样本。
• 可贡献新渲染器 / preset 组合，或修特定格式的边界案例。

git clone https://gitcode.com/gh_mirrors/file/file-viewer后执行pnpm install && pnpm dev，本地跑起官方 demo，先打开 example 目录里的样本 docx 试试。

【免费下载链接】file-viewerBrowser-native Office / PDF / CAD / archive viewer for internal web apps, with Vue, React, Svelte, jQuery, Web Components, and no server-side conversion.项目地址: https://gitcode.com/gh_mirrors/file/file-viewer