企业官网建设流程全解析

OHIF Viewer 3.13 升级指南：Node.js 运行时从 18 提升到 24 的完整迁移说明

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

导读

OHIF Viewer（OHIF zero-footprint DICOM viewer）在 3.13 版本将最低支持的 Node.js 运行时从 18 直接提升到24，并同步将包管理器收敛为 pnpm（engines.pnpm 11.1.1）。本文以官方迁移文档《Node.js 24 Requirement》为核心骨架，结合当前仓库中的真实配置文件与源码，完整讲解 Node 24 升级的原因、受影响的文件清单、本地环境与 CI 的运行器配置、升级后值得注意的行为变化，以及无法立即升级时的兼容窗口，帮助你随 3.13 一起规划一次平滑的运行时升级。

Node 24 升级概览：.node-version与engines字段同步变更

OHIF 3.13 将最低支持的 Node.js 运行时从 18 提升到24。仓库根目录的.node-version文件与每个 workspace 包的engines.node字段都进行了同步更新：

- .node-version 20.9.0 + .node-version 24

"engines": { - "node": ">=18", - "npm": ">=6", - "yarn": ">=1.20.0" + "node": ">=24", + "pnpm": "11.1.1" }

npm和yarn的engines字段被移除，因为仓库不再支持这两者作为安装路径——具体的迁移说明见 Package Manager guide（Yarn + Lerna 迁移到 pnpm workspaces）。

从当前仓库源码看，这些变更已实际落地：

• 根目录 .node-version 当前内容为24.15.0（官方文档示例写作24，仓库实际 pin 到了具体的 24.x 补丁版本）；
• 根目录 package.json 声明了"packageManager": "pnpm@11.5.2"，并设置了"engines": { "node": ">=24", "pnpm": ">=11" }；
• 应用入口 platform/app/package.json 同样声明了"engines": { "node": ">=24" }。

为什么是 Node 24

官方迁移文档给出了四条技术原因，这些原因与当前仓库的构建链路和依赖可以一一对上：

1. Rspack v2 需要较新的 V8 构建：Node 24 内置的 V8 是 12.x，这是 SWC 压缩器正常工作、避免回退到 Babel transform 的前提。当前仓库的 platform/app/package.json 中，生产构建脚本已是rspack build --config .webpack/webpack.pwa.js，devDependencies 中引入了@rspack/cli、@rspack/core、@rspack/dev-server等^2.0.0系列包。

2. pnpm 11 的shamefullyHoist+ workspace 符号链接布局：依赖 Node 20.10+ 的fs.symlink语义；Node 24 是当前 LTS 主线，也是 CI 所固定的版本。仓库根目录 pnpm-workspace.yaml 中配置了nodeLinker: hoisted（与文档描述的shamefullyHoist对应），并注释说明"镜像 cornerstone3D 的 pnpm 设置（已知可工作）"。

3. Cornerstone3D 编解码器使用了 top-levelawait和 Node 22+ 引入的现代Uint8Array/Buffer互操作。查看 platform/app/package.json 可以发现仓库依赖@cornerstonejs/codec-charls、@cornerstonejs/codec-libjpeg-turbo-8bit、@cornerstonejs/codec-openjpeg、@cornerstonejs/codec-openjph等 DICOM 图像编解码器，它们的运行要求直接决定了 Node 版本底线。

4. 生产构建脚本中的 24 GB--max-old-space-size设置：受益于 Node 24 对大堆 GC 的改进。这一条在 platform/app/package.json 中有直接证据："build": "cross-env NODE_OPTIONS=--max-old-space-size=24576 rspack build --config .webpack/webpack.pwa.js"，其中 24576 MB 恰好等于 24 GB；dev:fast脚本则使用了 16 GB（--max-old-space-size=16384）。

受影响的文件清单

官方文档列出，本次升级同步更新了以下文件：

