File Viewer CLI

零安装运行时使用 npx file-viewer-cli@latest ...：这个单 bin 入口严格委托给同版本 @file-viewer/cli。项目已经安装 scoped 包后，直接使用本地 file-viewer 命令。

从这里开始

运行交互式脚手架：

npm create file-viewer@latest my-viewer
# 或
pnpm create file-viewer my-viewer

向导会依次展示框架、方案、File Viewer 发行版、已验证框架版本和可选格式，最后再统一确认。取消或选择不执行时不会修改项目。

需要在 CI 中稳定复现时，把所有选择写明：

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

--yes 是 create、add、install 的安装和写入确认。非交互模式没有它时只打印计划，不安装依赖，也不写文件。

选择框架和版本

交互式向导会列出当前 CLI 目录冻结的精确版本。CI 使用 --framework-version <精确版本>。Vite 与框架插件版本作为一套经过构建验证的模板选择，CLI 不会任意拼接未经验证的运行时组合。

选择方案

如果安装体积会影响交付，先看 Full 计划：

npx file-viewer-cli plan --framework react --profile full

计划会列出锁定版本、资源命令、重型能力、许可证声明和当前实测 Full 安装区间，不会用一个很小的顶层 tgz 数字掩盖完整依赖闭包。

选择格式与可选能力

创建或接入时可以直接写文件扩展名或能力 id：

npx file-viewer-cli create viewer \
  --framework react \
  --profile standard \
  --formats dwg,typst \
  --yes

先检查目录，再修改已经初始化的项目：

npx file-viewer-cli list
npx file-viewer-cli config add dwg --write
npx file-viewer-cli config add dicom --write
npx file-viewer-cli config add p7m --write
npx file-viewer-cli config remove dwg --write
npx file-viewer-cli plan
npx file-viewer-cli install --yes

standard 中的重型能力始终需要显式选择。生成模块只 import 固定 profile 与额外能力；运行时仍然只在打开对应格式后才加载 renderer。

所有已选能力都会注册到同一份 File Viewer 生成配置中。DICOM、签名容器、Office、PDF 等格式共用同一个组件、文件入口、生命周期和工具栏；CLI 不会再创建第二套预览页面或按格式分裂业务入口。

DICOM 边界

dicom 安装可选的本地 DICOM Part 10 renderer，只支持单个本地单帧或多帧文件，包含有界解码和帧切换。它不提供多文件序列组装、PACS/DICOMweb、MPR、分割、诊断解读，也不嵌入整套 OHIF 应用。

数字签名能力边界

p7m（或能力 id signature）安装可选的本地签名与证据容器 renderer。它在 Worker 中有界检查 CMS/CAdES、RFC 3161/5544 时间戳、ASiC-S/E、RFC 4998 证据记录、JWS 与公开 OpenPGP 材料。密码学验证结果与证书/密钥信任、合格签名身份、政策合规和法律效力分开呈现。私钥操作、自动解密、远程 jku/x5u 获取、完整 XAdES 和归档政策验证不在该能力声明内。

创建新项目

脚手架只在确认计划后写入一个小型 Vite 项目和 File Viewer 接入层。按框架不同，会生成：

• package.json、index.html、src/main.mjs；
• Svelte 所需的 src/App.svelte 与 vite.config.mjs；
• 持久记录选择的 file-viewer.config.json；
• 默认确定性 renderer 注册模块 file-viewer.generated.mjs；
• 业务入口中的一条生成模块 import 标记；
• 精确版本 File Viewer 依赖和所选静态资源。

只预览、不写入：

npx file-viewer-cli create ./viewer \
  --framework svelte \
  --framework-version <已验证版本> \
  --profile standard \
  --non-interactive \
  --json

只有审阅 dry-run 后才使用 --force。它允许替换冲突的 CLI 脚手架、配置和生成文件，不是任意重写业务文件的通行证。

接入已有项目

在 package.json 所在目录运行 add，或者用位置参数传目录：

cd existing-app
npx file-viewer-cli add

# 在其它目录执行同一操作
npx file-viewer-cli add ./existing-app

检查范围包括：

• 优先读取 packageManager，然后检查 lockfile；
• Vue、React、Svelte、jQuery 依赖及其声明的运行时版本线；
• 已安装的 standard / preset / Full File Viewer 方案；
• Vite、Vue CLI、Webpack、Next.js、Nuxt 2/3 构建配置；
• 可静态证明的 Vite publicDir、Nuxt dir.public / dir.static，以及 Vue CLI、Next.js 的约定静态目录；
• 已有 File Viewer 包与当前目录版本是否漂移；
• 可以自动加入生成模块 import 的应用入口。

检测到多个框架或多个已安装方案时会停止，要求显式传入 --framework 或 --profile。动态或禁用的静态目录、多份构建配置、通用 Webpack 输出和未知构建系统会生成明确的 manualSteps，并在安装和写文件前失败关闭；确认实际构建目标后可传入受项目边界约束的 --asset-target 继续。已有框架版本没有精确命中已验证模板时，CLI 会保留现有运行时并提示风险，不会静默改版本。

先检查检测结果和命令：

npx file-viewer-cli add . --profile standard --json

再应用同一选择：

npx file-viewer-cli add . --profile standard --yes --non-interactive
npx file-viewer-cli verify --json

找不到已支持的业务入口时，add 会在安装和写入前失败关闭。请显式传入 --entry <项目内客户端入口>；不要把浏览器接入代码注入仅用于 SSR 的入口。

配置与生成模块

默认 file-viewer.config.json 只包含项目相对路径，可以提交到版本库：

