文档比对来了,Docker 一键跑:File Viewer 1.0.20 把 149 个附件入口带进浏览器

今天想聊一件很具体的事情：当一个业务系统开始认真管理附件，文档预览就会从“小功能”变成“交付门面”。

合同有旧版和新版，审批材料有 PDF、OFD、Word、Excel，项目归档里夹着压缩包、邮件、图纸和模型。客户现场还会问一句：能不能放到内网 Docker 里直接跑？研发团队也会问：Typst、Office 模板、历史 .doc 这类文件能否统一纳入预览？

File Viewer 最新主线推进到 1.0.20，这一轮更新把这些问题放在一起处理：文档比对入口上线，Docker 镜像准备好，Typst 与 Office 模板格式进入统一链路，PDF 加载继续提速，文档与 Demo 也同步补齐。 🌈

今天先看结论

方向	这次带来的变化	对业务的价值
新格式入口	新增 Typst 源文件直读预览，Office 模板与宏格式按只读链路纳入兼容入口	技术报告、模板文件、历史附件可以进入同一套预览界面
文档比对	新增 `/compare.html`，左右并排预览，支持示例、URL、本地上传和同步滚动	合同修订、方案对照、版本验收可以直接在浏览器里完成
Docker 部署	提供 nginx 静态镜像、`Dockerfile`、多架构 buildx 发布脚本	内网、私有云、客户现场可以一条命令运行 Demo 与比对页
PDF 链路	同源 PDF 默认交给 PDF.js 渐进读取，Range 服务可分片建页	大文件首屏等待更短，下载按钮也兼容流式场景
质量修补	WPS 专有封装给出转换指引，Docker Hub API 脚本增加诊断，文档和成品包继续同步	接入者更容易判断边界，发布链路更清楚

当前版本内置 149 个扩展名映射，覆盖 20 条预览链路。Vue3、Vue2.7、React 和纯 Web 四条包线继续保持一致的使用体验。

文档比对：把“两个文件来回切”变成左右并排看

很多系统里，用户需要看的往往是一组互相关联的文件。合同条款更新、标书版本回看、技术方案修订、测试报告复核，都需要把两份材料放在一起。

1.0.20 新增独立文档比对入口 /compare.html。它和主预览页分开，避免把比对场景塞进日常预览界面里。左右两个面板各自支持示例文件、URL 和本地上传，也支持同步滚动。

这张图里，左侧是旧版 .doc，右侧是新版 .docx。用户可以直接核对内容风格、段落变化和页面结构。对于 PDF、PPTX、Typst、Markdown 等格式，也可以通过同一个入口做并排检查。

它还支持通过 URL 预置左右文件：

https://viewer.flyfish.dev/compare.html?left=/example/test.doc&right=/example/word.docx

这对业务系统很方便。审批流、合同库、版本管理页只要生成一条链接，就能把对照预览交给独立页面处理。

新格式继续扩展：Typst 与 Office 模板进入统一入口

File Viewer 的路线一直很清晰：浏览器端尽可能多地完成真实附件预览，重型依赖按格式异步加载，主入口保持轻盈。

这一轮新增和整理的重点如下：

类别	扩展名	当前表现
Typst	`typ`、`typst`	直接读取源文件，按需加载 `@myriaddreamin/typst.ts` 浏览器 WASM 编译链路，输出分页 SVG
Word 模板	`dot`、`dotx`、`dotm`、`docm`	复用 Word 渲染链路，只读预览，保留页面阅读感
Excel 模板	`xlt`、`xltx`、`xltm`	复用表格链路，展示可读取的数据、尺寸和样式
PowerPoint 模板	`pptm`、`potx`、`potm`、`ppsx`、`ppsm`	复用演示文稿渲染链路，适合方案模板和课件预览
WPS 专有封装	业务指引	文档站给出转换建议，推荐沉淀为 Office、PDF 或 OFD 等浏览器友好的格式

Typst 是这次很值得单独拿出来讲的格式。它像代码一样管理文档源文件，又能生成漂亮的排版结果，正在越来越多技术团队里出现。

示例里可以看到标题、信息块、表格、公式和代码片段。组件会读取页面尺寸元数据，把输出拆成按页 SVG。打印和导出 HTML 时，也会沿用文档页面自身的布局。

更重要的是，Typst 的 WASM 编译器只在命中 .typ / .typst 时加载。普通 Word、PDF、图片、代码预览不会提前背上这部分体积。

Docker 一键部署：客户现场也能快速跑起来

很多团队接入组件时，先会在本地试 npm 包；走到客户现场、私有云或内网验收时，最省心的方式通常是一个静态镜像。

这一版加入了 Docker 部署链路：构建后的 Demo、文档比对页、示例文件、WASM、Worker 和静态资源全部放进 nginx 镜像，镜像目标为：

flyfishdev/file-viewer:1.0.20

运行方式非常直接：

docker run -d \
  --name flyfish-viewer \
  --restart unless-stopped \
  -p 8080:80 \
  flyfishdev/file-viewer:1.0.20

启动后访问：

地址	用途
`http://localhost:8080/`	主预览 Demo
`http://localhost:8080/compare.html`	文档比对 Demo
`http://localhost:8080/healthz`	健康检查

镜像发布脚本覆盖 linux/amd64 与 linux/arm64，也提供 Docker Hub 仓库创建 API helper。最新提交还补充了 Docker Hub API 诊断信息，方便发布时定位权限、命名空间和仓库状态问题。

这意味着你可以把 File Viewer 当作一个独立的“附件预览站”部署，再通过 iframe 嵌入 OA、CRM、知识库、工单或项目管理系统。需要多系统复用时，这条路尤其省心。

