Motrix 的 Electron + Vite 多目标构建体系：产物矩阵、preload 加载策略与原生 ABI 边界

Motrix（仓库中包名为 motrix-turbo）用一套 Vite 多配置体系同时产出 Electron 桌面端、Node 服务器与浏览器 Web 端三种形态，并通过构建规则文档 electron-vite.md 固化了产物命名、模块格式与原生 ABI 的边界约束。本文以该规则文档为骨架，逐条结合仓库中的 Vite 配置、脚本与源码实现，说明 Motrix 如何保证每个 build:* 流程都能打包出它真正需要的产物，以及 Electron 运行时如何安全地加载 preload 与 renderer。

一、多目标构建产物矩阵

规则文档给出的第一个硬性要求是一张"必需产物表"：每个构建目标必须落到固定路径与固定扩展名上。

构建目标	输出产物
Electron 主进程	dist/main/index.cjs
preload	dist/preload/preload.cjs
QuickJS 插件宿主 worker	dist/core/plugin/host/quick-js-worker.cjs
Electron renderer	dist/renderer/
Node 服务器与 CLI	dist/server/index.mjs、dist/server/motrix-admin.mjs
浏览器 renderer	dist/renderer-web/

这张表不是文档作者的主观约定，而是与六个 Vite 配置一一对应的实现事实：

• vite.main.config.ts 中 outDir: 'dist/main'，lib.formats: ['cjs']，fileName: () => 'index.cjs'，入口为 src/main/index.ts（第 54-67 行）；
• vite.preload.config.ts 产出 dist/preload/preload.cjs，同样是 CJS 单文件；
• vite.worker.config.ts 把 src/core/plugin/host/quick-js-worker.ts 编译为 dist/core/plugin/host/quick-js-worker.cjs；
• vite.renderer.config.ts 产出 dist/renderer/；
• vite.server.config.ts 是双入口构建：entry: { index: 'src/server/index.ts', 'motrix-admin': 'src/server/operator-cli.ts' }，formats: ['es'] 且 entryFileNames: '[name].mjs'，因此服务器同时得到 index.mjs 与 motrix-admin.mjs 两个产物（第 32-45 行）；
• vite.renderer.web.config.ts 产出 dist/renderer-web/，供纯 Web 部署使用。

package.json 的 build:electron 脚本把这条链路串起来：先执行 build:builtin（拉取内置引擎）与 build:legal（生成第三方声明），再依次以 vite build --config ... 构建 main、preload、worker、renderer 四个目标；build:server 则构建 server、worker 与 renderer-web。文档要求的"每个消费 build:* 的流程必须产出它打包所需的全部条目"，正是由这些脚本顺序保证的。

共享输出目录下的基名唯一性

文档中另一条约束是：共享同一输出目录的构建条目必须有唯一基名。在 server 构建中这一点尤为关键——dist/server/ 同时容纳 index.mjs 与 motrix-admin.mjs 两个入口产物，vite.server.config.ts 通过 entryFileNames: '[name].mjs' 以入口名区分二者。若两个入口意外产出同名文件，后构建者会覆盖先构建者，而这类错误在打包阶段未必立即暴露。

二、为什么 "type": "module" 下仍坚持 CJS 输出

package.json 声明了 "type": "module"，这决定了裸扩展名文件的默认解析规则：.js 按 ESM 解析、.cjs 按 CommonJS 解析、.mjs 按 ESM 解析。文档因此规定：main、preload、worker 三个产物必须保持 .cjs，服务器产物保持 .mjs，且包 main 字段必须与主进程产物一致。仓库中可以看到 main 字段恰好指向 dist/main/index.cjs（package.json 第 15 行）。

从源码结构看，main 与 preload 的 CJS 输出还服务于 Electron 的模块加载环境：Electron 主进程与 preload 运行在 Node 上下文里，而 renderer 端则完全走浏览器打包。vite.main.config.ts 中有一段注释解释了外部化策略——Node 22.12+ 的 require(ESM) 已稳定（Electron 41 捆绑 Node 22.14+），因此"声明了 type: module"本身不再是必须打包的理由；只有两类包才会进入 BUNDLED_PACKAGES（第 38 行）被强制打包进 CJS 输出：

1. exports 映射只暴露 import 条件的包（如 bittorrent-peerid、parse-torrent），require() 的解析器在加载前就会抛出 ERR_PACKAGE_PATH_NOT_EXPORTED，只能靠构建期按 import 条件解析；
2. 其传递依赖会被 electron-builder 26 的依赖遍历器从 asar 中丢掉的包（典型如 pino），打包可让所有传递依赖在构建期进入输出。

这段逻辑解释了产物格式选择的工程动机：不是"习惯用 CJS"，而是 asar 打包器与 ESM 条件导出的组合下，CJS 单文件输出是主进程最可靠的形态。

