Vortex 依赖报告解读:通过 nodeIntegration 泄漏给扩展的生产依赖清单与自动生成机制

原创2026-10-13 13:47:481,435 阅读
文章标签:桌面应用游戏开发前端插件系统

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,核心只有几步:

  1. 调用 pnpm 列出主包的生产依赖:通过 pnpm -F @vortex/main list --prod --json 获取 @vortex/main(即 src/main/package.json 定义的主进程包)在 --prod 模式下的依赖树;
  2. 解析 JSON 结果:pnpm list 会返回一组 workspace 包,脚本取第一个条目并读取其 dependencies 对象;
  3. 排序并生成 Markdown 表格:按包名 localeCompare 升序排序,逐行输出 | 包名 | 版本 |;
  4. 写回报告文件:将生成的 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() 函数会:

  1. 读取 src/main/package.json;
  2. 取全部 dependencies 的键名;
  3. 再加上 electron、vortex-api、@nexusmods/vortex-api 等注入模块与 Node 内置模块(builtinModules);
  4. 为每个 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 扩展模块解析的完整图景。

登录后查看全文
Vortex