企业官网建设流程全解析

OHIF Mode 安装完全指南：使用 CLI 添加本地与 NPM 发布模式

【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers

OHIF v3 采用"模式（Mode）+ 扩展（Extension）"的模块化架构，允许开发者通过可插拔的模式为查看器注入自定义临床工作流。本文以 platform/docs/docs/platform/modes/installation.md 为核心，系统讲解 OHIF 模式的两种安装路径——本地模式链接与 NPM 发布模式的在线安装，并结合 CLI 源码剖析其底层校验、依赖解析与配置写入机制，帮助你快速为查看器接入新工作流。

OHIF-v3 的外部模式机制

OHIF-v3 架构重新设计的目标，是让应用能够针对各种用例（Modes）轻松扩展，并在后台利用所需的功能（Extensions）达成用例目标。也就是说，模式是查看器的"工作流外壳"，扩展是支撑模式的"功能模块"。

OHIF-v3 提供了使用外部模式的能力（见 installation.md）：

• 本地模式：尚未发布或处于开发阶段的模式，通过link-mode链接到查看器；
• NPM 发布的模式：已发布到 NPM registry 的公开模式，通过add-mode直接安装。

两条路径都通过随 OHIF monorepo 分发的cli工具完成。该工具由 platform/cli/src/index.js 实现，入口命令定义在根目录 package.json 中：

"cli": "node ./platform/cli/src/index.js"

注意：CLI 目前内置于 OHIF monorepo，需要通过yarn（或pnpm）调用。CLI 启动时会校验当前目录的package.json中name必须为ohif-monorepo-root，否则报错 "ohif-cli must run from the root of the OHIF platform" 并退出——因此所有 CLI 命令都必须在 monorepo 根目录执行（platform/cli/src/index.js）。

CLI 命令总览

运行yarn run cli --help可以查看全部可用命令：

yarn run cli --help

OHIF CLI Options: -V, --version output the version number -h, --help display help for command Commands: create-extension Create a new template extension create-mode Create a new template Mode add-extension <packageName> [version] Adds an ohif extension remove-extension <packageName> removes an ohif extension add-mode <packageName> [version] Removes an ohif mode remove-mode <packageName> Removes an ohif mode link-extension <packageDir> Links a local OHIF extension to the Viewer to be used for development unlink-extension <extensionName> Unlinks a local OHIF extension from the Viewer link-mode <packageDir> Links a local OHIF mode to the Viewer to be used for development unlink-mode <extensionName> Unlinks a local OHIF mode from the Viewer list List Added Extensions and Modes search [options] Search NPM for the list of Modes and Extensions help [command] display help for command

与模式（Mode）直接相关的命令是：create-mode、link-mode、unlink-mode、add-mode、remove-mode，以及用于查看与管理已装插件的list和search。

安装 NPM 发布的模式：add-mode

add-mode是安装公开 NPM 模式的核心命令。它会在 NPM registry 中查找指定包并安装，同时把模式依赖的扩展一并加入查看器。

yarn run cli add-mode <packageName> [version]

• 不指定version时，使用该包的dist-tags.latest最新版本；
• 支持^前缀的次版本匹配（见 validate.js 中getVersion的版本解析逻辑）；
• 若模式在peerDependencies中声明了依赖的 OHIF 扩展，CLI 会自动安装这些扩展。

安装前校验：ohif-mode 关键字

add-mode的第一步是对 NPM 包进行校验（addMode.js 调用validateMode）。校验规则来自 keywords.js：

const keywords = { MODE: 'ohif-mode', EXTENSION: 'ohif-extension', };

CLI 会拉取 NPM registry 中该包元数据，检查目标版本包的keywords数组是否包含ohif-mode（validate.js）。不满足条件的包会被拒绝并报错package xxx is not an ohif-mode；不存在的包则报package xxx not found。这意味着一个合格的 OHIF 模式包必须在 package.json 中声明"keywords": ["ohif-mode"]。

完整安装流程与配置写入

add-mode使用listr任务链依次执行（addMode.js）：

1. 搜索校验模式：validateMode(packageName, version)；
2. 安装 npm 包：installNPMPackage(packageName, version)；
3. 将模式写入配置文件：addModeToConfig(packageName, yarnInfo)；
4. 检测依赖扩展：findRequiredOhifExtensionsForMode(yarnInfo)，读取模式的peerDependencies；
5. 安装依赖扩展：若有扩展依赖，调用addExtensions(...)依次安装。

配置文件即platform/app/pluginConfig.json（注意：小写pluginConfig.json，CLI 的list命令也读取该路径，见 index.js）。写入逻辑由 manipulatePluginConfigFile.js 实现：addModeToConfigJson会先把同名条目从modes数组移除（幂等），再追加{ packageName, version }。

当前仓库的 platform/app/pluginConfig.json 中，modes数组已包含@ohif/mode-longitudinal、@ohif/mode-basic、@ohif/mode-segmentation、@ohif/mode-tmtv、@ohif/mode-microscopy、@ohif/mode-preclinical-4d、@ohif/mode-test、@ohif/mode-basic-dev-mode等，格式如下：

{ "modes": [ { "packageName": "@ohif/mode-longitudinal" }, { "packageName": "@ohif/mode-segmentation", "default": false, "version": "3.0.0" } ] }

实战示例：安装 @ohif-test/mode-clock

官方文档以@ohif-test/mode-clock为例演示add-mode：

yarn run cli add-mode @ohif-test/mode-clock

该模式的功能是提供一个显示时钟的面板。执行后 CLI 输出大致如下：