三、preload 路径与 renderer URL 安全策略

文档指出：运行时 __dirname 位于 dist/main/，因此 preload 的加载路径为：

path.join(__dirname, '../preload/preload.cjs')

这与 src/main/index.ts 中的实际代码完全一致（preloadPath: path.join(__dirname, '../preload/preload.cjs')）。由于 main 与 preload 是两个独立的 Vite 构建目标、分别输出到 dist/main/ 与 dist/preload/，重命名或移动任何一个产物都必须同步更新该相对路径，这也是文档将二者列为强耦合约束的原因。

rendererUrlPolicy：唯一合法的窗口加载入口

文档要求：VITE_DEV_SERVER_URL 只向 initializeRendererUrlPolicy() 传入一次，之后所有 renderer 窗口都必须经由 rendererUrlPolicy.loadWindow(win, route) 加载；不得添加任何绕过 loopback-origin 检查与 packaged-file 检查的功能局部 loadURL()/loadFile() 调用。

实现位于 src/main/window/renderer-url-policy.ts，其设计要点：

• 一次性初始化：initializeRendererUrlPolicy()（第 113-121 行）维护一个模块级单例，重复初始化会直接抛错，保证策略参数（isPackaged、appPath、devServerUrl）在整个进程生命周期内一致；
• loopback 白名单：parseDevServerOrigin()（第 22-47 行）要求 dev server URL 必须是 http/https 协议、主机名属于 {localhost, 127.0.0.1, [::1]}、且仅含 origin（无用户名/密码、无路径/查询/哈希）；
• 打包态禁用 dev server：devServer 的成立条件是 !options.isPackaged && options.devServerUrl（第 73-76 行）——打包后的应用绝不允许把继承来的环境变量变成可执行的 renderer 内容；
• 可信 URL 判定：isTrustedUrl()（第 83-99 行）在开发态只接受精确等于 devServer origin 的 URL，在打包态只接受指向 dist/renderer/index.html 对应 file: URL 的精确路径；
• 统一加载出口：loadWindow(win, route)（第 100-107 行）开发态调用 win.loadURL(${devServerOrigin}/${search})，打包态调用 win.loadFile(rendererFilePath, { search })；route 解析被限制为"只含查询串"的格式。

这种"策略对象 + 冻结返回值 + 单例"的结构，使安全边界集中于一处，任何新增窗口（设置页、配对对话框等）都只能复用同一出口，无法各自为政地引入未校验的加载源。

四、pnpm 11 下的安装脚本治理

pnpm-workspace.yaml 是本节所有约束的载体，文档对应要求是：项目 pnpm 设置必须放在该文件中，并保持 nodeLinker: hoisted。

hoisted 链接器是打包工具链的硬性前提

文件第 5-9 行注释明确写道：pnpm 11 从该文件而非 .npmrc 读取项目设置，nodeLinker: hoisted（扁平 node_modules 布局）是 electron-builder 与原生模块重建工具链所要求的。这与 vite.main.config.ts 中"electron-builder 26 的 Go 依赖遍历器无法跟随 pnpm 布局的依赖树"的注释互为印证。文档因此要求：除非 Electron 打包 smoke 任务证明 isolated linking 可行，否则不得改动该设置——smoke:electron-package 脚本（package.json 第 25 行）正是承担这一验证职责的流程。

allowBuilds：安装脚本的门禁

pnpm 11 用 allowBuilds 取代了旧版 onlyBuiltDependencies：未列出的包，其安装脚本会被跳过。pnpm-workspace.yaml 中的白名单为：

包	保留原因（据文件内注释）
electron	兼容仍暴露安装脚本的版本发布
better-sqlite3	需针对固定 ABI 重建的原生模块
electron-winstaller / esbuild	无害的架构选择脚本，允许后安装不产生警告

为什么不能依赖 pnpm install 拉取 Electron 43

文档特别强调：electron 保持在 allowBuilds 中仅为兼容，但不要指望 pnpm install 来水合（hydrate）Electron 43——该版本把 install.js 暴露为包 bin，却没有 postinstall 脚本，安装期不会自动下载二进制。仓库中所有消费 Electron 或其许可证的本地工作流，都先经过 ensure:electron-runtime（即 scripts/ensure-electron-runtime.mjs）：它会校验完整 payload 并安全地修复不完整安装。这一点在 package.json 的脚本中随处可见：prestart、build:electron（经由 build:legal）、smoke:electron-package、check:registry-runtime、check:third-party-notices 均先执行该命令。而 CI/容器流程若紧接着就校验结果，可以直接调用 install.js。

五、原生模块的 ABI 双轨边界