{
  "schemaVersion": 1,
  "framework": "vue3",
  "profile": "standard",
  "formats": ["dwg"],
  "capabilities": [],
  "assetTarget": "public/file-viewer",
  "generatedModule": "file-viewer.generated.mjs",
  "locale": "zh-CN"
}

也可以单独查看或生成模块：

npx file-viewer-cli generate
npx file-viewer-cli generate --write

应修改配置后重新生成，不要直接维护生成文件。除非明确使用 --force，CLI 不会覆盖用户自有文件。

安装失败恢复边界

确认执行 create/add/install 后，CLI 会在包管理器步骤前，把已有的项目内 node_modules 及 Yarn unplugged 目录原子移动到项目同级、同文件系统的备份区；同时保存 package.json、已有 lockfile、Yarn PnP/install-state、CLI 配置/生成模块和受管资产目录。包管理器或资产步骤正常抛错时会恢复这些字节。无法建立安全原子备份区时，CLI 会在调用包管理器前失败关闭。

进程或主机被强制中断不属于正常异常事务，项目同级可能留下 .<项目名>.file-viewer-install-*。再次执行前应先检查并恢复该备份，不能直接删除。包管理器 cache（包括项目内 Yarn cache）不会回滚。只有 managedPackages 明确记录为 CLI 所有的过期重型依赖才会被移除；未跟踪的依赖声明视为用户所有并保留。

资源命令与 copy-assets 兼容

已经配置的模块化项目只安装或修复所选资产所有者：

npx file-viewer-cli assets --write

原聚合命令、包名和 bin 完整保留：

npx --no-install file-viewer-copy-assets ./public/file-viewer

# 统一 CLI 中的等价入口
npx file-viewer-cli copy-assets ./public/file-viewer

没有项目配置、并传入旧目标/选项时，file-viewer assets 也保持旧 copy 行为；存在模块化配置时，它执行所选资产计划，不能把旧参数混进新计划。

复制过程写入 manifest 和 receipt，校验必需文件，拒绝路径越界和符号链接目标，不覆盖无所有者文件或被外部修改的受管资源。现有 Full 包命令继续委托给同版本实现。完整部署 @file-viewer/web-full/dist/ 已经包含自身资源，不需要再次复制。

私有 registry

远程 registry 必须使用 HTTPS；明文 HTTP 只允许显式的 127.0.0.1 等回环地址用于本地测试：

npx file-viewer-cli add . \
  --profile standard \
  --registry https://registry.example.com/ \
  --cache-dir .file-viewer/package-cache \
  --yes

CLI 不会为了获取缺失的 copy-assets 载荷而静默使用环境中的 registry。包含用户名或密码的 registry URL 会被拒绝。认证应放在包管理器的用户/CI 配置中，不要写入项目配置或命令历史。

--registry 只影响 npm 包获取。Worker、WASM、字体和 vendor 运行时资源仍然自托管；只有显式设置 --asset-base-url 时才会使用经过批准的其它源。

准备离线 tgz 目录

prepare 及别名 cache 会从显式 registry 下载精确的 File Viewer 自有依赖闭包，并发范围为 1-8。每个 tarball 都会校验为目录内普通文件，并核对 SHA-512、包名、版本和依赖元数据，最终以原子方式写入目录和 file-viewer-offline-manifest.json。完整性只能证明字节与准备清单一致，不能证明 registry 来源可信，因此必须使用受信任的软件源。

先预览：

npx file-viewer-cli prepare \
  --framework vue3 \
  --profile standard \
  --registry https://registry.npmjs.org/ \
  --offline-dir .file-viewer/offline

审阅后准备：

npx file-viewer-cli prepare \
  --framework vue3 \
  --profile standard \
  --registry https://registry.npmjs.org/ \
  --offline-dir .file-viewer/offline \
  --concurrency 4 \
  --yes

在目标环境使用经过校验的目录：

npx file-viewer-cli add . \
  --profile standard \
  --offline-dir .file-viewer/offline \
  --cache-dir .file-viewer/package-cache \
  --yes \
  --non-interactive

离线目录包含所选能力所需的 File Viewer 自有包闭包、必要兼容包，以及供 create-file-viewer 使用的精确 @file-viewer/cli。它不会顺带镜像无关框架包或业务项目的全部第三方依赖；真正断网安装仍需为这些依赖准备包管理器 cache。npm、pnpm、Yarn Classic 与 Yarn Berry 都会收到各自正确的离线约束；Bun 仍需预热 cache。

安装时 --registry 与 --offline-dir 互斥。只有根包选择、registry、文件名、版本和完整性哈希全部相同时，已有离线目录才会被复用。

帮助与语言

CLI 会尽量跟随系统语言，也支持显式指定四种帮助语言：

file-viewer --help --lang en
file-viewer --help --lang zh-CN
file-viewer --help --lang ja-JP
file-viewer --help --lang de-DE

file-viewer create --help --lang en
file-viewer add --help --lang zh-CN
file-viewer doctor --help --lang ja-JP

提示和可读计划标签会本地化；--json 始终使用稳定英文键，方便 CI 和工具解析。

命令

常用选项

CI 模式

把计划和修改分开：

# 可审阅，不写入
npx file-viewer-cli plan \
  --framework vue3 \
  --profile standard \
  --formats dwg \
  --json > file-viewer-plan.json

# 应用精确目录选择
npx file-viewer-cli add . \
  --framework vue3 \
  --profile standard \
  --formats dwg \
  --non-interactive \
  --yes

# 版本、入口 import、receipt、哈希或资产漂移时让 CI 失败
npx file-viewer-cli verify --json

JSON 计划保存 command 与 args 数组，而不是经过 shell 插值的字符串，自动化可以先审阅再执行，不需要求值用户可控 shell 文本。

常见问题

继续阅读：模块化方案、按需 renderer、发布与分发、格式事实。