File Viewer 3.0.0 发布复盘：从依赖包到可验证的安装事务

File Viewer 3.0.0 发版时，我最在意的并不是又增加了多少格式，而是终于能把一次文件预览接入说清楚了。

过去的接入方式很像一张购物清单：安装组件包，复制 Worker 和 WASM，再把示例代码放进页面。顺利时十分钟能看到 Demo；不顺利时，问题会在部署、升级或离线环境里慢慢冒出来。

3.0.0 因此把 CLI 作为主线。它需要处理的不是一条安装命令，而是一笔有规划、有写入边界、有资源回执、失败后能回滚的安装事务。

第一件事不是安装，而是把方案算出来

文件预览的依赖差异很大。PDF、Office、CAD、DICOM 和数字签名容器背后不是同一套解析器，也不该默认进入每一个业务项目。

npx file-viewer-cli@3.0.0 plan \
  --framework vue3 \
  --profile standard \
  --package-manager pnpm

plan 不改项目，只列出精确包版本、生成模块、静态资源、许可证提示、体积估算和安装命令。对 Vue 3 的 standard 方案，它会把约 30.4 MB 打包依赖、101.7 MB 解包内容与约 24.1 MB 静态资源分开说明。

这种输出比“标准版适合大多数项目”有用。架构评审可以直接讨论体积、格式边界和运行时资源，而不是等到安装后再拆包。

244 个扩展名必须先变成能力模型

当前格式目录登记 244 个扩展名和 34 条预览链路，其中 221 个扩展名属于稳定集合，23 个属于按需或实验能力。

CLI 提供 lite、standard、office、engineering、all 等预设，也允许直接按格式选择。这里的预设不是把格式数量做成营销数字，而是把依赖、静态资源和能力边界放进同一份配置。

npx file-viewer-cli@3.0.0 create oa-preview \
  --framework vue3 \
  --profile standard \
  --formats pdf,docx,xlsx,pptx \
  --package-manager pnpm \
  --non-interactive --yes

DICOM 没有因为选择 all 就自动安装。它当前只覆盖本地单文件和多帧影像预览，不声称支持 PACS、DICOMweb、序列、MPR 或诊断。数字签名容器也把结构检查、密码学检查与证书信任、业务策略、法律效力分开处理。

这些限制写进能力模型之后，安装器才知道哪些内容可以自动完成，哪些决定必须留给业务系统。

旧项目检测的关键是“何时停手”

新项目的目录结构可控，旧项目则常常同时留下 npm 与 pnpm 锁文件、旧版 Webpack 配置、Vite 迁移入口和几个名字相近的应用目录。

cd existing-app
npx file-viewer-cli@3.0.0 add .

CLI 会识别锁文件、框架版本、Vite、Vue CLI、Webpack、Next.js、Nuxt 2/3、静态目录与应用入口。只有证据能指向唯一结果时，才生成接入文件和安装依赖。

如果入口存在歧义，它会在写入前停止，并把人工步骤输出出来。这里的设计原则很朴素：停止只是多一次确认，猜错入口却可能把正在运行的应用改坏。

运行时资源不能只靠一次复制

Worker、WASM、字体和其他运行时文件是最容易在部署中丢失的内容。包升级了，服务器上的静态目录未必同步；多个渲染能力共享目录时，后安装的脚本也可能覆盖先前文件。

3.0.0 为受管理资源记录包版本、能力配置、SHA-256 与所属模块。合并复制时只处理工具拥有的文件，显式清理则要求 --clean --confirm，并检查目标是否为专用安全目录。

资源回执解决了一个常见误区：node_modules 中的版本正确，不代表浏览器请求到的 Worker 与 WASM 也是这一版。两边需要分别验证。

离线安装需要完整性清单，也需要回滚

npx file-viewer-cli@3.0.0 prepare \
  --profile standard \
  --package-manager pnpm

联网机器可以提前准备离线依赖。准备过程校验 SHA-512、包名和版本，再原子写入完整性清单。目标机器从本地目录安装，任何阶段失败都应回滚，而不是留下“依赖成功、资源失败”或相反的半成品。

这也是我把它称为安装事务的原因。一次操作要么留下完整可查的结果，要么尽量恢复到开始之前。

doctor 与 verify 是这条链路的收尾

npx file-viewer-cli@3.0.0 doctor --json
npx file-viewer-cli@3.0.0 verify --json

doctor 给开发者看，检查依赖、生成入口、资源回执和文件漂移；verify 给 CI 用，遇到错误返回非零退出码。前者帮助定位，后者负责守住发布门槛。

本次发布的冻结验收覆盖 86 个发布 tarball、1 个支持 tarball和 64 份安装闭包报告，八种浏览器框架入口完成了实际页面检查。正式发布后，清单内 84 个 npm 条目都能读取各自版本和完整性字段；兼容包 msdoc-viewer 继续使用自己的 0.2.4。

从结果看，3.0.0 的变化不是把脚本集中到一个命令，而是给依赖选择、旧项目写入、运行时资源和离线交付建立了共同的证据格式。完整版本记录见 File Viewer 3.0.0 Release。