PDF 继续提速：同源文件支持渐进读取

PDF 是预览组件里最常被打开的一类文件，也是最容易暴露性能体验的链路。

过去，为了兼容各种鉴权下载和跨域场景，远端 PDF 往往会先下载为 Blob，再交给 PDF.js 渲染。文件越大，用户越容易在首屏等待里失去耐心。

最新主线新增 PDF 源加载策略：同源 PDF 默认交给 PDF.js 直接按 URL 读取；如果文件服务支持 Range，PDF.js 可以分片获取内容并逐步建页。跨域 URL 继续走兼容下载链路，照顾复杂 CORS 和鉴权环境。

当前 PDF 视图已经具备缩放、页码、旋转、页面侧栏、目录树侧栏、宽度自适应、完整打印和导出 HTML。新增配置项也为业务侧留出控制空间：

配置	作用
`options.pdf.streaming`	控制 PDF 渐进读取策略，默认 `same-origin`
`options.pdf.rangeChunkSize`	控制 Range 分片大小
`options.pdf.withCredentials`	URL 读取时是否携带浏览器凭据

对于合同库、票据中心、归档材料、技术白皮书这类长 PDF，首屏变快一点，用户感知会非常明显。

压缩包、邮件、EDA、图纸和模型仍在同一个体系里

这一轮主角是 Typst、文档比对和 Docker，但 File Viewer 的完整能力已经覆盖更宽的附件世界。

压缩包仍然走 libarchive.js Worker：先读取目录，用户点击内部文件时再按需解压，已解压内容可缓存到 IndexedDB。包里的 PDF、Word、Markdown、代码或图片会继续复用统一预览器。

邮件链路支持 eml 与 msg，可以展示头信息、HTML/文本正文、附件下载和附件继续预览。OLB / DRA 会尽力解析 OrCAD / Allegro 常见 CFB 容器，展示结构树、元件/封装/Padstack 候选、属性和诊断。

图纸和模型方面，DXF 走 @cadview/core，3D 模型走 Three.js，并按格式异步加载 loader。Excalidraw 使用官方包恢复并导出只读 SVG，draw.io 使用 diagrams.net 官方 viewer。

把这些格式放在一起看，File Viewer 的定位就很清楚：它面向真实业务附件，不只服务某一种文档。

那些看起来琐碎、实际很要紧的修补

这两版之间还做了很多“看起来没有标题感，但用户每天都会遇到”的工作。

细节	已做工作
打印完整性	Word / PDF / Typst 等分页内容走专属导出适配器，打印窗口只包含文档页面
`.doc` 兼容	`msdoc-viewer` CFB 补丁改为包管理器无关脚本，npm、pnpm、yarn 都能应用
Excel 边界	虚拟表格场景按能力隐藏打印入口，避免用户得到被截断的输出
WPS 说明	移除容易造成误解的专有格式入口，文档中给出更可靠的转换路径
资源部署	PDF wasm、libarchive wasm、Worker、hash chunk 和静态示例继续同步到成品包
文档更新	README、格式矩阵、Docker 文档、Demo 说明、分发说明一起刷新到 `1.0.20`

这些工作不会在界面上显得夺目，却决定了组件能否在客户现场、内网环境和多技术栈团队里长期维护。

本地验证账本

写这篇文章前，我重新基于最新提交跑了一遍验证：

项目	结果
自动测试	7 个测试文件通过，19 个测试用例通过
生产构建	2764 个模块完成构建，耗时约 1.72s
Typst Viewer	约 40.02KB，gzip 后约 12.92KB
PDF Viewer	约 1915.62KB，gzip 后约 592.76KB，按需异步加载
libarchive WASM	约 1002.54KB，gzip 后约 493.74KB，命中压缩包时加载
Typst renderer WASM	约 972.42KB，gzip 后约 360.11KB，命中 Typst 时加载

能力继续扩展，加载边界也继续保留。用户打开普通图片、Markdown、代码或小文档时，无需提前加载所有重型解析器。

怎么接入最新版

Vue3 项目：

npm install @flyfish-group/file-viewer3@1.0.20

Vue2.7 项目：

npm install @flyfish-group/file-viewer@1.0.20

React 与纯 Web 适配层：

npm install @flyfish-group/file-viewer-react@1.0.20
npm install @flyfish-group/file-viewer-web@1.0.20

Docker 运行完整 Demo：

docker run -d -p 8080:80 flyfishdev/file-viewer:1.0.20

常用入口：

入口	地址
在线 Demo	https://viewer.flyfish.dev^[1]
文档比对	https://viewer.flyfish.dev/compare.html^[2]
官方文档	https://doc.flyfish.dev^[3]
公开成品仓库	https://github.com/flyfish-dev/file-viewer^[4]
源码自助开通	https://dev.flyfish.group/shop^[5]

持续高质量开源

File Viewer 继续按开放协议维护，公开成品仓库提供可直接使用的构建产物、Demo 静态站、文档静态站、示例文件和 npm tarball。

完整源码通过飞鱼小铺象征性打赏开通，一杯奶茶即可自助获得全部源码以及永久仓库更新。流程越自助，大家越能把时间放回真正的业务集成里。

二次开发或商业使用时，请保留来源说明；如果你在真实项目中遇到新的样例文件、复杂打印场景、特殊部署问题，也欢迎一起贡献。文档预览这件事，终究要在真实附件里慢慢打磨，越走越开阔。✨

引用链接

[1]https://viewer.flyfish.dev

[2]https://viewer.flyfish.dev/compare.html

[3]https://doc.flyfish.dev

[4]https://github.com/flyfish-dev/file-viewer

[5]https://dev.flyfish.group/shop