Vortex 依赖报告解读:通过 nodeIntegration 泄漏给扩展的生产依赖清单与自动生成机制
Vortex 依赖报告解读:通过 nodeIntegration 泄漏给扩展的生产依赖清单与自动生成机制
本篇技术指南围绕 Vortex 仓库中的自动生成文档 etc/Dependency Report.md 展开,深入说明这份“泄漏清单”是什么、由谁生成、为何存在,以及它如何与 Electron 的 nodeIntegration 架构、扩展打包时的 external 策略和 pnpm workspace 版本管理相互印证。读完本文,你将掌握 Vortex 扩展可 require 的全部生产依赖(含版本与来源),并能独立复现该报告的生成命令。
报告的本质:扩展可导入模块的“白名单”
Vortex 采用 Electron 架构,渲染进程(renderer)以 nodeIntegration: true 启动,扩展(extension)被直接加载进渲染进程并导出为 CommonJS 模块,因此扩展代码中可以使用 require 导入 Node 模块——这一点在仓库的 docs/investigation/obsidian.md 中有明确记载:“Plugins are loaded directly into the renderer process on startup with no sandboxing or isolation. Furthermore, the renderer is spawned with nodeIntegration: true and plugins are exported to CJS. This allows plugins to use require and import node modules.”
etc/Dependency Report.md 正是对这一事实的工程化回应:它列出了 所有由 Vortex 主进程泄漏(leaked)给扩展的模块——只要出现在这份清单里,扩展就能借助 nodeIntegration 直接 require。文档开头的说明也直接声明了这一点:
This is a list of all modules leaked by Vortex to extensions. Any module listed here is importable by extensions thanks to nodeIntegration.
需要注意的是,报告文件头明确标注 “This file was auto-generated, don't edit it directly!”,这是一份机器生成的产物,人工直接修改会在下一次生成时被覆盖。
报告的生成机制:dependency-report.mjs
报告由仓库根目录 package.json 中名为 assets 的脚本触发:
"assets": "node ./scripts/dependency-report.mjs"
实际生成逻辑位于 scripts/dependency-report.mjs,核心只有几步:
- 调用 pnpm 列出主包的生产依赖:通过
pnpm -F @vortex/main list --prod --json获取@vortex/main(即 src/main/package.json 定义的主进程包)在--prod模式下的依赖树; - 解析 JSON 结果:pnpm list 会返回一组 workspace 包,脚本取第一个条目并读取其
dependencies对象; - 排序并生成 Markdown 表格:按包名
localeCompare升序排序,逐行输出| 包名 | 版本 |; - 写回报告文件:将生成的 Markdown 写入仓库根目录下的
etc/Dependency Report.md,并在控制台打印写入的依赖数量。
const { stdout: raw } = await execAsync("pnpm -F @vortex/main list --prod --json");
const [{ dependencies = {} }] = JSON.parse(raw);
const rows = Object.entries(dependencies)
.sort(([a], [b]) => a.localeCompare(b))
.map(([depName, { version: depVersion }]) => `| ${depName} | ${depVersion} |`)
.join("\n");
@vortex/main 的依赖声明位于 src/main/package.json,报告中出现的每一个包名都对应其中的 dependencies 字段。因此这份报告的本质,就是主进程生产依赖清单的自动化快照——凡是被 @vortex/main 声明为生产依赖的包,都会进入扩展可导入的集合。这也是为什么报告需要自动生成:任何依赖的新增或升级,都会直接改变扩展可见的模块面,人工维护极易遗漏。
从仓库结构上看,docs/repo-layout.md 将 etc/ 目录描述为“Generated API report (vortex.api.md) and dependency report”,即 etc/ 专门存放自动生成的产物,这份依赖报告与 API 报告地位相同。
完整依赖清单(截至当前仓库快照)
下表完整继承报告正文,共 129 项直接生产依赖,按包名排序;link: 前缀表示该条目不是外部 npm 版本,而是指向仓库内 workspace 包的相对路径。
| Package | Version |
|---|---|
| @duckdb/node-api | 1.5.1-r.1 |
| @electron/remote | 2.1.3 |
| @floating-ui/react | 0.27.20 |
| @headlessui/react | 2.2.10 |
| @hot-updater/bsdiff | 0.30.6 |
| @mdi/js | 7.4.47 |
| @msgpack/msgpack | 2.8.0 |
| @nexusmods/file-dependency-resolver | link:../../packages/file-dependency-resolver |
| @nexusmods/fomod-installer-ipc | 0.13.4 |
| @nexusmods/fomod-installer-native | 0.13.4 |
| @nexusmods/nexus-api | 1.7.3 |
| @nosferatu500/react-sortable-tree | 4.4.0 |
| @nosferatu500/theme-file-explorer | 3.0.21 |
| @opentelemetry/api | 1.9.1 |
| @opentelemetry/context-async-hooks | 2.8.0 |
| @opentelemetry/context-zone | 2.8.0 |
| @opentelemetry/exporter-trace-otlp-http | 0.219.0 |
| @opentelemetry/resources | 2.8.0 |
| @opentelemetry/sdk-trace-base | 2.8.0 |
| @opentelemetry/semantic-conventions | 1.40.0 |
| @tailwindcss/cli | 4.3.2 |
| @tanstack/react-virtual | 3.13.23 |
| @types/bluebird | 3.5.20 |
| @types/uuid | 3.4.13 |
| @vortex/nexus-api-v3 | link:../../packages/nexus-api-v3 |
| @vortex/shared | link:../shared |
| bbcode-to-react | 0.2.11 |
| big.js | 5.2.2 |
| bluebird | 3.7.2 |
| bootstrap-sass | 3.4.3 |
| classnames | 2.5.1 |
| commander | 4.1.1 |
| content-disposition | 0.5.4 |
| content-type | 1.0.5 |
| crc-32 | 1.2.2 |
| cytoscape | 3.33.1 |
| cytoscape-cose-bilkent | 4.1.0 |
| cytoscape-edgehandles | 3.6.0 |
| d3 | 5.16.0 |
| dayjs | 1.11.20 |
| dequal | 2.0.3 |
| dnd-core | 9.5.1 |
| draggabilly | 2.4.1 |
| drivelist | 10.0.2 |
| electron-context-menu | 3.6.1 |
| electron-redux | 1.4.9-sync |
| electron-updater | 6.8.9 |
| encoding-down | 6.3.0 |
| exe-version | link:../../packages/exe-version |
| feedparser | 2.3.0 |
| fs-extra | 9.1.0 |
| fuzzball | 1.4.0 |
| glob | 11.1.0 |
| got | 15.0.5 |
| graphlib | 2.1.8 |
| i18next | 21.10.0 |
| i18next-fs-backend | 2.6.1 |
| icon-extract | link:../../packages/icon-extract |
| iconv-lite | 0.5.2 |
| immutability-helper | 3.1.1 |
| ini | 6.0.0 |
| interweave | 12.9.0 |
| is-admin | 3.0.0 |
| js-yaml | 4.1.1 |
| json-socket | 0.3.0 |
| jsonwebtoken | 9.0.3 |
| leveldown | 5.6.0 |
| levelup | 4.4.0 |
| limiter | 3.0.0 |
| lodash | 4.17.23 |
| markdown-ast | 0.2.1 |
| memoize-one | 5.2.1 |
| minimatch | 3.1.5 |
| mixpanel-browser | 2.79.0 |
| modmeta-db | 0.9.3 |
| node-7z | 0.8.1 |
| normalize-url | 6.1.0 |
| numeral | 2.0.6 |
| openapi-fetch | 0.17.0 |
| p-limit | 7.3.0 |
| p-queue | 9.3.0 |
| packery | 2.1.2 |
| permissions | 2.1.0 |
| prop-types | 15.8.1 |
| ps-list | 7.2.0 |
| re-reselect | 4.0.1 |
| re-resizable | 6.11.2 |
| react | 18.3.1 |
| react-bootstrap | 0.33.1 |
| react-datepicker | 3.8.0 |
| react-dnd | 14.0.5 |
| react-dnd-html5-backend | 14.1.0 |
| react-dom | 18.3.1 |
| react-hot-toast | 2.6.0 |
| react-i18next | 11.18.6 |
| react-markdown | 6.0.3 |
| react-overlays | 1.2.0 |
| react-redux | 7.2.9 |
| react-select | 1.3.0 |
| recharts | 2.15.4 |
| redux | 4.2.1 |
| redux-act | 1.8.0 |
| redux-batched-actions | 0.5.0 |
| redux-thunk | 2.4.2 |
| relaxed-json | 1.0.3 |
| reselect | 4.1.8 |
| resolve | 1.22.11 |
| rimraf | 2.6.2 |
| sass | 1.101.0 |
| semver | 7.7.4 |
| shortid | 2.2.17 |
| simple-vdf | 1.1.3 |
| source-map-support | 0.5.21 |
| string-template | 1.0.0 |
| tailwindcss | 4.3.2 |
| temporal-polyfill | 1.0.4 |
| tmp | 0.1.0 |
| tough-cookie | 6.0.1 |
| turbowalk | 3.1.1 |
| universal-analytics | 0.4.23 |
| uuid | 3.4.0 |
| vortex-parse-ini | 0.4.0 |
| wholocks | 1.1.0 |
| winapi-bindings | 2.7.3 |
| winston | 2.4.7 |
| write-file-atomic | 3.0.3 |
| ws | 7.5.10 |
| xml2js | 0.5.0 |
| xxhash-addon | 2.1.0 |
| zod | 4.4.3 |
从清单看架构:这份依赖为什么会“泄漏”
报告的存在与 Vortex 的窗口与安全配置直接相关,可以从三处源码得到印证。
主窗口开启 nodeIntegration。 src/main/src/MainWindow.ts 中主窗口 webPreferences 明确设置了 nodeIntegration: true(注释说明这是为 @electron/remote 兼容所必需),同时 contextIsolation: false。这意味着渲染进程内的扩展代码拥有完整的 Node 能力,可以 require 主进程可解析的任意模块——清单中的包因此对扩展“可见”。
内嵌 webview 与 BrowserView 则被严格降权。 与主窗口形成对照,src/main/src/Application.ts 中的 attachWebView 处理函数会删除 preload / preloadURL 并将 nodeIntegration 强制设为 false,注释写明“disallow creation of insecure webviews”;src/main/src/ipcHandlers.ts 创建的 WebContentsView 也显式配置 nodeIntegration: false、contextIsolation: true 与 sandbox: true。也就是说,只有在主渲染进程中运行的扩展才享有这份依赖清单的访问权,任何次级 web 内容都不在泄漏范围内。
Renderer 构建也为此做了配合。 src/renderer/webpack.config.cjs 的注释“disable polyfills for browser because nodeIntegration is enabled”说明 webpack 构建时因 nodeIntegration 开启而关闭了浏览器端 polyfill;src/renderer/eslint.config.mjs 中则有“TODO: remove Node globals after disabling nodeIntegration”的待办标记,反向印证当前构建仍以 Node 全局可用为前提。
与扩展打包的关系:external 白名单来自同一份依赖
报告清单并非只用于文档展示,它还直接参与扩展的打包决策。仓库内扩展通过 scripts/extensions-rolldown.mjs 提供的共享 Rolldown 配置进行打包,其中 getExternals() 函数会:
- 读取
src/main/package.json; - 取全部
dependencies的键名; - 再加上
electron、vortex-api、@nexusmods/vortex-api等注入模块与 Node 内置模块(builtinModules); - 为每个 id 生成
^id(?:$|/)形式的正则,同时匹配包本身及其子路径(例如react与react/jsx-runtime)。
const externalIds = [
...new Set([
...builtinModules.filter((m) => !m.startsWith("_")),
...Object.keys(packageJson.dependencies),
...injectedExternals,
]),
];
return externalIds.map((id) => new RegExp(`^${escapeRegExp(id)}(?:$|/)`));
这意味着:扩展在构建时不会把清单中的这些包打包进自身产物,而是保持 external,在运行时从 Vortex 宿主环境解析——与报告“这些模块可由扩展导入”的声明完全闭环。报告是“扩展能 require 什么”的静态文档,而 getExternals() 是“扩展打包时不内联什么”的构建期实现,两者共享同一个数据源(src/main/package.json 的 dependencies)。
此外 nativeRemapPlugin(mappings) 会把指定的原生模块导入重写到运行时路径并标记为 external,进一步说明像 xxhash-addon、winapi-bindings、drivelist 这类带原生二进制的模块在扩展侧只做间接引用,实际加载仍由 Vortex 主进程负责。
版本来源:pnpm workspace catalog 的统一管理
报告中每个外部包的具体版本号并非散落在各处,而是由仓库根目录的 pnpm-workspace.yaml 中的 catalog 字段统一钉定。例如 react: 18.3.1、@duckdb/node-api: 1.5.1-r.1、@opentelemetry/exporter-trace-otlp-http: 0.219.0 等都可在 catalog 中一一对应;src/main/package.json 中则统一写作 "catalog:" 或 "workspace:*",由 pnpm 解析为实际版本。
报告中的三条 link: 条目也由此得到解释:
| 报告中的条目 | workspace 位置 | 说明 |
|---|---|---|
@nexusmods/file-dependency-resolver → link:../../packages/file-dependency-resolver |
packages/file-dependency-resolver | 文件级依赖解析器,支撑健康检查 |
@vortex/nexus-api-v3 → link:../../packages/nexus-api-v3 |
packages/nexus-api-v3 | Nexus Mods OpenAPI v3 的强类型 HTTP 客户端 |
@vortex/shared → link:../shared |
src/shared/package.json | 跨进程共享 API、类型与工具 |
exe-version → link:../../packages/exe-version |
packages/exe-version | 读取 Windows 可执行文件版本信息 |
icon-extract → link:../../packages/icon-extract |
packages/icon-extract | 从可执行文件提取图标 |
这些 link: 指向的 workspace 包同样被 @vortex/main 声明为依赖,因此也会作为可解析模块出现在扩展的导入范围内。值得注意的是,报告只覆盖 @vortex/main 的 dependencies,而不包括 devDependencies(如 electron、electron-builder 等构建期工具)——这也解释了为什么报告中看不到 electron 本身。
如何自行复现与使用这份报告
报告是生成产物,任何开发者在本地都可以一键复现:
# 先按仓库要求安装依赖(会触发 preinstall 钩子生成 .local.env)
pnpm install
# 重新生成 etc/Dependency Report.md
pnpm run assets
也可以直接执行生成脚本本身,等价于 pnpm run assets:
node scripts/dependency-report.mjs
对于扩展开发者,这份报告的实战价值非常直接:
- 判断某个包能否在扩展代码里直接
require:查阅表格即可。清单内的包无需自行打包或声明为扩展自己的依赖;清单之外的包要么属于构建期工具,要么需要显式引入到扩展自己的依赖中。 - 避免重复打包:结合 scripts/extensions-rolldown.mjs 的 external 规则,扩展构建产物应保持这些包为 external,减少体积并防止同一模块出现多份实例(例如多份 React 副本导致 hooks 状态错乱)。
- 关注版本变更:
@vortex/main依赖升级会同步反映到报告与 external 规则中,扩展依赖某个清单包的 API 时,应以报告中的版本为准进行兼容性评估。
总结
etc/Dependency Report.md 是 Vortex 工程体系中一份小巧但关键的自述文档:它以 pnpm -F @vortex/main list --prod --json 为数据源、由 scripts/dependency-report.mjs 自动生成,精确刻画了“在 nodeIntegration: true 的渲染进程架构下,扩展可以直接导入的全部生产依赖”这一安全与兼容性边界;同时它与 scripts/extensions-rolldown.mjs 的 external 打包策略、pnpm-workspace.yaml 的版本 catalog 形成三位一体的依赖治理闭环。理解这份报告,就理解了 Vortex 扩展模块解析的完整图景。