# @file-viewer/vite-plugin 中文文档

规范地址：https://npmcn.com/package/%40file-viewer/vite-plugin/

版本：3\.3\.3
npm 元数据更新时间：2026-10-31T11:06:38.866Z
中文译文更新时间：2026-11-14T17:42:10.608Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40file-viewer/vite-plugin
原文对照：https://npmcn.com/package/%40file-viewer/vite-plugin/?lang=original
项目主页：https://doc.file-viewer.app/guide/on-demand-renderers
源码仓库：https://github.com/flyfish-dev/file-viewer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：163 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vite \>=5 \<9
- 首次发布：2026-06-23T06:26:46.535Z
- 最新版本发布：2026-10-31T11:06:38.509Z
- 近 30 天下载量：103448（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 61 个）

## 中文简介

文件查看器按需渲染器组装、块规划和离线资产部署的 Vite 插件.

## 安装

```sh
npm install @file-viewer/vite-plugin
```

也可以使用：`pnpm add @file-viewer/vite-plugin`、`yarn add @file-viewer/vite-plugin`、`bun add @file-viewer/vite-plugin`

## README

# @file-viewer/vite-plugin

[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.zh-CN.md)

[![npm version](https://img.shields.io/npm/v/@file-viewer%2Fvite-plugin?logo=npm)](https://www.npmjs.com/package/@file-viewer/vite-plugin) [![npm downloads](https://img.shields.io/npm/dm/@file-viewer%2Fvite-plugin?logo=npm)](https://www.npmjs.com/package/@file-viewer/vite-plugin) [![GitHub stars](https://img.shields.io/github/stars/flyfish-dev/file-viewer?style=flat&logo=github)](https://github.com/flyfish-dev/file-viewer/stargazers) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE)

[GitHub](https://github.com/flyfish-dev/file-viewer) · [文档](https://doc.file-viewer.app/zh/) · [在线 Demo](https://demo.file-viewer.app/) · [格式矩阵](https://doc.file-viewer.app/guide/formats) · [问题反馈](https://github.com/flyfish-dev/file-viewer/issues) · [English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/presets/vite-plugin/README.md)

[![File Viewer 在线演示：Word、Excel、PPT、3D 模型、CAD 图纸与二进制检查器](https://raw.githubusercontent.com/flyfish-dev/file-viewer/main/docs/public/_media/file-viewer-demo-v3-zh.webp)](https://demo.file-viewer.app/)

> ⭐ 如果 File Viewer 对你有帮助，欢迎到 [GitHub](https://github.com/flyfish-dev/file-viewer) 点个 Star。

Flyfish File Viewer 的 Vite 按需 renderer 自动装配插件。它可以自动发现已安装的 `@file-viewer/preset-*` 和 `@file-viewer/*-full` 包，让 Vue、React、Svelte、jQuery 和 Vanilla JS 组件无需手动传 `renderers` 就获得对应预览能力；也可以根据业务声明的文件格式生成 `virtual:file-viewer-renderers`，只 import 命中的 renderer 包，并提供 chunk 分组和离线 worker/WASM/字体资源复制能力。

## 最快开始

需要完整格式支持时，最快路径是“full 包 + 注册一次 Vite 插件”。full 已内置 `preset-all`，不要再安装 preset；`copyAssets:true` 会在开发和构建时自动匹配 full 包，并把 Worker、WASM、字体和 vendor 文件发布到部署基址下的 `file-viewer/`（根部署即 `/file-viewer/`）：

```bash
pnpm add @file-viewer/vue3-full
pnpm add -D @file-viewer/vite-plugin
```

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

export default defineConfig({
  plugins: [
    fileViewerRenderers({
      copyAssets: true
    })
  ]
})
```

只安装 full 包而不启用资源复制，PDF Worker、CAD/Typst/Archive WASM 等格式会缺少运行文件，只能获得部分格式支持。

需要更小体积时，改用“标准组件包 + 一个 preset”，Vite 配置保持不变。插件会自动发现已安装的 preset，无需手写 renderer import，也无需显式写 `preset:'office'`：

```bash
pnpm add @file-viewer/vue3 @file-viewer/preset-office
pnpm add -D @file-viewer/vite-plugin
```

组件默认 `autoRenderers:true`，会读取 Vite 插件注入的 preset / renderer registry。常规业务代码只要使用 `@file-viewer/vue3`、`@file-viewer/react`、`@file-viewer/web`、`@file-viewer/svelte`、`@file-viewer/jquery`、`@file-viewer/vue2.7` 或 `@file-viewer/vue2.6` 即可获得对应能力。

可选 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 完整格式矩阵。

如果只需要极少数格式，也可以安装对应 renderer 包，例如 `@file-viewer/renderer-pdf`、`@file-viewer/renderer-word`、`@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-text`，再通过 `formats` 做精确裁剪。

## vite.config.ts

推荐默认使用 full/preset 自动装配。只传 `copyAssets:true` 时，插件会自动发现已安装的 `@file-viewer/*-full` 或 `@file-viewer/preset-*`，无需写 `preset:'all'`：

```ts
fileViewerRenderers({
  copyAssets: true
})
```

只有在需要源码扫描、单格式裁剪、或手动 registry 管理时，再使用自定义能力：

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

export default defineConfig({
  plugins: [
    fileViewerRenderers({
      formats: ['pdf', 'dwg', 'typst', 'zip', 'xmind'],
      scan: true,
      copyAssets: true,
      chunkStrategy: 'renderer'
    })
  ]
})
```

`inject` 默认开启，插件会把 `virtual:file-viewer-renderers` 注入 Vite HTML 入口，preset 导入后会自动注册到 core。常规业务只需要安装组件包和对应 preset，组件会通过 `autoRenderers` 默认读取这些能力。

```ts
const options = {
  // 默认 true；需要完全手动控制时设为 false。
  autoRenderers: true
}
```

### 可定制能力

| 选项 | 说明 |
| --- | --- |
| `copyAssets` | `true` 或 `{ publicDir, outDir, mode, baseDir }`；复制匹配的 Worker、WASM、字体和 vendor 资源。检测到 full 时默认发布到 `<部署基址>/file-viewer/`，这是 full 完整格式支持的必需项；标准包/preset 保持原有根目录行为 |
| `preset` | \`'auto' |
| `autoPresets` | `true` 或 preset 列表；常用于 `scan:true` 时继续自动激活已安装 preset |
| `formats` | 文件扩展名或格式 token，例如 `['pdf', 'docx', 'dwg']` |
| `renderers` | renderer id，例如 `['pdf', 'word', 'cad']` |
| `scan` | `true` 或 `{ roots, extensions, maxFileSize }`，扫描源码 hint 并合并格式 |
| `inject` | 默认 `true`；设为 `false` 后手动导入 `virtual:file-viewer-renderers` |
| `chunkStrategy` | \`'renderer' |
| `stabilizeInteropChunks` | 默认 `true`；为默认分组和宿主 `manualChunks` 稳定 Pako / CommonJS 辅助模块及 CodeMirror / Lezer / Sandpack 的分组 |
| `missingRenderer` | \`'error' |

如果宿主项目按包名拆分 `node_modules`，`@codemirror/*`、`@lezer/*` 和 Sandpack 之间的循环依赖可能在生产构建中表现为 `codemirror-view.* Cannot access ... before initialization`。插件同时稳定默认分组和已有的 `manualChunks` 函数：Pako 与共享 CommonJS 辅助模块归入 `vendor-commonjs`，避免压缩格式的初始化循环；CodeMirror / Lezer / Sandpack 归入 `vendor-codemirror`。Vite 8 使用对应的 Rolldown 分组，其它自定义分组保持不变；确实需要完全接管时可设置 `stabilizeInteropChunks:false`。

`copyAssets.baseDir` 可以覆盖自动目录：必须是相对路径，不能包含 `..`；传空字符串表示显式复制到根目录。插件会为标准包、preset 和 full 包同步统一运行时资源根；full 包仍同时同步 `setDefaultFullAssetBaseUrl()`。只有设置 `inject:false` 且不手动导入虚拟模块时，业务才需要调用 `setDefaultFileViewerAssetBaseUrl()`（full 包同时调用 `setDefaultFullAssetBaseUrl()`）。Vite 配置了 `base:'/app/'` 时，full 包开发 URL 为 `/app/file-viewer/...`，构建文件仍位于 `outDir/file-viewer/`。

资源复制在开发服务器启动/重启及生产构建结束时执行，不随普通 HMR 执行。内容相同的文件不会被重复写入，生成的清单不再包含易变的 `copiedAt` 时间戳。Vite 自身清空构建目录、复制 public 目录的行为保持不变。

如果你需要严格控制 registry，可以关闭注入并手动传入：

```ts
fileViewerRenderers({
  formats: ['pdf'],
  inject: false,
  copyAssets: true
})
```

```ts
import { configuredFileViewerRenderers } from 'virtual:file-viewer-renderers'

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

也可以使用 `preset: 'auto'` 发现项目中已安装的 preset 包；当 `preset-all` 存在时会优先使用它，避免重复导入其它 preset。注意：如果同时开启 `scan:true`，请显式使用 `preset:'auto'` 或 `autoPresets:true`，否则插件会以源码 hint 为准，不再做“无配置 preset 自动发现”。

```ts
fileViewerRenderers({
  preset: 'auto',
  scan: true,
  formats: ['pdf'],
  copyAssets: true,
  chunkStrategy: 'renderer'
})
```

`scan: true` 会扫描常见源码目录里的轻量 hint，并把它们合并到 `formats`：

```ts
export const fileViewerFormats = ['pdf', 'docx', 'xlsx']
```

```html
<input accept=".pdf,.docx" data-file-viewer-formats="dwg,xmind" />
```

这适合业务把上传入口、示例矩阵或附件白名单维护在源码中时使用：开发和构建阶段插件会自动生成 renderer 装配模块，少写一份手工 import 清单。

## 缺失 renderer 提示

如果用户打开的是支持矩阵内的格式，但项目没有安装或装配对应 renderer，core 会显示“需要装配预览能力”，并提示推荐安装的 preset / renderer 包，例如 `.pdf` 会引导安装 `@file-viewer/preset-office` 或 `@file-viewer/renderer-pdf`。只有真正不在支持矩阵中的扩展名才显示“不支持在线预览”。

## 嵌套 Vite 项目

从 3.0.3 起，子目录只有项目元数据或 Vite 插件声明时，会沿祖先 `package.json` 查找实际可解析的 Full 依赖。子项目明确声明轻量组件或 preset 时保留其根目录资产布局， 不会继承父项目的 Full 布局。`copyAssets.baseDir` 仍具有最高优先级；`publicDir` 和 `build.outDir` 均相对于 Vite root，不相对于依赖所在目录。

## 当前边界

当前插件会为已经拆出的 renderer 包生成导入：Word、Spreadsheet、PDF、OFD、Presentation、CAD、Draw.io/Excalidraw/Mermaid/PlantUML、3D、Data、EDA、Typst、压缩包、邮件、EPUB、代码/Markdown/Patch/Git Bundle、图片、媒体、XMind 和 Geo。可以通过 `formats` 显式声明，也可以通过 `scan: true` 从源码 hint 自动发现；`.zipx`、`.cbz`、`.tiff`、`.mjs`、`.gv`、`.patch`、`.bundle`、`.mermaid`、`.puml`、`.mpeg` 等 core 支持的扩展也会映射到对应 renderer。开启 `copyAssets:true` 时会识别已安装能力；full 包把匹配资源复制到开发 `publicDir/file-viewer/` 与构建 `outDir/file-viewer/`，标准包/preset 维持根目录行为，包括 Typst compiler / renderer WASM 与默认字体目录。`preset: 'auto' | 'lite' | 'office' | 'engineering' | 'all'` 会导入对应 `@file-viewer/preset-*` 包；如果同时声明 `formats`，插件会在 preset 之外补充额外 renderer。

## 文档

-   按需渲染架构: [https://doc.file-viewer.app/guide/on-demand-renderers](https://doc.file-viewer.app/guide/on-demand-renderers)
-   支持格式: [https://doc.file-viewer.app/guide/formats](https://doc.file-viewer.app/guide/formats)

## 格式与相关包

File Viewer 在浏览器内预览 275+ 种扩展名，覆盖 Office、PDF/OFD、CAD、3D、压缩包、邮件、图片、音视频和代码，无需服务端转码；完整清单见 [格式矩阵](https://doc.file-viewer.app/guide/formats)。

-   组件：`@file-viewer/web`、`@file-viewer/vue3`、`@file-viewer/vue2.7`、`@file-viewer/vue2.6`、`@file-viewer/react`、`@file-viewer/react-legacy`、`@file-viewer/svelte`、`@file-viewer/jquery`，以及对应的 `-full` 包
-   能力组合：`@file-viewer/preset-lite`、`@file-viewer/preset-office`、`@file-viewer/preset-engineering`、`@file-viewer/preset-all`
-   构建：`@file-viewer/vite-plugin`、`file-viewer-copy-assets`

## 许可证

本包采用 Apache-2.0。详见 [LICENSE](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE)。

## 常见问题

### @file-viewer/vite-plugin 是什么？

文件查看器按需渲染器组装、块规划和离线资产部署的 Vite 插件\.

### 如何安装 @file-viewer/vite-plugin？

在项目目录运行 npm install @file-viewer/vite-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（\>=5 \<9）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @file-viewer/vite-plugin 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @file-viewer/vite-plugin 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @file-viewer/vite-plugin 可以商用吗？

@file-viewer/vite-plugin 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @file-viewer/vite-plugin 的下载量有多少？

根据 npm 官方下载统计，@file-viewer/vite-plugin 在 2026/10/15 – 2026/11/13 这 30 天内被下载 103,448 次，日均约 3,448 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @file-viewer/vite-plugin 还在维护吗？

最新版本 3\.3\.3 发布于 2026/10/31（14 天前）；至今共发布 61 个版本，其中过去 12 个月发布了 61 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。