1.3k Star，谢谢大家：File Viewer 这一路把 206 种文件预览慢慢做实了

1.3k Star，谢谢大家：File Viewer 这一路把 206 种文件预览慢慢做实了

这两天重新看 GitHub 数据，File Viewer 公开仓已经来到约 1.3k star，第一反应有点像把锅里的面捞起来，发现里面突然多了一只荷包蛋：来得突然，也是真的开心。

这篇先认真说声谢谢。

感谢阮一峰老师在科技爱好者周刊里提到，也感谢这段时间每一位提 issue、发截图、给样例、帮忙验证内网部署和移动端兼容的朋友。File Viewer 能走到今天，靠的是很多真实业务里的附件问题，一点点被大家拎到了台前。

图：GitHub 数据截至 2026/7/9 17:49（北京时间）；npm、Docker 和 release matrix 仍采用 2026/7/6 阶段整理口径。npm 下载数为 52 个包聚合统计，包含标准包和历史兼容包，不等同于独立用户数。

1.3k star 背后，真正让我开心的是这些反馈

File Viewer 最初要解决的问题很朴素：企业系统里的附件越来越复杂，用户希望直接在浏览器里看，不想为了一个 Word、一个 CAD 图纸、一个压缩包或者一封邮件，再额外跳到本地软件、服务端转码、云端转换。

真实反馈里，大家遇到的问题往往非常具体：

• Word 文档目录样式错乱，复杂表格打开很慢。

• PDF 目录跳转后内容被侧边栏挡住，缩放和搜索浮层位置不舒服。

• Excel sheet 太多时标签被压扁，图片浮层挡住滚动条。

• PPTX 背景没出来，worker 路径在不同构建工具里不一致。

• DWG / DXF / DWF 图纸缩在角落，文字编码和 wasm 路径会出问题。

• OFD 发票资源路径大小写、BaseLoc、图片资源和 BOM 都可能踩坑。

• ZIP 里的中文文件名乱码，压缩包内文件还要继续预览。

• 手机 WebView、Electron file://、内网静态部署、Cloudflare / Nginx / 对象存储，各种环境都要能跑。

这些问题不太适合写成一句“支持很多格式”就结束。它们很细，也很真实。很多时候，用户发来的只有一张截图、一段控制台报错，甚至一句“这个文件打不开”。但就是这些反馈，把项目一点点推向更可用的状态。

图：GitHub 公开仓当前已来到约 1.3k star，issue 里也沉淀了大量真实文件兼容性反馈。

当前 File Viewer 做到了什么

到当前版本 2.1.23，File Viewer 的基础能力已经比较完整：

• 206 个扩展名映射。

• 24 条 renderer 链路。

• 52 个 npm 发布目标。

• 16 个组件目标。

• 27 条 smoke 渲染链。

• 432 个组件渲染目标。

• Apache-2.0 协议，授权范围以许可证文本为准，接入前建议结合企业内部合规要求确认。

从格式覆盖看，项目现在主要面向这些场景：

• Office：Word、Excel、PPTX、RTF、ODT、ODS 等。

• PDF / OFD / Typst：页面渲染、缩放、搜索、目录、打印和导出持续完善。

• CAD / 工程图纸：DWG、DXF、DWF、DWFX、XPS 等走工程图纸链路。

• 压缩包：ZIP、RAR、7Z、TAR、GZ、ISO、APK、CBZ 等，支持目录读取和内部文件继续预览。

• 邮件：EML、MSG、MBOX，支持正文、头信息、附件和附件继续预览。

• 绘图与脑图：Draw.io、Excalidraw、Mermaid、PlantUML、XMind。

• 设计与数据：PSD、SQLite、Parquet、Avro、GeoJSON、KML、GDSII、OASIS 等。

• 常规文件：Markdown、代码、patch、git bundle、图片、HEIC、音视频、字体、3D 模型等。

它的核心价值在于分层：不同格式拆成独立 renderer，再通过 preset 和 full 包给不同团队选择。想轻量就按需装，想快速验收就用 full，想工程化就用 Vite 插件和离线资产复制。

图：官网已经围绕纯前端、模块化 renderer、离线部署、生态组件和多格式矩阵重新梳理。

这段时间主要在补什么

最近这几轮更新，看上去 commit 很多，但方向很集中：让项目更适合真实业务接入。

第一，是架构继续模块化。

core 保持纯 TypeScript，负责格式识别、资源加载、renderer 协议、生命周期、搜索、缩放、打印、导出和 controller API。PDF、Word、Spreadsheet、PPTX、CAD、Typst、Archive、Email、Mindmap、Data、EDA 等能力进入独立 renderer。Vue、React、Svelte、jQuery、Web Component 这些生态组件保持各自原生体验，不互相套娃。

第二，是加载性能继续收紧。

PDF、Office、CAD、Typst、压缩包、PSD、Mermaid、XMind、3D、Geo 这些重型能力，只有命中文件类型时才异步加载。IIFE / full 包也在减少首包压力，Worker、WASM、字体和 vendor 资源尽量随包自托管。

第三，是离线部署继续完善。

企业内网场景里，“跑得起来”经常比“看起来优雅”更重要。最近持续修了 PDF worker、DOCX worker、libarchive wasm、CAD wasm、Typst 字体、Draw.io fallback、full 包默认 asset base URL、非 Vite 静态资源路径和移动端 WebView 兼容。

第四，是真实格式继续打磨。

OFD 电子发票资源路径、GBK / GB18030 ZIP 中文文件名、PPTX 背景和 worker、DOCX 目录与复杂样式、Excel 图片浮层、CAD fit 和图层、PDF 目录/页缩略图切换、压缩包内嵌预览、暗色模式与 Shadow DOM 样式隔离，都在这一阶段继续往前推进。