文档规定：better-sqlite3 等原生模块必须匹配当前 ABI——测试走 Node ABI，Electron 与 E2E 走 Electron ABI，修改测试或启动脚本时必须保留 ensure-native-abi.mjs 钩子。package.json 的 pre 钩子正是这一双轨制的落点：

• pretest / pretest:watch → node scripts/ensure-native-abi.mjs node（Node ABI）；
• prestart → pnpm run ensure:electron-runtime && node scripts/ensure-native-abi.mjs electron；
• pretest:e2e / pretest:e2e:ui / pretest:e2e:debug → 同样先切到 Electron ABI；
• 对应的手动重建入口为 rebuild:for-node（pnpm rebuild better-sqlite3）与 rebuild:for-electron（electron-rebuild --force --only better-sqlite3）。

scripts/ensure-native-abi.mjs 的实现揭示了"双轨"背后的探测机制：

• 在目标运行时下探测：probeRuntime()（第 42-58 行）对 electron 目标会把随包的 Electron 二进制当作 Node 运行（ELECTRON_RUN_AS_NODE=1），让探测子进程看到 Electron 自己的 ABI 版本；对 node 目标则直接用宿主 Node；
• 版本感知的判定：decideAbi()（第 16-26 行）解析探测结果——退出码 0 为 match，stderr 含 NODE_MODULE_VERSION 为 mismatch，含 Cannot find module 为 missing。注释明确指出这是修复"版本盲"缺陷：为旧版 Electron 编译的 .node 再也不会被误判为"已针对 Electron 编译完成"；
• 强制删除旧产物：removeStaleBinary() 会删除 node_modules/better-sqlite3/build/Release/better_sqlite3.node 再重建，因为 @electron/rebuild 的 .forge-meta 标记曾被观察到声称比二进制实际的 ABI 更新，因此不被信任。

六、postinstall 的两个独立门禁

scripts/postinstall.mjs 是 pnpm install 的收尾流程，文档要求其独立控制两个阶段，且"跳过其一绝不能暗示跳过另一个"：

• Stage A — Electron 原生重建：执行 electron-rebuild --module-dir . --sequential --disable-pre-gyp-copy（第 52-58 行；直接调用 @electron/rebuild 使重建指向仓库根目录，而不是 electron-builder 尚未生成的暂存 appDir），仅由 MOTRIX_SKIP_ELECTRON_REBUILD=1 跳过；
• Stage B — 拉取捆绑的 aria2 引擎：经由 scripts/fetch-engine.mjs，仅由 MOTRIX_SKIP_ENGINE_FETCH=1 跳过。

文件头部注释（第 4-19 行）还定义了失败语义：两个 SKIP 守卫相互独立，但失败不是独立的——Stage A 若实际执行且失败，会以其真实退出码短路退出、绝不进入依赖网络的 Stage B，让损坏的原生重建立即暴露而非被后序引擎拉取掩盖。另一个细节是信号杀进程（status === null 且带 signal）绝不会被 status ?? 0 误读为成功（classifyRebuildResult，第 32-40 行）。

七、Server Docker 边界

文档最后一节划定服务器镜像与桌面构建的边界：

• 服务器镜像使用系统 aria2，同时跳过 Electron 重建与引擎拉取——package.json 的 start:server 即以 MOTRIX_SKIP_ELECTRON_REBUILD=1 node dist/server/index.mjs 体现该模式；
• scripts/stage-server-app.mjs 为目标平台选择单个 better-sqlite3 prebuild（而非把多个平台的 .node 都塞进包内），再由 scripts/verify-server-package.mjs 校验暂存 payload 的完整性；
• 运行时镜像刻意不含 pnpm 与任何构建工具链，因此绝不能在服务器运行时依赖原生模块重建——ABI 匹配必须在暂存（stage）阶段一次性解决。

这条边界解释了为什么 pnpm-workspace.yaml 与 ensure-native-abi.mjs 同时存在：前者治理安装期的脚本权限，后者在每次测试/启动前做运行时 ABI 的最终裁决，二者共同覆盖"装进来"与"跑起来"两个时刻。

小结

electron-vite.md 用六个约束面（产物矩阵、格式边界、preload/URL 策略、pnpm 安装门禁、ABI 双轨、Docker 边界）完整刻画了 Motrix 的构建契约。结合仓库实现可以看到，每条约束背后都有具体机制支撑：Vite 多配置的 lib.formats 与 entryFileNames 保证产物命名，renderer-url-policy.ts 的单例策略对象统一窗口加载出口，pnpm-workspace.yaml 的 allowBuilds 与 ensure:electron-runtime 分工处理 Electron 43 的无 postinstall 特性，而 ensure-native-abi.mjs 的"在目标运行时下探测 + 删除旧产物"策略则让 ABI 检查真正具备版本感知能力。对于要维护或扩展 Motrix 构建链路的开发者，这份文档加上述文件路径，即可作为完整的排查与自检清单。