发布与开源分发

Release For Users

这一页说明 Flyfish Viewer 对外分发时包含什么、如何安装、如何发布私有化 Worker/WASM viewer assets，以及开源总仓库和私有 Gitea 聚合仓之间的职责。 GitHub / Gitee 的 flyfish-dev/file-viewer 是开源总仓库和主分发入口，包含可运行的主 Demo 源码、core、标准组件包、兼容包、文档源码和 release 索引；完整静态站点产物通过 GitHub Release 或 Cloudflare Pages 分发。 为控制国内镜像仓库体积，Gitee 同步使用最新完整快照的干净历史，避免多轮二进制构建历史叠加。 Gitee 镜像同步同一份开源总仓库内容，方便国内网络环境下载和部署。

分发渠道

渠道	地址	内容
官方网站	file-viewer.app	一站式组件门户、产品定位、应用场景、资源导航和商业支持入口
官方文档/组件主页	doc.file-viewer.app	主文档域名，提供组件主页、接入文档、格式说明和开源分发说明
在线 Demo	demo.file-viewer.app	可直接体验完整预览器，用于快速验证能力
文档比对 Demo	demo.file-viewer.app/compare.html	独立入口，支持左右并排预览、上传、URL、交换、重置、同步滚动、聚焦搜索和行级定位
官方 iframe Demo 交付包	GitHub Release: file-viewer-v2-*-official-demo-iframe.tar.gz	官方 Demo 的零依赖构建产物，包含 iframe.html、兼容原主 Demo 的 index.html、父页面示例、说明文件、样例和离线 Worker/WASM/vendor 资源
Docker 镜像发布目标	flyfishdev/file-viewer:latest	可一键部署的 nginx 静态镜像，发布时支持 linux/amd64 和 linux/arm64
npm 标准生态	生态组件总览	@file-viewer/core、独立 renderer、preset、@file-viewer/pptx 原生引擎、Vanilla JS / Pure Web、Vue3、Vue2.7、Vue2.6、React、React Legacy、jQuery、Svelte 全线标准包
自托管静态资源	file-viewer/assets/*、file-viewer/vendor/*、file-viewer/wasm/*	Worker、WASM、示例文件和重型渲染器资源，按需自托管
GitHub 开源总仓库	github.com/flyfish-dev/file-viewer	一站式入口: README、LICENSE、主 Demo 源码、core、标准组件包、兼容包、文档源码、构建产物、示例和 release tarball
Gitee 开源总仓库	gitee.com/flyfish-dev/file-viewer	国内镜像目标，使用干净历史控制仓库体积；如远端配额阻塞，以 GitHub 开源总仓库和 release 为准
打赏与优先支持	https://dev.flyfish.group/sponsor?source=github	请我们喝杯柠檬水后，可获得完整聚合仓访问、优先技术支持和维护协助

npm 安装

新项目优先使用 @file-viewer/* 标准包名。历史 @flyfish-group/* 包继续同步发布，但主要用于旧项目平滑升级。

场景	标准包	历史兼容包
Core 底座	@file-viewer/core	无
PPTX 原生引擎	@file-viewer/pptx	无
Word renderer	@file-viewer/renderer-word	无
演示文稿 renderer	@file-viewer/renderer-presentation	无
绘图 renderer	@file-viewer/renderer-drawing	无
3D 模型 renderer	@file-viewer/renderer-3d	无
数据资产 renderer	@file-viewer/renderer-data	无
EDA renderer	@file-viewer/renderer-eda	无
轻量 renderer preset	@file-viewer/preset-lite	无
Office renderer preset	@file-viewer/preset-office	无
工程 renderer preset	@file-viewer/preset-engineering	无
全量 renderer preset	@file-viewer/preset-all	无
Vite 按需装配插件	@file-viewer/vite-plugin	无
Vanilla JS / Pure Web / script 标签	@file-viewer/web	@flyfish-group/file-viewer-web
Vue3	@file-viewer/vue3	@flyfish-group/file-viewer3、file-viewer3
Vue2.7	@file-viewer/vue2.7	@flyfish-group/file-viewer
Vue2.6	@file-viewer/vue2.6	无
React 18/19	@file-viewer/react	@flyfish-group/file-viewer-react
React 16.8/17	@file-viewer/react-legacy	无
jQuery	@file-viewer/jquery	无
Svelte	@file-viewer/svelte	无

常用安装命令:

pnpm add @file-viewer/vue3 @file-viewer/preset-office
# 重度用户 / 全格式附件中心:
pnpm add @file-viewer/vue3 @file-viewer/preset-all
# 非 Vite 或特定生态也可把 @file-viewer/vue3 替换为 @file-viewer/web / react / vue2.7 / vue2.6 / jquery / svelte。

Webpack、Rspack、Rollup、Umi、传统多页应用和内部组件库通过 options.preset 显式注入 preset。Vite 项目可以额外安装插件并使用免配置自动装配：

pnpm add -D @file-viewer/vite-plugin

fileViewerRenderers({
  copyAssets: true
})

插件会自动发现已安装的 @file-viewer/preset-* 并注入能力；需要极致裁剪时再用单 renderer + formats。

常用定制边界：

配置	说明
copyAssets:true	复制命中的 Worker、WASM、字体、PDF/CAD/Typst/Archive/Data 等静态资源，推荐生产和内网部署开启
formats / renderers	不使用 preset、或在 preset 外补充少数格式时，生成精确 renderer import
scan:true	扫描源码中的 fileViewerFormats、data-file-viewer-formats、上传 accept 等格式 hint
preset:'auto' / autoPresets:true	开启 scan:true 时继续保留已安装 preset 的自动激活
inject:false	关闭自动注入，改为手动导入 virtual:file-viewer-renderers 并传入 options.renderers

Vanilla JS / Pure Web:

<flyfish-file-viewer
  src="/files/demo.pdf"
  theme="light"
  style="display:block;height:100vh"
></flyfish-file-viewer>

<script type="module">
  import { defineFileViewerElement } from '@file-viewer/web'
  defineFileViewerElement()
</script>

Vue3:

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

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

Vue2.7:

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

Vue.use(FileViewer)

new Vue({
  render: h => h(App)
}).$mount('#app')

React:

import FileViewer from '@file-viewer/react'

export function Preview() {
  return (
    <div style={{ height: '100vh' }}>
      <FileViewer url="/files/demo.docx" />
    </div>
  )
}

Svelte、jQuery、React Legacy、Vue2.6、Core 自定义接入和 script 标签示例见 生态组件总览。Vanilla JS / Pure Web、React、jQuery 和 Svelte 标准接入不需要配置独立静态页面地址。只有当你希望固定 Worker、WASM 或示例文件的访问路径时，才需要执行 pnpm exec file-viewer-copy-assets ./public/file-viewer。复制脚本会写入 flyfish-viewer-assets.json，按 core renderer asset manifest 校验 archive、CAD、DOCX、Spreadsheet、Typst、SQLite 等 worker/WASM 静态资源。

Release Tarball 安装

如果你在内网、离线环境，或者 npm 发布权限还没有完成配置，也可以直接使用开源总仓库 artifacts/ 里的 release tarball:

npm install ./artifacts/flyfish-group-file-viewer3-*.tgz
npm install ./artifacts/file-viewer-core-*.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-web-*.tgz
npm install ./artifacts/file-viewer-jquery-*.tgz
npm install ./artifacts/file-viewer-svelte-*.tgz
npm install ./artifacts/file-viewer-renderer-word-*.tgz
npm install ./artifacts/file-viewer-renderer-presentation-*.tgz
npm install ./artifacts/file-viewer-preset-all-*.tgz
npm install ./artifacts/file-viewer-pptx-*.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、独立 renderer、preset、PPTX 原生引擎、Vanilla JS / Pure Web、Vue3、Vue2.7、Vue2.6、React、React Legacy、jQuery、Svelte 和历史兼容 tarball 都会随开源总仓库一起生成。file-viewer3 非 scoped 兼容包仍会同步发布到 npm，但它和 @flyfish-group/file-viewer3 包体重复，开源总仓库下载区只保留 flyfish-group-file-viewer3-*.tgz 这一份 Vue3 兼容 tarball。React tarball 依赖 web viewer 包，离线安装时请按 npm 依赖关系一起放入本地源或依次安装。

纯离线部署时，除了 npm tarball，也要把 viewer assets 一起发布到业务静态目录。运行 file-viewer-copy-assets 会复制 PDF.js worker/CMap/WASM/standard fonts、CAD WASM、Typst WASM/默认字体、SQLite WASM、压缩包 worker 和 Office worker，并生成 flyfish-viewer-assets.json 供验收。运行时默认不会访问公共 CDN 或第三方在线静态资源；路径特殊时通过各格式的 options.*Url 指向自托管地址。

Vue full 包的默认静态前缀是 /file-viewer/。如果你把资产发布到这个目录，@file-viewer/vue3-full、@file-viewer/vue2.7-full 和 @file-viewer/vue2.6-full 会自动指向 /file-viewer/vendor/libarchive/worker-bundle.js、/file-viewer/vendor/libarchive/libarchive.wasm、PDF.js、DOCX、PPTX、CAD、Typst、Draw.io 和 SQLite 等资源。部署在其它前缀时，启动前调用 setDefaultFullAssetBaseUrl('/your-prefix/')，或继续使用对应的 options.archive.*、options.pdf.*、options.typst.* 等显式配置。

官方 Demo iframe 交付包

客户需要“直接拿官方 Demo 构建产物做 iframe 集成”时，使用 GitHub Release 中的 file-viewer-v2-*-official-demo-iframe.tar.gz。这个包不要求业务项目安装 npm 包，解压后把所有文件发布到同一个静态目录即可，目录中的 assets/、vendor/、wasm/ 和 example/ 必须保持相对位置不变。

/iframe.html 是推荐的无 Demo 外壳入口，支持 clean URL 的静态平台也可以写成 /iframe；/index.html 保留原主 Demo 能力，并兼容同一套 url、from、name 和 postMessage(Blob) 协议。

URL 文件嵌入:

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

父页面拿到二进制后再传入 iframe:

<iframe
  id="viewer"
  src="/file-viewer/iframe.html?from=https%3A%2F%2Fapp.example.com&name=contract.docx"
></iframe>
<script>
  const file = await fetch('/api/files/contract.docx').then(response => response.blob())
  document.querySelector('#viewer').contentWindow.postMessage(file, 'https://static.example.com')
</script>

from 必须等于父页面 origin，Demo 只接受该 origin 发来的 Blob。包内的 iframe-example.html 同时覆盖 URL 与本地文件 postMessage 两条路径；发布前由 pnpm release:demo-iframe:pack 和 pnpm verify:demo-iframe-artifact 生成并校验，随后进入 release:standard:build、release:public 和 GitHub Release 附件校验链路。

部署到 Cloudflare Pages 时，平台会根据访客 Accept-Encoding 自动启用边缘压缩。项目的 scripts/deploy-cloudflare-pages.mjs 还会在 Direct Upload 前对超过 Pages 单文件限制的 WASM 做 Brotli 预压缩，并在 _headers 中写入 Content-Encoding: br、Vary: Accept-Encoding、Content-Type: application/wasm 和长期缓存策略，确保 27MB 级 Typst compiler WASM 仍然通过原始 .wasm URL 稳定加载。上线后运行下面的命令确认官网、文档站、Demo 和 Typst WASM 都已经走 Cloudflare 压缩:

pnpm verify:cloudflare-compression

开源总仓库内容

GitHub / Gitee 的 flyfish-dev/file-viewer 是开源总仓库，用于分发开源源码、Demo / 文档源码和 release 元数据。私有 Gitea 继续作为完整聚合仓、统一发布脚本、内部自动化和优先技术支持入口。仓库内容包括:

• packages/core/: framework-neutral core 源码
• packages/components/: Vanilla JS / Pure Web、Vue、React、jQuery、Svelte 等标准组件包源码
• packages/compat/: 历史 npm 包名兼容 alias 源码
• apps/: 主 Demo 和组件 Demo 源码
• dist/: 混淆压缩后的组件库产物
• docs/: VitePress 文档源码
• artifacts/: release manifest、状态报告和可上传到 GitHub Release 的 tarball
• Dockerfile / Docker Hub 标签: 可直接部署的静态镜像构建与发布信息
• README.md: 默认中文入口，提供友好的安装、嵌入、下载和授权说明
• README.en.md: 完整英文入口，与中文 README 互相提供语言切换链接，便于海外客户快速评估和接入
• LICENSE: 项目许可证

其中 README.md 会承担开源总仓库首页职责，写明官方文档、在线 Demo、npm 包、私有化部署、源码目录、release 下载物和支持入口。apps/、packages/ 和 docs/ 默认保留源码，主 Demo、component demo、文档站和样例文件的构建产物不再作为顶层目录常驻提交，避免 GitHub clone 被静态站点和二进制样例拖大。需要下载站点产物时，从 GitHub Release 或 Cloudflare Pages 部署域名获取。

如果确实需要生成完整展开目录，可以显式使用 FILE_VIEWER_PUBLIC_EXPANDED_ASSETS=1 或 --expanded-assets。该模式只用于一次性交付、离线包检查或临时镜像排障，不作为公开 GitHub / Gitee 的默认发布形态。

开源总仓库会包含 apps/、packages/core/、packages/components/、packages/compat/ 和 docs/ 等源码，同时继续保留可直接部署或下载的 release 产物。

发版命令

2.x 之后，生态包从完整聚合仓统一构建、校验和发布。发布前建议执行:

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

其中 pnpm obfuscate 会处理 packages/components/vue3/dist/ 中的 .js / .mjs 文件。类型声明、CSS、图片和示例文件不会被混淆，便于业务方正常接入和排查。

正式发布前建议先执行:

npm publish --dry-run --access public

确认包名、版本、README 和 dist/ 文件无误后，再执行 npm publish --access public。如果 npm 账号启用了 MFA，请使用交互式会话完成浏览器确认。

生态包发布:

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

release:ecosystem:pack 会先构建 core、独立 renderer、preset、PPTX 原生引擎、标准组件包和历史兼容包，再统一打包当前 35 个 npm 目标。发布前请确认 tarball 中包含必要的 viewer assets、dist/*、README / README.en.md，且没有 .DS_Store。

开源总仓库使用私有 Gitea main 完整聚合仓生成，发布前执行:

pnpm release:public

该命令会同步开源源码、混淆后的 dist/、release 元数据和生态 tarball，并在写入后自动执行 pnpm verify:public-main。默认不会把 Demo、component demo、文档静态产物和示例文件展开写入开源总仓；如需完整展开，请显式追加 --expanded-assets。如果只想检查已经生成的开源总仓库内容，可以执行:

pnpm verify:public-main

校验会反查 artifacts/release-manifest.json、artifacts/release-status.json、artifacts/release-status.schema.json、所有应公开 tarball、README / README.en.md、组件 GitHub / Gitee 索引和顶层目录边界，避免漏掉源码、重复 tarball 或发布过期产物。release-manifest.json 会通过 metadataAssets 索引 manifest、status 和 schema 三份元数据；release-status.json 的 sourceBaseline 会明确私有 Gitea main 才是完整原始聚合仓基线，本地 checkout 分支名只是执行上下文；release-status.schema.json 是状态报告的公开 JSON Schema，可用于 CI 或下载端判断哪些缺口是本地可修项、哪些是 npm / Gitee / GitHub 等外部发布阻塞。

Docker 镜像发布

Docker 镜像用于一键部署主 Demo、零依赖 iframe 入口和文档比对页。发布前先确保 Docker Hub 已登录，并且当前账号对 flyfishdev/file-viewer 有推送权限:

docker login
DOCKER_IMAGE=flyfishdev/file-viewer pnpm docker:publish

默认会推送 latest 和 latest 两个标签，并生成 linux/amd64 / linux/arm64 多架构 manifest。发布后至少验证:

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

然后打开 /、/iframe.html?url=/example/word.docx、/compare.html 和 /healthz。

授权和贡献

项目使用 Apache-2.0 许可证。二开或商用时，请保留许可证、版权和来源说明，并注明项目来源为 Flyfish Viewer / @flyfish-group/file-viewer3 或 @flyfish-group/file-viewer。

如果你修复了通用问题或增强了通用能力，建议通过 issue / PR 一起贡献回来。这样后续升级时，大家都能少走一点弯路。