图：Demo 左上角保留 GitHub star 徽标，主区域展示真实中文 Word 文档预览和统一工具栏。

一些看起来小、但用户会天天碰到的问题

很多修复不适合做成大标题，但它们很影响使用体验。

比如 PDF。

目录侧边栏打开后，跳转页面不能把正文挤到看不见；搜索浮层不能跑到页面左上角；缩放不能只改外层 CSS 造成文字层错位；导航、页缩略图、目录树、打印、导出要尽量统一。

比如 Word 和 Excel。

Word 要兼顾复杂中文正式文档、目录、图片、表格、worker 解析和移动端性能；Excel sheet 多时要提供可滚动标签，而不是把所有 sheet 挤成一排小薄片。打印能力也要根据格式真实显隐，不能让用户点了以后只打印一个截断视口。

比如 CAD。

DWG / DXF / DWF 远比展示一张图片复杂。图层、实体、缩放、适配、文本编码、wasm 路径、worker 打包、Vite / Webpack / 非构建工具部署，都可能影响最终体验。现在项目通过自研 CAD 能力持续把这些问题收敛到浏览器端。

图：DWG 图纸支持图层、结构信息、缩放与适配，适合工程资料库、图纸归档和业务系统里的快速初筛。

比如压缩包。

压缩包预览不能停在列目录。真实业务里，用户会希望点开 ZIP 里的 PDF、DOCX、图片、代码或 JSON 继续预览。移动端还要处理 worker 加载、缓存、内存安全和列表布局。最近的 GBK / GB18030 中文文件名修复，就是来自真实客户文件。

图：压缩包预览会先读取目录，用户点击内部文件后再按需解压，并继续交给同一套预览链路。

为什么坚持纯前端

服务端转码当然有它的价值，尤其在追求极致 Office 还原、统一生成图片或 PDF 的场景里。但很多企业系统还有另一类需求：文件不方便出内网，不希望维护转码服务，也不想因为预览功能额外引入复杂后端链路。

File Viewer 选择先把浏览器端能做的部分尽量做好：

• 文件尽量在浏览器里解析和渲染。

• Worker / WASM / 字体 / vendor 资源可自托管。

• 支持 Docker、静态站、私有 CDN、对象存储、内网 Nginx。

• Vue、React、Web Component、Svelte、jQuery 都有对应组件。

• 统一 options、事件、controller、生命周期、搜索、缩放、打印、导出和水印。

这条路线的好处是接入轻，部署边界清楚，对隐私和内网更友好。代价也很明确：不同格式的浏览器端还原度会受规范开放程度、文件复杂度和第三方解析能力影响。项目会继续把这些边界写进文档，也欢迎大家用真实样本一起推进。

图：文档比对页面支持左右并排、同步滚动、示例/URL/上传入口和搜索定位能力，适合合同审阅、材料对照和版本校对。

文档、Demo 和支持矩阵也在一起补

开源组件最怕“代码能跑，用户找不到入口”。这段时间除了修渲染问题，也在不断补文档和 Demo：

• 官网首页重新梳理核心价值、生态组件、支持矩阵和部署路径。

• 文档站补充快速开始、纯 JS、Web Component、Vue、React、Svelte、jQuery、CDN/IIFE、Vite plugin、full 包和 Docker。

• 支持格式页会列扩展名，也说明每类格式的渲染链路和体验边界。

• Demo 提供分组样例、上传、URL、文档比对、工具栏、fit、搜索、水印、打印、HTML 导出等真实交互。

• README 同步更新中文和英文入口，方便国内外开发者快速判断是否适合自己的业务。

图：支持格式页把 206 个扩展名、24 条预览链路、按需加载和体验边界放在一起说明。

图：文档站持续补充概览、快速开始、生态接入、部署、格式边界和常见问题，尽量让真实接入少走弯路。

也说说数据

这次我重新整理了一下公开数据，口径如下：

• GitHub 公开仓：约 1.3k stars（当前公开接口 1,265），135 forks。

• Issue：当前 open issues 5 个，历史关闭数据以仓库 Issues 页为准。

• npm：52 个发布目标近 30 天合计 299,667 次下载。

• Docker Hub：2,691 pulls。

• 本地 release matrix：206 个扩展名映射，24 条 renderer 链路，27 条 smoke 渲染链，432 个组件渲染目标。

这些数字只是阶段快照。尤其 npm 下载数是 package family 聚合值，包含标准包和历史兼容包，不代表独立用户数。更值得看的，是 issue 关闭率、真实文件反馈数量、Demo 和文档是否能把接入路径讲清楚。

接下来还想继续做什么

1.3k star 是一个很开心的节点，但 File Viewer 还有很多事情要继续做：

• 持续提升 Office、PDF、OFD、CAD、压缩包、邮件这些高频格式的稳定性。

• 继续优化移动端、WebView、Electron、内网静态部署和非 Vite 工程的体验。

• 把搜索、定位、视图状态、文档比对、打印、导出和水印做得更一致。

• 把每一个真实 bug 尽量沉淀成 harness、fixture 或文档说明，减少反复踩坑。

• 继续欢迎大家提供可公开或可脱敏的真实样本，让支持矩阵更接近生产环境。

最后再说一遍谢谢。

谢谢阮一峰老师在周刊里提到这个项目，谢谢每一位长期关注、反馈和支持 File Viewer 的朋友。一个开源项目最有价值的部分，常常来自社区不断推过来的真实场景，也来自大家一起把边界摸清楚的过程。

项目公开仓库是 flyfish-dev/file-viewer。比数字更重要的，是继续用真实 issue、可复现样本和清晰文档把边界说明白。

继续慢慢做实，继续把复杂附件预览这件事讲清楚。