File Viewer

面向企业后台、内网和私有化系统的纯前端文件预览组件。

无需服务端转码，在浏览器端预览 Office、PDF/OFD、CAD、压缩包、邮件、图片、音视频、代码等常见业务附件。支持 Vue、React、Svelte、jQuery 和 Web Components。

在线 Demo · 文档 · GitHub Wiki · 快速开始 · 支持格式

项目定位

File Viewer 是面向业务系统的浏览器原生文件预览组件。它的核心场景是企业后台、OA、知识库、工单系统、附件中心、工程资料库和私有化交付项目中的附件预览。

无需后端转码服务，也不要求把私有文件交给云端转换。一个组件、一套 API，覆盖 Office、PDF、OFD、Typst、CAD、XMind、压缩包、邮件、绘图、音视频、代码、PSD、字体和结构化数据。当前内置 206+ 扩展名映射和 24 条预览链路。

新项目优先使用 @file-viewer/*；@flyfish-group/* 历史包继续同步维护。

亮点

接入快。 Vanilla JS、Vue、React、Svelte、jQuery 都有原生组件；full 包可一步拿到完整能力。
覆盖广。 206+ 扩展名，24 条预览链路，覆盖常见办公、工程、设计、数据和代码附件。
纯前端。 浏览器内解析和渲染，支持离线、内网、Docker、私有 CDN 和严格资源自托管。
模块化。 轻量组件、renderer、preset、full 包分层清晰，既能极简安装，也能一键全量。
按需加载。 PDF、Office、CAD、Typst、压缩包、图纸、PSD、Mermaid 等重型能力只在命中格式时加载。
操作完整。 搜索、高亮、缩放、打印、导出 HTML、下载、水印、主题、生命周期钩子和按钮前置校验都走统一 API。
生态一致。 Core 聚焦底层能力，各框架组件只做原生封装，参数、事件和 controller 体验保持一致。

按场景选择入口

用户	他们关心什么	推荐入口
企业后台 / OA 开发	Word、Excel、PPT、PDF 附件预览	快速开始 / Office preset
工程资料系统	DWG、DXF、DWF、图纸初筛	支持格式 / 格式完整度
前端组件使用者	Vue / React / Web Component 接入	生态组件总览
私有化交付团队	离线、内网、Worker / WASM 自托管	发布与分发 / Docker 部署

在线效果

打开 demo.file-viewer.app 可以直接体验 Word 合同、Excel 报表、PPT 材料、DWG 图纸、压缩包和邮件场景入口，也可以继续打开完整样例矩阵、上传自己的脱敏文件、复制当前样例的 React 接入代码，验证工具栏、文档比对和离线资产加载效果。

兼容性反馈

这个项目还在持续打磨，尤其需要真实业务文件来验证兼容性。

如果你手里有不涉密、可脱敏的 DOC / XLS / PPT / DWG / DWF / 压缩包 / 邮件样本，欢迎拿 Demo 试一下。遇到样式不一致、打不开、内网部署路径问题或移动端异常，都可以通过 issue 反馈。

如果这个方向刚好对你有用，也欢迎收藏项目。比起单纯 Star，我更希望收到真实场景下的兼容性反馈。

快速开始

先选接入层，再按需选择格式能力。只想最快拿到完整体验时，直接使用 *-full 包。

场景	推荐安装
Script 标签 / CDN 完整能力	`@file-viewer/web-full`
Vanilla JS npm	`@file-viewer/web` + `@file-viewer/preset-all`
Vue 3	`@file-viewer/vue3-full`，或 `@file-viewer/vue3` + preset
Vue 2.7 / 2.6	`@file-viewer/vue2.7-full` / `@file-viewer/vue2.6-full`
React 18/19	`@file-viewer/react-full`
React 16.8/17	`@file-viewer/react-legacy-full`
Svelte	`@file-viewer/svelte-full`
jQuery	`@file-viewer/jquery-full`
精确裁剪	任意组件包 + `@file-viewer/preset-*` 或独立 renderer

CDN / Script 标签

<script src="https://cdn.jsdelivr.net/npm/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js"></script>

<flyfish-file-viewer
  src="/files/report.pdf"
  theme="light"
  toolbar-position="bottom-right"
  style="display:block;height:720px"
></flyfish-file-viewer>

web-full 的 CDN IIFE 首包只注册 Custom Element、controller 和 lazy full preset；PDF、Word、Excel、CAD、Typst、压缩包等重型 renderer 会在命中文件类型时从 dist/renderers/*.iife.js 异步加载。Worker、WASM、字体和 vendor 资源继续按脚本 URL 自动解析，内网部署时把 dist 目录完整镜像到自己的静态域即可。

Vanilla JS

npm i @file-viewer/web @file-viewer/preset-all

import { mountViewer } from '@file-viewer/web'
import presetAll from '@file-viewer/preset-all'

mountViewer(document.querySelector('#viewer')!, {
  url: '/files/report.docx',
  options: { preset: presetAll, theme: 'light' }
})

Vue 3

npm i @file-viewer/vue3-full

import { createApp } from 'vue'
import FileViewer from '@file-viewer/vue3-full'

createApp(App).use(FileViewer).mount('#app')

<file-viewer url="/files/report.docx" />

Vue 2

npm i @file-viewer/vue2.7-full
# Vue 2.6 项目使用 @file-viewer/vue2.6-full

import Vue from 'vue'
import FileViewer from '@file-viewer/vue2.7-full'

Vue.use(FileViewer)

React

npm i @file-viewer/react-full

import FileViewer from '@file-viewer/react-full'

export function Preview() {
  return <FileViewer url="/files/report.pdf" style={{ height: 720 }} />
}

Svelte

npm i @file-viewer/svelte-full

<script>
  import FileViewer from '@file-viewer/svelte-full'
</script>

<FileViewer url="/files/report.pdf" containerStyle="height:720px" />

jQuery

npm i @file-viewer/jquery-full

import '@file-viewer/jquery-full'

$('#viewer').fileViewer({ url: '/files/report.pdf' })

按需组合

npm i @file-viewer/vue3 @file-viewer/preset-office

import officePreset from '@file-viewer/preset-office'

const options = {
  preset: officePreset,
  theme: 'light',
  toolbar: { position: 'bottom-right' }
}

Vite 项目可额外安装 @file-viewer/vite-plugin，自动发现已安装 preset 并复制 Worker/WASM/字体/vendor 资源；非 Vite 项目直接使用 options.preset，不需要额外插件。

架构

@file-viewer/core: 格式识别、资源加载、renderer 协议、生命周期、搜索、缩放、打印、导出和 controller API。
@file-viewer/renderer-*: PDF、Word、PPTX、CAD、Typst、Archive、Drawing、Data、EDA 等独立渲染能力。
@file-viewer/preset-*: lite、office、engineering、all 四类能力组合。
@file-viewer/web|vue3|vue2.7|vue2.6|react|react-legacy|svelte|jquery: 各生态的原生组件。
@file-viewer/*-full: 组件 + preset-all 的一步到位包，适合快速验证和全格式附件中心。

入口

入口	地址
官方网站	file-viewer.app
官方文档	doc.file-viewer.app
在线 Demo	demo.file-viewer.app
文档比对 Demo	demo.file-viewer.app/compare.html
Release 下载	github.com/flyfish-dev/file-viewer/releases
Docker 镜像	`flyfishdev/file-viewer:latest`
Linux Do 友链	linux.do
打赏与优先支持	dev.flyfish.group/shop

支持格式

当前版本内置 206 个扩展名映射，覆盖 24 条预览链路。

类别	扩展名	当前表现	适合场景
Word	`docx`、`docm`、`dotx`、`dotm`	`@file-viewer/renderer-word` + 自研 `@file-viewer/docx`，Worker 解析、连续流式阅读、目录字段缓存和异步分批渲染；模板/宏格式按只读预览处理	新生成的 Word 文档、正式文档、Word 模板
Word	`doc`、`dot`	`@file-viewer/renderer-word` + `msdoc-viewer`，使用 Word 风格页面容器，增强 CFB 容错和表格布局	历史 `.doc` 老文档、Word 97-2003 模板
兼容文档	`rtf`、`odt`	`@file-viewer/renderer-word` + `rtf.js` / ODF `content.xml` 兼容预览	RTF 富文本、OpenDocument 文本文档
Excel	`xlsx`、`xltx`	`@file-viewer/renderer-spreadsheet` + `styled-exceljs` + 虚拟滚动，支持尺寸、合并、常见样式、自动文本色、workbook drawing 图片和可选表头拖拽调整列宽；默认主线程解析，静态 Worker 需显式开启；打印按钮按能力隐藏，避免只打印当前视口	需要保留表格结构和样式的业务、Excel 模板
Excel 兼容格式	`xlsm`、`xlsb`、`xls`、`xlt`、`xltm`、`csv`、`ods`、`fods`、`numbers`	统一解析，按格式可用信息渐进还原样式；同样遵循虚拟表格打印边界	老表格、轻量数据查看
PowerPoint	`pptx`、`pptm`、`potx`、`potm`、`ppsx`、`ppsm`、`odp`	基于独立开源 `@file-viewer/pptx` 原生引擎浏览幻灯片内容，Worker 渐进解析并按页输出；ODP 走 OpenDocument 幻灯片文本预览	汇报材料、课件、方案、演示模板
PDF	`pdf`	基于 `pdfjs-dist` 预览，同源 URL 默认渐进读取；服务端支持 Range 时自动分片加载，支持缩放工具栏、旋转页、页侧边栏/目录树侧边栏切换、宽度自适应、完整打印和导出 HTML	合同、票据、版式成品
OFD	`ofd`	基于 `DLTech21/ofd.js` 仓库源码在线预览国产版式文档，避开 npm dist 授权 wasm 分支	电子发票、公文、归档材料
Typst	`typ`、`typst`	直接读取 Typst 源文件，按需加载 `@myriaddreamin/typst.ts` 浏览器 WASM 编译器、SVG 渲染器和本地字体资产；支持完整预览、打印和导出 HTML	技术报告、论文草稿、工程文档模板
压缩包	`zip`、`zipx`、`7z`、`rar`、`tar`、`gz`、`gzip`、`tgz`、`bz2`、`bzip2`、`tbz`、`tbz2`、`xz`、`txz`、`lzma`、`zst`、`tzst`、`cab`、`ar`、`cpio`、`iso`、`xar`、`lha`、`lzh`、`jar`、`war`、`ear`、`apk`、`cbz`、`cbr`	`@file-viewer/renderer-archive` 基于 `libarchive.js` WASM Worker 读取目录，点击后按需解压内部文件并复用统一预览器，支持 IndexedDB 缓存、ZIP/TAR/GZIP fallback 和体积上限	归档附件、批量交付包、压缩包内文档快速查看
邮件	`eml`、`msg`、`mbox`	`@file-viewer/renderer-email` 独立承接邮件链路；EML/MBOX 使用 `postal-mime`，MSG 使用 `@kenjiuno/msgreader`，支持头信息、HTML/文本正文、附件下载与附件预览	邮件归档、工单邮件、客户来信附件
EDA	`olb`、`dra`、`gds`、`oas`、`oasis`	`@file-viewer/renderer-eda` 独立承接；使用 `cfb` 解析 OrCAD/Allegro 常见 CFB 容器；标准 GDSII 会读取 structure、boundary、path、text、reference，小图输出 SVG，大元素集自动切到 WebGL canvas；OAS/OASIS 可读文本版图夹具会输出 SVG 预览，真实 SEMI 二进制 OASIS 先做安全结构索引、可读字符串、实体候选和诊断，不虚标专业电气/几何校核	元件库、封装图纸、芯片版图附件初筛
CAD	`dwg`、`dxf`、`dwf`、`dwfx`、`xps`	基于 `@flyfish-dev/cad-viewer` 预览图纸；DWG 通过 Worker + LibreDWG WASM 解析，DXF 使用 JS parser，DWF/DWFx/XPS 使用 native `dwf-viewer` 渲染 W2D/W3D/XPS 图形	工程图纸、二维 CAD 附件、AutoCAD 归档文件
3D 模型	`glb`、`gltf`、`obj`、`stl`、`ply`、`fbx`、`dae`、`3ds`、`3mf`、`amf`、`usd`、`usda`、`usdc`、`usdz`、`kmz`、`pcd`、`wrl`、`vrml`、`xyz`、`vtk`、`vtp`、`step`、`stp`、`iges`、`igs`、`ifc`、`3dm`	`@file-viewer/renderer-3d` 基于 Three.js loaders 交互预览；工程 CAD/BIM 格式会给出不内置几何内核的原因和转换建议	设计模型、点云、三维资产、工程模型
地理数据	`geojson`、`kml`、`gpx`、`shp`	`@file-viewer/renderer-geo` 独立承接；`@tmcw/togeojson` / `shpjs` 转 GeoJSON 后离线 SVG 预览	地理附件、轨迹、边界和轻量 GIS 数据
XMind 脑图	`xmind`	基于 `@ljheee/xmind-parser` 解析 XMind 8 XML 与 XMind 2020+ JSON 包结构，离线渲染多 sheet 脑图、节点、标签、备注、链接、标记、图片和目录树，使用 `@panzoom/panzoom` 提供成熟的拖拽平移、移动端双指缩放、滚轮锚点缩放、键盘平移、统一 toolbar 状态同步、适配画布、搜索、打印、HTML 导出和缩放	脑图、项目规划、知识结构、会议纪要
Excalidraw	`excalidraw`	基于官方 `@excalidraw/excalidraw` 的 `restore` + `exportToSvg` 输出只读预览	白板草图、流程草稿、产品沟通图
draw.io	`drawio`、`dio`	基于官方 diagrams.net `GraphViewer` 预览 mxGraphModel / mxfile	流程图、架构图、业务泳道图
Mermaid	`mermaid`、`mmd`	`@file-viewer/renderer-drawing` 按需加载官方 `mermaid`，输出主题适配 SVG，并通过 `@panzoom/panzoom` 支持拖动、缩放、重置和统一工具栏联动	架构图、流程图、状态图、序列图
PlantUML	`plantuml`、`puml`	使用 `plantuml-encoder` 生成渲染 payload，支持配置自托管 PlantUML SVG 服务；预览层同样支持拖动、缩放和主题容器适配	UML 时序图、组件图、部署图
电子书	`epub`	`@file-viewer/renderer-epub` 基于 `epubjs` 解析目录和章节资源，使用兼容性更好的滚动阅读	电子书、培训手册、长篇阅读材料
电子书	`umd`	按 UMD 移动电子书结构解析元数据、目录和 zlib 压缩正文	旧移动电子书、历史小说附件
Markdown	`md`、`markdown`	`@file-viewer/renderer-text` 提供 Markdown 阅读样式，支持明暗主题阅读面	README、知识文档、说明文档
图片	`gif`、`jpg`、`jpeg`、`bmp`、`tiff`、`tif`、`png`、`svg`、`webp`、`avif`、`ico`、`heic`、`heif`、`jxl`	原生图片浏览；HEIC/HEIF 命中时按需使用 `heic2any` 转换	图片附件、设计稿、Logo、移动端照片
代码/文本	`txt`、`json`、`jsonc`、`json5`、`ipynb`、`yaml`、`yml`、`toml`、`ini`、`proto`、`hcl`、`tex`、`gv`、`http`、`js`、`mjs`、`cjs`、`jsx`、`ts`、`tsx`、`vue`、`react`、`css`、`html`、`htm`、`xml`、`log`、`java`、`py`、`go`、`rs`、`rb`、`swift`、`kt`、`php`、`c`、`cpp`、`cc`、`h`、`hpp`、`cs`、`sh`、`bash`、`sql`、`diff`、`patch`、`bundle`、`bdl`	`@file-viewer/renderer-text` 使用 `highlight.js` 轻量高亮；patch 按需加载 `diff2html` 做左右比对，git bundle 解析 refs、历史记录、文件树和可读 blob 内容	日志、配置、代码片段、接口响应、代码评审
音频	`mp3`、`mpeg`、`wav`、`ogg`、`oga`、`opus`、`m4a`、`aac`、`flac`、`weba`、`midi`、`mid`	`@file-viewer/renderer-media` 使用浏览器原生音频播放；MIDI 命中时按需加载 `@tonejs/midi` 展示轨道结构	录音、播客、语音附件、音效素材、MIDI 文件
视频	`mp4`、`webm`、`m3u8`	`@file-viewer/renderer-media` 使用浏览器原生视频播放；HLS 清单必要时按需加载 `hls.js`	演示视频、录屏、HLS 流
字体/设计/数据	`ttf`、`otf`、`woff`、`woff2`、`psd`、`ai`、`eps`、`sqlite`、`wasm`、`parquet`、`avro`、`webarchive`	`@file-viewer/renderer-data` 独立承接，基于 FontFace、`ag-psd`、`sql.js`、`hyparquet`、`avsc`、WebAssembly Module 和安全摘要；PSD 支持图层选择显隐、重绘和统一缩放；SQLite WASM 支持私有化配置	字体、设计资产、数据库、列式数据和 Web 归档

能力组合

组件包默认保持轻量，格式能力通过 preset 或 renderer 装配。

模式	适合场景	示例
`*-full`	想最快拥有完整格式能力	`@file-viewer/vue3-full`
组件 + preset	大多数业务系统，体积和能力平衡	`@file-viewer/vue3` + `@file-viewer/preset-office`
组件 + 多 preset	组合办公和工程附件	`preset: [officePreset, engineeringPreset]`
组件 + renderer	只要一个或少数格式	`@file-viewer/renderer-pdf`
CDN full	无构建工具、script 标签、快速验证	`@file-viewer/web-full`
Vite 插件	Vite 项目自动发现已安装 preset 并复制资产	`@file-viewer/vite-plugin`

Preset 选择:

preset	覆盖范围
`@file-viewer/preset-lite`	文本、Markdown、代码、图片、音频、视频
`@file-viewer/preset-office`	PDF、Word、Excel、PowerPoint、OFD、RTF、OpenDocument
`@file-viewer/preset-engineering`	CAD、3D、绘图、XMind、Geo、Typst、Archive、Data、EDA
`@file-viewer/preset-all`	官方 Demo 完整格式矩阵

国际化、主题、水印、工具栏、搜索、打印、导出、生命周期和前置权限校验都通过同一套 options 配置。完整 API 见官方文档。

当前 npm 生态

当前版本以 npm registry 的 latest dist-tag 为准，共维护 50 个 npm 发布目标: 45 个标准组件/完整 full 包/核心/renderer/preset/工程插件包 + 5 个历史兼容 alias。新项目建议优先使用 @file-viewer/* 标准包名；旧项目继续使用 @flyfish-group/* 或 file-viewer3 时也会拿到同版本能力。

场景	推荐 npm 包	历史兼容包	版本策略	说明
Core 底座	`@file-viewer/core`	无	`latest`	框架无关的格式矩阵、预览能力、资源加载、生命周期事件、搜索、缩放、打印、导出和操作 API
PPTX 原生引擎	`@file-viewer/pptx`	无	`latest`	从 Flyfish 历史稳定实现拆出的独立 PPTX 渲染引擎，Worker 渐进解析，由 `@file-viewer/renderer-presentation` 按需加载
Word renderer	`@file-viewer/renderer-word`	无	`latest`	标准 renderer 插件，承接 DOCX/DOC/DOT/RTF/ODT 链路，内部按需加载 `@file-viewer/docx`、`msdoc-viewer` 和 `rtf.js`，core-only 安装不再拉取 Word 重依赖
演示文稿 renderer	`@file-viewer/renderer-presentation`	无	`latest`	标准 renderer 插件，基于 `@file-viewer/pptx` 提供 PPTX/PPTM/POTX/POTM/PPSX/PPSM 按需预览、缩放、打印和导出
绘图 renderer	`@file-viewer/renderer-drawing`	无	`latest`	标准 renderer 插件，提供 Draw.io / diagrams.net 离线 viewer、Excalidraw 官方 SVG 导出、Mermaid 官方 SVG 渲染、PlantUML SVG 服务接入、Panzoom 拖拽缩放、打印和 HTML 导出
3D 模型 renderer	`@file-viewer/renderer-3d`	无	`latest`	标准 renderer 插件，基于 Three.js loaders 提供 GLTF/GLB、OBJ、STL、PLY、FBX、DAE、3DS、3MF、USD/USDZ、点云和 VTK 等按需 WebGL 预览
数据资产 renderer	`@file-viewer/renderer-data`	无	`latest`	标准 renderer 插件，基于 `ag-psd`、`sql.js`、`hyparquet`、`avsc`、FontFace 和 WebAssembly Module 提供 PSD、SQLite、Parquet、Avro、字体、WASM、AI/EPS、WebArchive 预览
EDA renderer	`@file-viewer/renderer-eda`	无	`latest`	标准 renderer 插件，提供 OLB、DRA、GDSII、OASIS 结构预览，标准 GDSII 可生成 SVG/WebGL 版图预览，OASIS 文本夹具可生成 SVG，真实二进制 OASIS 保持结构诊断边界
轻量 renderer preset	`@file-viewer/preset-lite`	无	`latest`	一次装配文本、Markdown、代码、图片、音频和视频预览，适合常见轻附件场景
Office renderer preset	`@file-viewer/preset-office`	无	`latest`	一次装配 PDF、Word、Excel、PowerPoint、OFD、RTF 和 OpenDocument 文档链路
工程 renderer preset	`@file-viewer/preset-engineering`	无	`latest`	一次装配 CAD、3D、绘图、XMind、Geo、Typst、Archive、Data 和 EDA 工程附件链路
全量 renderer preset	`@file-viewer/preset-all`	无	`latest`	一次装配 Word、PDF、OFD、PPTX、CAD、Draw.io/Excalidraw/Mermaid/PlantUML、Typst、XMind、压缩包、邮件、电子书、代码/Markdown/Patch/Git Bundle、图片、音视频和 core 其余完整格式能力
Vite 按需装配插件	`@file-viewer/vite-plugin`	无	`latest`	免配置自动发现已安装 `@file-viewer/preset-*` 并激活对应能力；也可按 `formats`、`renderers` 或源码 hint 生成 `virtual:file-viewer-renderers`，只 import 命中的 renderer 包，并提供 renderer chunk 分组和 PDF/OFD/CAD/Drawing/Typst/Archive/Data 离线资产路线
独立 renderer 包	`@file-viewer/renderer-word`、`@file-viewer/renderer-pdf`、`@file-viewer/renderer-ofd`、`@file-viewer/renderer-presentation`、`@file-viewer/renderer-cad`、`@file-viewer/renderer-drawing`、`@file-viewer/renderer-3d`、`@file-viewer/renderer-data`、`@file-viewer/renderer-eda`、`@file-viewer/renderer-typst`、`@file-viewer/renderer-archive`、`@file-viewer/renderer-email`、`@file-viewer/renderer-epub`、`@file-viewer/renderer-text`、`@file-viewer/renderer-image`、`@file-viewer/renderer-media`、`@file-viewer/renderer-mindmap`、`@file-viewer/renderer-geo`	无	`latest`	用于按需安装 Word、重型版式、文本阅读、图片、媒体、3D、数据资产、EDA 和地理数据链路，避免业务只看轻量格式时安装 DOCX/DOC/PDF/OFD/PPTX/CAD/Draw.io/Excalidraw/Mermaid/PlantUML/Typst/压缩包/邮件/EPUB/XMind/OLB/DRA/GDS/OASIS/GeoJSON/KML/GPX/SHP/PSD/SQLite/Patch/Git Bundle/代码高亮/HEIC/HLS/MIDI 依赖
Vanilla JS / Pure Web / script 标签	`@file-viewer/web`	`@flyfish-group/file-viewer-web`	`latest`	`mountViewer(container, options)`、Custom Element、IIFE、资源复制 CLI、Worker/WASM 自托管工具
Vue3	`@file-viewer/vue3`	`@flyfish-group/file-viewer3`、`file-viewer3`	`latest`	Vue3 原生组件、插件安装、props、事件、ref/controller 和完整类型
Vue2.7	`@file-viewer/vue2.7`	`@flyfish-group/file-viewer`	`latest`	Vue2.7 原生组件，能力和 Vue3 保持一致
Vue2.6	`@file-viewer/vue2.6`	无	`latest`	Vue2.6 专线，面向仍停留在 Vue 2.6 的老项目
React 18/19	`@file-viewer/react`	`@flyfish-group/file-viewer-react`	`latest`	React 原生组件和 hooks/controller，不通过 Vue 或 iframe 转接
React 16.8/17	`@file-viewer/react-legacy`	无	`latest`	面向旧 React 项目的兼容组件包
jQuery	`@file-viewer/jquery`	无	`latest`	jQuery 插件式接入，适合传统后台系统
Svelte	`@file-viewer/svelte`	无	`latest`	Svelte 组件、action 和类型入口

生态边界很清楚: @file-viewer/core 只负责底层预览能力和 API；各标准组件包只依赖 core 和自己的框架依赖，不嵌套其他框架实现；历史兼容包只负责旧包名继续可用，不建议新项目优先选择。

常见安装方式:

pnpm add @file-viewer/web
pnpm add @file-viewer/vue3
pnpm add @file-viewer/react
pnpm add @file-viewer/core
pnpm add @file-viewer/renderer-word
pnpm add @file-viewer/pptx

如果你在内网、离线环境，或者 npm 发布权限还没有完成配置，也可以直接使用开源总仓库 artifacts/ 里的 release tarball。离线安装 React 包时请先安装同版本 web 包:

npm install ./artifacts/file-viewer-core-*.tgz
npm install ./artifacts/file-viewer-pptx-*.tgz
npm install ./artifacts/file-viewer-renderer-word-*.tgz
npm install ./artifacts/file-viewer-web-*.tgz
npm install ./artifacts/file-viewer-vue3-*.tgz
npm install ./artifacts/file-viewer-vue2.7-*.tgz
npm install ./artifacts/file-viewer-vue2.6-*.tgz
npm install ./artifacts/file-viewer-react-*.tgz
npm install ./artifacts/file-viewer-react-legacy-*.tgz
npm install ./artifacts/file-viewer-jquery-*.tgz
npm install ./artifacts/file-viewer-svelte-*.tgz
npm install ./artifacts/flyfish-group-file-viewer3-*.tgz
npm install ./artifacts/flyfish-group-file-viewer-*.tgz
npm install ./artifacts/flyfish-group-file-viewer-web-*.tgz
npm install ./artifacts/flyfish-group-file-viewer-react-*.tgz

Core、PPTX 原生引擎、Vanilla JS / Pure Web、Vue3、Vue2、React、React legacy、jQuery、Svelte 和历史兼容 tarball 都会随开源总仓库一起生成。file-viewer3 非 scoped 兼容包仍会同步发布到 npm，但它和 @flyfish-group/file-viewer3 包体重复，开源总仓库不再重复存储该 tarball。React / 纯 JS 包推荐用 npm install 获得完整依赖体验；如需自托管 Worker、WASM 和示例资源，可运行 pnpm exec file-viewer-copy-assets ./public/file-viewer。

GitHub Release 会同步提供完整下载项:

文件	用途
`file-viewer-v2-*-demo.tar.gz`	主 Demo 静态站，解压后即可体验主预览和 `/compare.html` 文档比对
`file-viewer-v2-*-component-demo.tar.gz`	Vanilla JS / React 原生组件演示站
`file-viewer-v2-*-lib-dist.tar.gz`	Vue3 组件库构建产物，适合离线检查 dist 内容
`file-viewer-v2-*-docs.tar.gz`	文档站静态产物
`file-viewer-core-*.tgz`	`@file-viewer/core` 纯 TypeScript 底座本地 npm 安装包
`file-viewer-pptx-*.tgz`	`@file-viewer/pptx` 原生 PPTX 渲染引擎本地 npm 安装包
`file-viewer-vue3-*.tgz`	Vue3 标准包名本地 npm 安装包
`file-viewer-vue2.7-*.tgz`	Vue2.7 标准组件包本地 npm 安装包
`file-viewer-vue2.6-*.tgz`	Vue2.6 标准组件包本地 npm 安装包
`file-viewer-react-*.tgz`	React 18/19 标准组件包本地 npm 安装包
`file-viewer-react-legacy-*.tgz`	React 16.8/17 标准组件包本地 npm 安装包
`file-viewer-web-*.tgz`	纯 Web 标准组件包，本地安装后可复制 Worker/WASM viewer assets
`file-viewer-jquery-*.tgz`	jQuery 标准组件包本地 npm 安装包
`file-viewer-svelte-*.tgz`	Svelte 标准组件包本地 npm 安装包
`flyfish-group-file-viewer3-*.tgz`	Vue3 本地 npm 安装包
`flyfish-group-file-viewer-*.tgz`	Vue2.7 本地 npm 安装包
`flyfish-group-file-viewer-web-*.tgz`	纯 JS 历史兼容包，提供 `mountViewer` 原生挂载和资源复制工具
`flyfish-group-file-viewer-react-*.tgz`	React 历史兼容包，提供原生 React 组件入口

file-viewer3 非 scoped 历史兼容包仍会走 npm 发布链路；开源总仓库下载区使用 flyfish-group-file-viewer3-*.tgz 作为 Vue3 兼容 tarball，避免重复存储相同包体。

如果 npm 11 安装 tgz 或依赖时报 Cannot read properties of null (reading 'matches')，通常不是 File Viewer 版本不匹配，而是 npm 在混用包管理器后的 node_modules symlink 上触发 Arborist 内部错误。请删除 node_modules 和当前锁文件后，用同一个包管理器重新安装；离线 tgz 场景请确保同版本 core、preset、renderer 和组件包能从私有 npm 源或本地 tarball 依赖闭包解析。项目发布前可运行 pnpm verify:npm-install-smoke，它会用 npm 11.17.0 验证 registry 与 tgz 安装。

标准生态包与公开仓库

下面内容由 ecosystem/wrappers.json 和 packages/core/src/registry/formats.ts 自动生成。开源总仓库同步 README 时会携带同一份索引，确保用户可以从任意入口找到标准 npm 包、历史兼容包、分散组件仓库和 release 下载物。

核心底座包: @file-viewer/core。core 源码已公开，GitHub: https://github.com/flyfish-dev/file-viewer-core，Gitee: https://gitee.com/flyfish-dev/file-viewer-core。开源总仓库提供可直接运行的主 Demo 源码、core、标准组件包、兼容包、文档源码、构建产物、示例文件和 release tarball；私有 Gitea main 是完整原始聚合仓，用于统一自动化、内部集成历史、打赏支持和优先技术支持，不等同于 GitHub 开源总仓库。

框架	标准 npm 包	入口格式	GitHub	Gitee	兼容历史包
Vanilla JS / Pure Web	`@file-viewer/web`	ESM, 类型声明, script 标签 IIFE, Worker/WASM viewer 资源, 复制静态资源 CLI	file-viewer-web	file-viewer-web	`@flyfish-group/file-viewer-web`
Vanilla JS / Pure Web Full	`@file-viewer/web-full`	ESM, 类型声明, script 标签 IIFE	file-viewer-web-full	file-viewer-web-full	无
Vue 3	`@file-viewer/vue3`	ESM, 类型声明	file-viewer-vue3	file-viewer-vue3	`@flyfish-group/file-viewer3`, `file-viewer3`
Vue 3 Full	`@file-viewer/vue3-full`	ESM, 类型声明	file-viewer-vue3-full	file-viewer-vue3-full	无
Vue 2.7	`@file-viewer/vue2.7`	ESM, 类型声明	file-viewer-vue2.7	file-viewer-vue2.7	`@flyfish-group/file-viewer`
Vue 2.7 Full	`@file-viewer/vue2.7-full`	ESM, 类型声明	file-viewer-vue2.7-full	file-viewer-vue2.7-full	无
Vue 2.6	`@file-viewer/vue2.6`	ESM, 类型声明	file-viewer-vue2.6	file-viewer-vue2.6	无
Vue 2.6 Full	`@file-viewer/vue2.6-full`	ESM, 类型声明	file-viewer-vue2.6-full	file-viewer-vue2.6-full	无
React 18/19	`@file-viewer/react`	ESM, 类型声明	file-viewer-react	file-viewer-react	`@flyfish-group/file-viewer-react`
React 18/19 Full	`@file-viewer/react-full`	ESM, 类型声明	file-viewer-react-full	file-viewer-react-full	无
React 16.8/17	`@file-viewer/react-legacy`	ESM, 类型声明	file-viewer-react-legacy	file-viewer-react-legacy	无
React 16.8/17 Full	`@file-viewer/react-legacy-full`	ESM, 类型声明	file-viewer-react-legacy-full	file-viewer-react-legacy-full	无
jQuery	`@file-viewer/jquery`	ESM, 类型声明	file-viewer-jquery	file-viewer-jquery	无
jQuery Full	`@file-viewer/jquery-full`	ESM, 类型声明	file-viewer-jquery-full	file-viewer-jquery-full	无
Svelte	`@file-viewer/svelte`	Svelte 组件, ESM, 类型声明	file-viewer-svelte	file-viewer-svelte	无
Svelte Full	`@file-viewer/svelte-full`	Svelte 组件, ESM, 类型声明	file-viewer-svelte-full	file-viewer-svelte-full	无

工程级按需 renderer 装配

快速开始的核心是先跑通组件，再明确格式能力边界。推荐先安装当前生态组件包，再按产品形态选择 @file-viewer/preset-lite、@file-viewer/preset-office、@file-viewer/preset-engineering 或 @file-viewer/preset-all。Webpack、Rspack、Rollup、Umi、传统多页应用等非 Vite 项目，优先通过 options.preset 或 options.renderers 显式注入能力；Vite 插件只是进一步省掉手动 import 并复制离线资产。

npm i @file-viewer/vue3 @file-viewer/preset-office

import officePreset from '@file-viewer/preset-office'

const options = {
  preset: officePreset,
  rendererMode: 'replace'
}

需要组合办公文档与工程图纸等能力时，继续使用同一个 preset 字段传数组即可：

import officePreset from '@file-viewer/preset-office'
import engineeringPreset from '@file-viewer/preset-engineering'

const options = {
  preset: [officePreset, engineeringPreset],
  rendererMode: 'replace'
}

如果只需要少数格式，也可以安装单 renderer 并传给 options.renderers：

import { pdfRenderer } from '@file-viewer/renderer-pdf'

const options = {
  renderers: [pdfRenderer],
  rendererMode: 'replace'
}

Vite 项目可以再加插件，插件会免配置发现已安装 preset、注入 virtual module，并按命中格式复制 Worker / WASM / 字体 / vendor 资源：

npm i -D @file-viewer/vite-plugin

import { fileViewerRenderers } from '@file-viewer/vite-plugin'

export default {
  plugins: [
    fileViewerRenderers({
      copyAssets: true
      // 无需 preset 配置：插件会自动发现已安装的 @file-viewer/preset-office。
    })
  ]
}

重度用户需要一次拥有官方 Demo 的完整能力时，直接把 preset 换成全量包；非 Vite 项目继续传 options.preset，Vite 配置也保持不变：

npm i @file-viewer/vue3 @file-viewer/preset-all

需要自定义装配时，再显式配置插件：

fileViewerRenderers({
  preset: 'auto',        // 同时开启源码扫描时，仍自动发现已安装 preset
  scan: true,            // 识别 fileViewerFormats、data-file-viewer-formats、accept
  formats: ['pdf'],      // 在已安装 preset 之外额外补充精确 renderer
  copyAssets: true,
  chunkStrategy: 'renderer'
})

严格裁剪或组件库内部测试时，可以关闭自动注入并显式传入 virtual module：

// vite.config.ts
fileViewerRenderers({ formats: ['pdf'], inject: false, copyAssets: true })

// 业务组件入口
import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'

const options = {
  renderers: configuredFileViewerRenderers,
  rendererMode: 'replace'
}

Vue、React、Svelte、jQuery、Vanilla JS / Pure Web 都传同一份 options，只是在各自生态中映射为 props、hook、action、plugin 或 mountViewer(...) 参数。
preset-lite 面向文本、Markdown、代码、图片和音视频；preset-office 面向 PDF / Word / Excel / PowerPoint / OFD；preset-engineering 面向 CAD / 3D / 绘图 / XMind / Geo / Typst / EDA / Data。
想要最小包体时，可以不用 preset，直接安装 @file-viewer/renderer-pdf、@file-viewer/renderer-word 等单个 renderer，并通过 options.renderers 手动注入。
fileViewerRenderers() 或 fileViewerRenderers({ copyAssets:true }) 会免配置自动发现已安装 preset；如果同时开启 scan:true，请使用 preset:'auto' 或 autoPresets:true 保留 preset 自动发现。
scan:true 会识别 fileViewerFormats、data-file-viewer-formats 和上传控件 accept，调试与打包时自动选择 renderer。
copyAssets:true 会复制 PDF/CAD/Typst/Archive/Data 等 worker、WASM 和 vendor 资源，满足离线和企业内网部署。
builtinRenderers 仍可用于高级基线控制或历史兼容；普通快速接入只需要 preset / renderers 与 rendererMode。
如果打开的是支持矩阵内但未装配的格式，预览器会提示应安装的 preset / renderer；只有真正不在矩阵中的扩展名才提示不支持。
@file-viewer/preset-all 是全量一键方案，适合 demo、后台运维工具和企业全格式附件中心；普通业务仍建议优先选择更窄的 preset。

组件属性与工具栏定制摘要

每个生态包都暴露原生接入方式。Vanilla JS / Pure Web 优先面向非框架、Custom Element 和 script 标签场景；Vue3 保持轻量声明式 props；React、Svelte、jQuery 和 Vue2 适合需要 buffer、name、type、size 等命令式挂载参数的场景。完整示例见官方文档: https://doc.file-viewer.app/guide/ecosystem

组件	实际属性 / 入口	事件入口	定制入口
Vanilla JS / Pure Web `@file-viewer/web`	`<flyfish-file-viewer>` 属性 `src/url`、`filename/name`、`type`、`size`、`theme`、`toolbar`、`toolbar-position`、`watermark`、`search`、`options`；也支持 `mountViewer(...)`	`viewer-ready`、`viewer-event`、`viewer-state-change`、`viewer-error`、`onEvent`、`onStateChange`、`controller.subscribe()`	Custom Element 实例暴露完整 controller handle；IIFE script 标签会自动注册元素，同时保留 `mountViewer` 命令式挂载和资源复制 CLI。
Vue 3 `@file-viewer/vue3`	`url`、`file`、`options`	`load-start`、`load-complete`、`unload-start`、`unload-complete`、`operation-before`、`operation-cancel`、`operation-availability-change`、`search-change`、`location-change`、`zoom-change`	模板 `ref` 暴露 `FileViewerExpose`；适合声明式接入。`Blob` / `ArrayBuffer` 建议包装成带扩展名的 `File` 后传给 `file`。
Vue 2.7 `@file-viewer/vue2.7`	`url`、`file`、`buffer`、`name`、`filename`、`type`、`size`、`options`、`containerClass`、`containerStyle`	`viewer-event` / `viewerEvent`	组件实例暴露 controller handle 全量方法；适合 Vue 2.7 项目和历史 `@flyfish-group/file-viewer` 平滑升级。
Vue 2.6 `@file-viewer/vue2.6`	同 Vue 2.7	`viewer-event` / `viewerEvent`	独立 Vue 2.6 构建，不要求业务升级到 Vue 2.7。
React `@file-viewer/react`	`ViewerMountOptions` + `div` 原生属性，如 `className`、`style`、`data-`、`aria-`	`onEvent`、`onStateChange`	`ref` 暴露 `FileViewerHandle`；`useFileViewer()` 会返回 `ref`、`props`、`state`、`handle`，便于自定义工具栏。
React Legacy `@file-viewer/react-legacy`	同 React 标准包	`onEvent`、`onStateChange`	面向 React 16.8 / 17；组件名和默认导出保持 legacy 生态友好。
jQuery `@file-viewer/jquery`	`$(el).fileViewer(ViewerMountOptions & { replace?: boolean })`	`onEvent`、`onStateChange` 或 `getFileViewerController(el).subscribe()`	插件方法支持 `zoomIn`、`printRenderedHtml`、`searchDocument` 等；`replace:false` 可在同一节点上原地更新。
Svelte `@file-viewer/svelte`	`ViewerMountOptions` + `className`、`containerStyle`	`on:viewerEvent`、`onEvent`、`onStateChange`	`bind:this` 暴露 controller handle；也提供 `use:fileViewer` action，action 额外支持 `replace`。

内置工具栏可直接使用，也可以通过 toolbar:false 进入 headless 操作模式，自行用组件 ref、hook、controller、action 或 jQuery plugin method 组装业务工具栏。

工具栏配置	说明
`toolbar: false`	隐藏内置工具栏，但不关闭下载、打印、导出、缩放等 controller API，适合完全自定义业务工具栏。
`toolbar: true`	使用默认内置工具栏，下载、打印、HTML 导出和缩放按钮都会按能力动态显隐。
`download` / `print` / `exportHtml` / `zoom`	表达业务是否允许展示对应按钮；最终仍会结合文件类型、渲染完成状态、导出适配器和缩放 provider 计算真实可用性。
`position`	`auto`、`top`、`bottom-right`。默认 `auto`，PDF 自动悬浮右下角，减少和 PDF 自身页码 / 目录工具栏冲突。
`beforeOperation`	工具栏层统一前置校验，会在 `options.beforeOperation` 后执行。返回 `false` 或抛错都会取消本次操作。
`beforeDownload` / `beforePrint` / `beforeExportHtml`	单按钮前置校验；适合下载权限、打印审计、导出水印确认等细粒度业务规则。

共享格式矩阵当前声明 24 条预览链路、206 个扩展名。完整能力通过 renderer / preset 按需装配，格式说明见本文“支持格式”和官方文档: https://doc.file-viewer.app/guide/formats

支持项目与商业版

Flyfish Viewer 会持续保持 Apache-2.0 开源。开源版适合通用 Web 预览、内网部署、业务附件中心和轻量级集成；如果你需要更高还原度、更极致性能、私有化交付、定制适配或优先技术支持，可以通过下面入口请我们喝杯柠檬水，也可以了解商业版原生文档引擎。

打赏与优先支持: dev.flyfish.group/shop
商业版介绍: product.flyfish.group
商业版 Demo: office.flyfish.dev
飞鱼开源工作室: flyfish.dev

微信赞赏码	支付宝收款码	微信公众号二维码	用户交流群

商业版来自 Flyfish Office 产品线，面向严肃企业场景提供自研原生 Office 文档引擎，重点解决 Word、Excel、PowerPoint 在复杂版式、大文件、分页布局、高保真渲染和稳定性能上的更高要求。开源版会继续维护，商业支持主要用于更快响应、私有化评估和定制交付。

Demo 与 Docker

本仓库保留两个可运行演示入口:

命令	说明
`pnpm dev`	主 Demo，和 demo.file-viewer.app 使用同一条链路
`pnpm dev:components`	Vanilla JS、Vue、React、Svelte、jQuery 生态组件演示
`pnpm build:component-demo`	构建组件演示静态产物
`pnpm docs:dev`	启动文档站

Docker 适合内网、私有云、客户现场或希望直接运行完整 Demo 的场景:

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

访问:

主预览: http://localhost:8080/
文档比对: http://localhost:8080/compare.html

源码仓库内也提供 Dockerfile，本地构建运行:

pnpm docker:build
docker run --rm -p 8080:80 flyfishdev/file-viewer:latest

使用说明

组件支持两条主要输入路径: url?: string 与 file?: File
独立文档比对页位于 /compare.html，可通过 ?left=/example/test.doc&right=/example/word.docx 预置左右文件；它支持同步滚动、当前聚焦文档的浮层搜索、高亮命中、上一个 / 下一个、行级定位和 PDF 工具栏隐藏，但只做视觉并排预览，不做语义 diff，完整说明见 Demo 文档
当 file 和 url 同时存在时，会优先渲染 file
如果业务侧拿到的是 Blob 或 ArrayBuffer，推荐先包装成带扩展名的 File
预览器会填满父容器，请为父容器提供稳定高度
使用 url 预览时，目标资源需要允许浏览器访问；跨域场景下需要正确配置 CORS
如果下载地址本身没有明确扩展名，建议先在业务侧取回文件，再包装成 File
PPTX 渲染器已拆分为独立包 @file-viewer/pptx / flyfish-dev/pptxjs，会尽量还原常见组合图形、旋转/翻转、主题背景、图片裁剪和 EMF 矢量图片；复杂 Office 特效仍建议用真实业务文件做回归
OFD、Typst、XMind、压缩包、邮件、OLB/DRA/GDS/OASIS、CAD、地理数据、3D 模型、绘图、EPUB、UMD、PDF、Office、Markdown、音视频、HLS、HEIC、字体/数据资产和代码高亮渲染器都按需异步加载，只有命中格式时才拉取对应代码块；Typst compiler / renderer WASM 和默认字体可通过 options.typst.compilerWasmUrl、options.typst.rendererWasmUrl、options.typst.fontAssetsUrl 指向自托管地址，默认仅在打开 .typ / .typst 时加载
普通业务优先通过 options.preset 装配 @file-viewer/preset-lite、@file-viewer/preset-office、@file-viewer/preset-engineering 或 @file-viewer/preset-all；多个能力包直接使用 preset: [officePreset, engineeringPreset]。builtinRenderers 仅作为高级基线控制或历史兼容开关保留；UMD / EPUB 电子书均由 @file-viewer/renderer-epub 按需提供
options.archive 一般只需要配置 cache、workerTimeoutMs 和体积上限；预览器会先尝试当前部署 base 下的 vendor/libarchive/worker-bundle.js。手机 WebView、本地临时服务器、MIME 或 CSP 导致 Worker 初始化超时时，会继续降级到 ZIP/TAR/GZIP 兼容模式，避免压缩包一直停在 loading。只有静态目录、CDN 路径或 WASM 位置特殊时，才需要显式传 archive.workerUrl / archive.wasmUrl
表格列宽拖拽通过 options.spreadsheet.resizableColumns: true 显式开启，默认关闭以保持历史交互兼容；官方 Demo 默认开启，方便查看被截断的长文本
options.theme 支持 light、dark、system，默认继续跟随系统；DOCX 由 @file-viewer/renderer-word 内部 @file-viewer/docx 自动选择 Worker 或主线程解析，HTTP/HTTPS 默认 Worker，Electron file:// 等本地不安全协议自动回退，真实浏览器 DOM 渲染、连续流式阅读、目录字段缓存和异步分批挂载，可通过 options.docx.workerUrl、options.docx.workerJsZipUrl 覆盖离线资源路径；如业务明确需要页式预览，可显式设置 options.docx.visualPagination: true；Excel/XLSX 默认使用主线程解析，避免本地服务器、手机 WebView、MIME 或 CSP 导致 Worker 卡住，确实需要静态 Worker 时再传 options.spreadsheet.worker: true 和 options.spreadsheet.workerUrl；PDF 默认探测站点根路径的 PDF.js Worker，可用时使用真实 Worker，不存在或被回退成 HTML 时自动懒加载包内 worker handler 兜底，options.pdf.workerUrl 可覆盖为内网、离线或严格 CSP 的自托管地址；options.watermark 支持文字或图片水印；options.toolbar 可控制下载原文件、打印完整渲染结果、导出 HTML、统一缩放按钮和操作栏位置，toolbar.zoom 可单独控制缩放按钮显示，toolbar.position 支持 auto、top、bottom-right，PDF 默认悬浮到右下角以避开自身导航栏；统一缩放通过渲染器内部 provider 适配 PDF、Word、PPTX、Excel 虚拟表格、图片、CAD、OFD、Typst、Markdown、代码和绘图等链路，避免业务侧外层 CSS 缩放造成表格坐标或 canvas 交互偏移；Excel 多 sheet 时标签栏按内容宽度展示并横向滚动，不会被平均压缩；options.pdf.toolbar 可隐藏 PDF 自身页码缩放工具栏；options.search 可控制搜索高亮、整词/大小写和命中数量；options.ai 可开启文本切片结构，返回行号、页码、锚点和 label 等溯源字段，便于业务侧做向量化、召回、AI 摘要、高亮回填和来源定位；options.hooks 可接收加载/卸载生命周期；options.beforeOperation 可在下载、打印、导出和缩放前做权限校验；打印按钮会结合当前文件类型、渲染完成状态和导出适配器动态显隐，Word / PDF 会生成完整页面，Excel 等虚拟表格会隐藏打印按钮，避免只打印当前视口或第一页

const blob = await response.blob()
const file = new File([blob], 'contract.pdf', { type: blob.type })

本地开发

下面的命令适用于开源总仓库和私有 Gitea 完整聚合仓。GitHub / Gitee 会公开 core、独立渲染引擎包、Demo、标准组件包、兼容包和文档站源码；私有 Gitea 提供完整聚合仓、统一发布脚本、内部自动化和优先技术支持。普通用户仍建议优先通过 npm、开源总仓库 dist/ 或 artifacts/ 里的 tarball 使用。

pnpm install
pnpm dev

常用脚本:

pnpm build: 构建示例站点
pnpm build:vue3: 构建 Vue3 标准组件包产物
pnpm docs:dev: 启动 VitePress 文档站
pnpm docs:build: 构建文档站
pnpm type-check: 执行 TypeScript 类型检查
pnpm dev:components: 启动 React + 纯 JS 组件 Demo
pnpm build:component-demo: 构建组件 Demo
pnpm docker:build: 构建本机架构 Docker 镜像
pnpm docker:publish: 推送 Docker Hub linux/amd64 / linux/arm64 多架构镜像；可通过 DOCKER_IMAGE 替换命名空间
pnpm release:ecosystem:list: 列出当前完整生态 npm 发布目标
pnpm release:ecosystem:pack: 构建并打包 core、标准组件包和历史兼容 npm tarball

打包发布

Vue3 和 Vue2 发包时分别在对应分支执行同一套发布链路:

包	分支	npm 名称
Vue3	`v3`	`@flyfish-group/file-viewer3`
Vue2.7	`v2`	`@flyfish-group/file-viewer`
Core	`packages/core` / `file-viewer-core`	`@file-viewer/core`
React	当前仓库子工程	`@file-viewer/react` / `@flyfish-group/file-viewer-react`
纯 JS	当前仓库子工程	`@file-viewer/web` / `@flyfish-group/file-viewer-web`
其他组件包	当前仓库子工程	`@file-viewer/vue2.7` / `@file-viewer/vue2.6` / `@file-viewer/react-legacy` / `@file-viewer/jquery` / `@file-viewer/svelte`

建议在发布前执行下面这组命令:

pnpm type-check
pnpm build
pnpm build:vue3
pnpm obfuscate
pnpm docs:build
pnpm release:ecosystem:pack

其中:

apps/viewer-demo/dist/ 是正式在线 Demo 和文档比对页的部署产物
packages/components/vue3/dist/ 是 Vue3 标准组件包构建产物；执行 pnpm obfuscate 后会对其中的 .js / .mjs 进行压缩混淆
pnpm build 会生成可独立部署的 Demo 静态站点产物
docs/.vitepress/dist/ 是文档站静态产物
npm pack 会生成可直接发布或分发的 npm 包 tarball

如果只是准备 npm 包，可以直接执行:

pnpm release:ecosystem:pack

完整生态包发布前执行:

pnpm type-check:components
pnpm build:component-demo
pnpm release:ecosystem:list
pnpm release:ecosystem:pack
pnpm release:ecosystem:publish:dry-run
pnpm release:ecosystem:publish

发布到 npm:

npm publish --dry-run --access public
npm publish --access public

如果 npm 账号启用了 MFA，请使用交互式终端完成浏览器确认后再等待发布结果。

开源总仓库会提交 core、Demo、标准组件包、兼容包、文档源码，同时保留可直接使用的构建产物、示例文件和 npm tarball。为避免 Gitee 因历史二进制膨胀超过 1GB，同步 Gitee 时会使用最新完整快照的干净历史。私有 Gitea 仍作为完整聚合仓，保留统一发布脚本、内部集成历史和优先技术支持；需要支持项目或获得优先协助的用户，可以前往 https://dev.flyfish.group/shop，请我们喝杯柠檬水。

文档导航

开源说明

本项目使用 Apache-2.0 许可证。

二开或商用时，请按许可证要求保留版权、许可证和来源说明，并注明项目来源为 Flyfish Viewer / @flyfish-group/file-viewer3 或 @flyfish-group/file-viewer。如果你基于本项目修复了通用问题或增强了通用能力，也欢迎通过 issue / PR 一起贡献回来，让这套预览能力继续变得更稳。

Name		Name	Last commit message	Last commit date
Latest commit History 224 Commits
.github		.github
apps		apps
artifacts		artifacts
component-demo		component-demo
demo		demo
dist		dist
docs-dist		docs-dist
docs		docs
example		example
packages		packages
BRANCHES.md		BRANCHES.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
RELEASE_TEMPLATE.md		RELEASE_TEMPLATE.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
WRAPPER_ECOSYSTEM.md		WRAPPER_ECOSYSTEM.md
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

File Viewer

项目定位

亮点

按场景选择入口

在线效果

兼容性反馈

快速开始

CDN / Script 标签

Vanilla JS

Vue 3

Vue 2

React

Svelte

jQuery

按需组合

架构

入口

支持格式

能力组合

当前 npm 生态

标准生态包与公开仓库

工程级按需 renderer 装配

组件属性与工具栏定制摘要

支持项目与商业版

Demo 与 Docker

使用说明

本地开发

打包发布

文档导航

开源说明

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 18

Packages 0

Uh oh!

Contributors 1

Languages

Packages