• .node-version—— 固定为24（当前仓库实际为24.15.0）；
• 根目录package.json——engines.node >=24、engines.pnpm 11.1.1；
• 每个 workspace 包的engines.node字段，包括platform/app、platform/core、platform/ui、platform/ui-next、platform/i18n、platform/cli、全部extensions/*包和全部modes/*包；
• CLI 模板：platform/cli/templates/extension/dependencies.json与platform/cli/templates/mode/dependencies.json——由 CLI 生成的扩展和模式现在要求 Node 24 与 pnpm 11.1.1；
• CI 配置：.github/workflows/*、.circleci/config.yml、.netlify/build-deploy-preview.sh同步升级。

仓库中可验证的证据包括：

• platform/cli/templates/extension/dependencies.json 的engines已是{ "node": ">=24", "pnpm": ">=11" }，脚本也改为pnpm run dev/pnpm run build/pnpm run start；
• platform/cli/templates/mode/dependencies.json 同样为node >=24、pnpm >=11；
• CI 工作流 .github/workflows/playwright.yml 中matrix.node-version: [24.15.0]，并使用actions/setup-node安装；docs 构建工作流.github/workflows/build-docs.yml同样使用node-version: 24.15.0；
• CircleCI 配置 .circleci/config.yml 使用cimg/node:24.15.0镜像；
• Netlify 预览脚本 .netlify/build-deploy-preview.sh 通过pnpm run build:ci执行构建，并在脚本中打印pnpm -v与node -v便于核对版本。

注意：当前仓库根目录package.json的packageManager字段写的是pnpm@11.5.2，而迁移文档示例为11.1.1。如果使用 Corepack，进入仓库执行任意 pnpm 命令时会自动读取并切换到该字段指定的版本。

本地环境升级：Node 版本管理器配置

如果你使用 Node 版本管理器，官方文档给出如下命令：

# nvm nvm install 24 nvm use 24 # fnm fnm install 24 fnm use 24 # volta volta install node@24

.node-version文件会被fnm、nodenv、asdf以及（开启engines-strict设置后的）pnpm识别。大多数带 Node 工具栏的编辑器在cd进入仓库时会自动切换到对应版本。

需要说明的是：仓库当前的.node-version内容为24.15.0（一个精确补丁版本），而文档 diff 示例写作24。二者都是合法写法——精确版本能保证本地与 CI 完全一致，而只写大版本号则允许工具链选择最新的 24.x。你可以根据团队的确定性需求选择其中一种。

CI 运行器升级：构建镜像与流水线配置

官方文档要求更新你的流水线镜像：

- node-version: '20.9.0' + node-version: '24'

三类主流 CI 的具体配置方式：

当前仓库的实际配置比文档示例更进一步——全部 pin 到了24.15.0：

• GitHub Actions 的 Playwright 测试工作流 .github/workflows/playwright.yml 中matrix.node-version: [24.15.0]，随后通过corepack enable && corepack prepare --activate启用 pnpm（工作流注释说明了为何在自托管 runner 上不采用pnpm/action-setup：其自安装器会调用 runner 内置的 npm CLI，而该路径在自托管机上已损坏，Corepack 则直接基于 Node 自身的 https 下载 pnpm，完全不经过 npm CLI）；
• CircleCI .circleci/config.yml 使用cimg/node:24.15.0；
• 生产镜像 Dockerfile 的第一阶段使用FROM node:24.15.0-slim as builder，并在其中执行npm install -g pnpm@11，随后pnpm install --no-frozen-lockfile（注释解释了为何此处不能使用--frozen-lockfile：.dockerignore排除了platform/docs，锁文件中 docs importer 在构建上下文里缺少对应 manifest，frozen 安装会失败，pnpm 会自动 reconcile 掉 docs 部分）。

值得注意的行为变化

升级到 Node 24 后，有四个行为变化需要提前了解：

1. punycode弃用警告：Node 24 在 require 内置punycode时会打印弃用警告。部分传递依赖仍会触发它，警告无害但噪音较大。如果需要在 CI 中静默，可设置NODE_OPTIONS=--no-deprecation。

2. OpenSSL 提供者：Node 24 使用 OpenSSL 3.x。如果你之前为了兼容旧 Webpack 哈希而设置了NODE_OPTIONS=--openssl-legacy-provider，请移除它——Rspack 不需要该选项。当前仓库构建链路已全面切换到 Rspack（见 platform/app/package.json），不再有 webpack 哈希兼容问题。

3. fetch成为全局对象：Node 24 内置 WHATWGfetch。在 Node 环境下运行的脚本不再需要node-fetch之类的 polyfill。

4. ESM 解析更严格：在"type": "module"包中的.js文件里，相对导入必须包含文件扩展名。这主要影响 tests/utils 下的测试辅助代码。

兼容窗口：无法立即升级时的应对方案

如果暂时无法迁移到 Node 24，官方文档指出：platform/app/package.json中的build:webpack回退方案可以在 Node 22 下运行，但生产环境支持不被保证，且 Rspack 相关脚本会拒绝执行。从当前仓库源码看，platform/app/package.json 的构建入口已完全收敛到rspack build（生产）与rsbuild dev（开发，配置见根目录 rsbuild.config.ts），因此官方建议将运行时升级与 3.13 部署放在一起规划，而不是长期依赖回退路径。

迁移清单总结

结合官方文档与仓库现状，升级到 OHIF 3.13 的 Node 24 迁移可以按以下步骤执行：

1. 本地通过nvm/fnm/volta安装 Node 24（仓库.node-version指定24.15.0），并确保pnpm >= 11（根package.json的packageManager为pnpm@11.5.2，Corepack 会自动匹配）；
2. 将 CI 流水线镜像更新为 Node 24：GitHub Actionsnode-version: '24.15.0'、CircleCIcimg/node:24.15.0、Docker 基础镜像node:24.15.0-slim；
3. 清理旧的NODE_OPTIONS=--openssl-legacy-provider设置，如遇punycode弃用警告可设置NODE_OPTIONS=--no-deprecation静默；
4. 检查"type": "module"包中的.js相对导入是否补齐了文件扩展名；
5. 若通过 CLI 生成新扩展或新模式，确认模板产物使用 pnpm 脚本与engines.node >= 24（模板已更新，见 platform/cli/templates/extension/dependencies.json 与 platform/cli/templates/mode/dependencies.json）；
6. 参考 Package Manager guide 完成 yarn/lerna 到 pnpm 的命令切换，并在 fork 仓库中删除yarn.lock、node_modules后重新以pnpm install --frozen-lockfile安装。

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