Adding ohif-mode @ohif-test/mode-clock... ✔ Searching for mode ✔ Installing npm package ✔ Adding ohif-mode to the configuration file ✔ Detecting required ohif-extensions... Added ohif-mode @ohif-test/mode-clock@3.1.0 Installing dependent extensions ✔ Added ohif-extension @ohif-test/extension-clock@3.1.0

由于@ohif-test/mode-clock在peerDependencies中声明了@ohif-test/extension-clock，CLI 自动将该扩展一并安装到查看器。安装完成后，查看器启动时便会出现Clock Mode这个新模式，与Basic Viewer并列供用户切换。

链接本地模式：link-mode / unlink-mode

对于开发中、尚未发布到 NPM的本地模式，使用link-mode将其链接到查看器。这在"创建模式模板 → 开发调试 → 最终发布"的迭代流程中至关重要。

yarn run cli link-mode <packageDir>

link-mode的底层实现（linkPackage.js）会：

1. 读取本地包package.json，校验keywords包含ohif-mode，否则报错${packageName} is not ohif-mode；
2. 校验 pnpm已安装（validatePnpm，因为当前 monorepo 使用 pnpm 作为包管理器）；
3. 切换到 OHIF Platform 根目录执行pnpm link <resolvedPackageDir> --config.frozen-lockfile=false（链接会改动 lockfile，因此需关闭 frozen-lockfile 校验）；
4. 更新 webpack 配置：将链接包的node_modules路径写入platform/app/.webpack/webpack.pwa.js的modules数组，保证 webpack 能找到链接包的外部依赖；
5. 将{ packageName, version }写入pluginConfig.json的modes数组；
6. 对 webpack 配置执行 prettier 格式化。

与之对应，unlink-mode <modeName>会将模式从查看器移除，并提示"don't forget to run pnpm install"（index.js）。

create-mode：模式模板的起点

yarn run cli create-mode

create-mode通过inquirer交互式提问创建模式模板（index.js 中的_createPackage），问题包含默认答案（显示在括号中，直接回车使用默认值）。部分提问涉及是否立即初始化 git 仓库（默认Y）。注意：create-mode只生成模板，要使用该模式必须先执行link-mode链接到查看器。

从仓库中的真实模式可以看到模式入口文件的标准形态，例如 modes/basic/src/index.tsx 导出id、routeName: 'basic'、displayName以及isValidMode等字段，并通过getHangingProtocolModule、getToolbarModule等接入查看器运行时。

卸载模式：remove-mode

yarn run cli remove-mode <packageName>

remove-mode的处理与add-mode对称（removeMode.js）：

1. 校验该模式已安装（validateModeYarnInfo，同样检查ohif-mode关键字）；
2. 卸载 npm 包（uninstallNPMPackage）；
3. 从pluginConfig.json的modes数组移除该条目；
4. 通过findOhifExtensionsToRemoveAfterRemovingMode检测：如果某扩展只被该模式依赖、不再被任何已安装模式使用，则一并移除这些扩展。

该机制保证了卸载模式后不会遗留"孤儿"扩展依赖。

管理已安装插件：list 与 search

list：列出查看器当前安装的所有扩展与模式，数据来自pluginConfig.json：

yarn run cli list

输出按 "Extensions" 和 "Modes" 分组，每项显示packageName @ version（listPlugins.js）。

search：在 NPM registry 中搜索 OHIF 扩展与模式：

yarn run cli search [--verbose]

CLI 通过 NPM 关键字接口分别按ohif-extension和ohif-mode检索（searchPlugins.js），默认显示包名、版本和描述；加--verbose（即-v）会额外显示仓库链接。

配置与环境的补充说明

pluginConfig.json：CLI 的配置中枢

pluginConfig.json是 CLI 所有增删命令的配置中枢，由 CLI 自动生成与维护，不需要也不应该手工编辑。它跟踪查看器当前使用的所有扩展、模式及其版本（见 ohif-cli.md）。除extensions、modes数组外，文件还包含public数组，用于声明需要由 webpack 静态拷贝的公共资源（如 platform/app/pluginConfig.json 中的dicom-microscopy-viewer动态导入路径）。

私有 NPM 仓库

若模式发布在私有 NPM 仓库，需要先创建一个只读 token 并导出为环境变量（CLI 在拉取 registry 元数据时会通过Authorization: Bearer <token>请求头携带它，见 validate.js）：

npm login npm token create --read-only export NPM_TOKEN=<your readonly token>

外部依赖处理

ohif-cli会把外部依赖的路径写入 webpack 配置（platform/app/.webpack/webpack.pwa.js），这样你可以在自己的项目里安装这些依赖，并在自定义扩展与模式中使用它们（ohif-cli.md）。

包管理器的适配

当前仓库使用pnpm作为工作区包管理器（见根目录 pnpm-workspace.yaml）。因此link-mode内部实际调用的是pnpm link，而非文档早期示例中的yarn link；相应地，CLI 会先执行validatePnpm校验环境。如果你在旧版 yarn-only 的 OHIF 版本上使用，命令行为会略有差异，请以你所用版本的实际实现为准。

总结：模式安装的完整工作流

结合源码与文档，OHIF 模式的典型生命周期如下：

无论走哪条路径，CLI 最终都会把模式的{ packageName, version }写入 platform/app/pluginConfig.json，这就是查看器启动时识别并加载模式的唯一依据。掌握add-mode与link-mode两条安装路径，你就能在本地开发与 NPM 分发两种场景下自由地为 OHIF 查看器接入自定义临床工作流。

【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers