《Electron 45.2.3 内核解剖》第 8 章 模块加载:七个 bundle、一次 js2c、两个注册表

2 阅读1小时+

《Electron 45.2.3 内核解剖》第 8 章 模块加载:七个 bundle、一次 js2c、两个注册表

8.0 五个可以当场做的观察

在任何一个 Electron 45 应用里,下面五件事都能当场验证,而且每一件都会推翻一个想当然的直觉。

观察一:lib/ 不在硬盘上。

$ ls node_modules/electron/dist/resources/
default_app.asar
$ ls node_modules/electron/dist/resources/electron.asar
ls: cannot access '.../electron.asar': No such file or directory

在很长一段历史里,Electron 的框架 JS 代码躺在 resources/electron.asar 里,是一个可以用 npx asar extract 拆开、可以用编辑器改、改坏了应用就起不来的普通文件。在这个版本里它不存在了。dist/resources/ 下只剩 default_app.asar——那是"没给应用时启动的欢迎页",不是框架代码。

观察二:但代码里还在提它。

lib/renderer/init.ts:95:    global.__filename = path.join(process.resourcesPath, 'electron.asar', 'renderer', 'init.js');
lib/renderer/init.ts:96:    global.__dirname = path.join(process.resourcesPath, 'electron.asar', 'renderer');

这两行在给 http:// 页面里的 preload 伪造一个 __filename。如果只读代码,会以为 electron.asar 还在;如果去硬盘上找,会找不到。这是本章第一个"化石":一段代码在描述一个已经不存在的世界,只为了让依赖于那个世界的旧代码继续跑。

观察三:require.resolve('electron') 返回的不是路径。

// 主进程
require.resolve('electron')        // 'electron'
require.resolve('electron/main')   // 'electron'
require.resolve('electron/renderer') // 'electron'

Node 的 require.resolve 语义是"返回文件的绝对路径"。这里返回了一个裸字符串,说明有东西改写了 Module._resolveFilename,把五个不同的请求名塌缩成了同一个键。

观察四:require('electron') 拿到的属性是 getter。

README.md:64-66

const electron = require('electron')
Object.getOwnPropertyDescriptor(electron, 'app')
// { get: [Function: get], set: undefined, enumerable: true, configurable: false }
Object.keys(electron).length
// 几十个名字,但你一个模块都还没真正加载

Object.keys 能列出全部模块名,但此时 Menu、Tray、session 的构造函数一个都没被创建。名字是提前写好的,值是按需取的。

观察五:process._linkedBinding 和 require('electron') 是两个世界。

// 主进程
process._linkedBinding('electron_browser_app')      // { app: [Getter] } 之类,C++ 直接给的
process._linkedBinding('electron_renderer_ipc')     // Error: No such binding(主进程没有这个)
require('electron').app                             // 同一个 app 对象
require('electron').ipcRenderer                     // undefined(主进程的表里没有这一项)

require('electron') 在渲染进程里能拿到 ipcRenderer,在主进程里拿不到;process._linkedBinding('electron_renderer_ipc') 在主进程里直接报"没有这个绑定"。两条路径各有各的可见范围,互不越界。


五个观察指向同一个问题:

require('electron') 这四个字,到底被谁翻译成了什么?

这个问题的答案在 45 里发生了一次结构性搬迁。在旧版本里,答案是运行期的一句 JS:框架代码打包成 asar,Module._resolveFilename 钩子把 'electron' 指向 asar 里的 browser/api/exports/electron.js,Node 正常读文件、正常编译、正常执行。整条链都在运行期,全在 JS 里,全都可以被 monkey-patch。

在 45 里,这条链被拆成了两半:

  • 前一半搬到了构建期:lib/ 下 94 个 TypeScript 文件被 rolldown 打成 7 个 bundle,再由 js2c 转成 C++ 字节数组,编进二进制;
  • 后一半留在运行期:node::builtins::BuiltinLoader 按 id 取出字节,用 V8 编译成函数,带着两个参数(process、require)调用它。

于是"文件系统"这个环节整个消失了。没有文件可读,没有路径可解析,没有 asar 可拆。取而代之的是两个字符串注册表:

注册表键的样子值的来源谁在用
node::builtins 的 BuiltinLoaderinternal/electron/js2c/browser_initjs2c 生成的字节数组C++ 侧 CompileBundle / CompileAndCall
Node 的 linked binding 链表electron_browser_appNODE_LINKED_BINDING_CONTEXT_AWARE 宏注册的函数指针process._linkedBinding()

本章的立论:

Electron 的"模块"不是文件,是两张字符串表。第一张表把 JS 源码变成函数,第二张表把 C++ 模块变成 JS 对象。lib/ 是唯一同时看得见两张表的地方,因为它是唯一用两种键写过代码的地方。

这句话可以拆成三个可验证的命题:

  1. lib/ 里没有任何一行代码 require 过一个 .js 文件路径——所有 @electron/internal/... 都在构建期被解析掉了(8.3);
  2. lib/browser/api/module-list.ts 的 40 个条目里,有 7 个直接写 process._linkedBinding('electron_browser_*'),剩下 33 个 require('./x') 进去之后,第一行还是 process._linkedBinding(8.9);
  3. require('electron') 在运行期只命中一个假的 Module 缓存项,它的 exports getter 指回 bundle 内部的一个对象(8.10)。

三个命题合起来解释了一件事:为什么 Electron 的 API 表面看起来像 Node 模块,实际上一根线都不走 Node 的模块解析。


8.1 三代实现:asar、webpack、rolldown

要理解 45 为什么长成这样,得先把前两代的结构摆出来。这不是考古癖,因为 45 的代码里到处是前两代的残骸,读不懂残骸就读不懂现在。

8.1.1 第一代:asar + 运行期 require 钩子

框架 JS 放在 resources/electron.asar,asar 是一个把目录打包成单文件的格式,Node 的 fs 被 patch 过,读 asar 内部路径时会去解包。应用启动时:

  1. C++ 侧算出 electron.asar/browser/init.js 的路径;
  2. 调 node::LoadEnvironment,把 init.js 当入口脚本跑;
  3. init.js 里装一个 Module._resolveFilename 钩子,把 require('electron') 改写成 electron.asar/browser/api/exports/electron.js;
  4. 之后的一切都走 Node 的正常流程:读文件、Module._compile、包一层 function(exports, require, module, __filename, __dirname)。

这个结构的好处是完全透明:你能 asar extract 出来看,能改,能在 DevTools 里给框架代码下断点,栈里是真实文件名 electron.asar/browser/api/browser-window.js:123。

坏处有三个,都是后来出走的直接原因:

  • asar 是一次运行期解析。每个 require 都要过一次 asar 的路径索引,启动时几十次;
  • 每个文件都是一次独立编译。V8 要为每个 .js 单独 parse + compile,而 V8 的 code cache 是按脚本粒度缓存的,几十个小文件的缓存管理成本比一个大文件高一个量级;
  • 可以被改。这对调试是优点,对"框架完整性"是缺点:任何能写 resources/ 的人都能替换框架代码。

第三点在很长时间里是 Electron 安全讨论的固定条目。45 的结构从根上关掉了这条路:没有文件,就没有可替换的文件。

8.1.2 第二代:webpack + js2c

中间那一代把 lib/ 用 webpack 打成每进程一个 bundle,再 js2c 进二进制。这一代同时解决了"可替换"和"文件太多"两个问题,但留下了 webpack 自己的包袱:

  • webpack 的 runtime 会注入一堆 __webpack_require__、模块 id 映射、chunk 加载器。这些代码在 Electron 里永远只服务一个 chunk,纯属开销;
  • webpack 对 ESM 的处理会引入 __esModule 标记和 get default() 包装,而 Electron 的 module-list 需要"拿到构造函数本身",于是 define-properties.ts:6 里长出了 handleESModule 那段三分支代码(8.9.2);
  • webpack 的配置是隐式的,externals 和 ProvidePlugin 的组合难以审计。

第二代留下的最明显化石,是 lib/browser/api/module-list.ts 的第 1 行:

lib/browser/api/module-list.ts:1
// TODO: Updating this file also required updating the module-keys file

本仓库里不存在任何叫 module-keys 的文件:

$ grep -rn "module-keys" --include=*.ts --include=*.mts --include=*.js .
lib/browser/api/module-list.ts:1:// TODO: Updating this file also required updating the module-keys file

一条 TODO 指向一个已经被删掉的文件。它说明在那个年代,加一个模块要改两个地方:module-list.ts 声明名字和 loader,module-keys.ts 给 webpack 提供静态可分析的键名列表(webpack 需要它才能做 require('electron') 的静态分析)。rolldown 不需要这个:它按真正的模块图工作,不需要一份"键名清单"喂给它。

8.1.3 第三代:rolldown + 单 chunk + 构建期代码缓存

45 的流水线是这样的(全部证据在 BUILD.gn:22 与 build/bundle/):

lib/<target>/init.ts
   │  rolldown(build/bundle/bundle.mjs)
   ▼
$root_gen_dir/internal/electron/js2c/<name>.js      ← 7 个文件
   │  node_js2c(--only-js)
   ▼
$root_gen_dir/electron_natives.cc                    ← 1 个 C++ 文件,字节数组
   │  编译链接
   ▼
electron 二进制
   │  BuiltinLoader::LookupAndCompileFunction
   ▼
一个 v8::Function,参数 (process, require) 或 (binding) 或 (isolatedApi)

BUILD.gn 里能数出全部 7 个 bundle 目标:

BUILD.gn:241  electron_bundle("electron_browser_bundle")            → browser_init.js
BUILD.gn:247  electron_bundle("electron_renderer_bundle")           → renderer_init.js
BUILD.gn:253  electron_bundle("electron_worker_bundle")             → worker_init.js
BUILD.gn:259  electron_bundle("electron_webview_bundle")            → webview_bundle.js
BUILD.gn:265  electron_bundle("electron_isolated_renderer_bundle")  → isolated_bundle.js
BUILD.gn:271  electron_bundle("electron_node_bundle")               → node_init.js
BUILD.gn:277  electron_bundle("electron_utility_bundle")            → utility_init.js
BUILD.gn:283  action("electron_js2c")                               → electron_natives.cc

七个输入文件,七个输出文件,一个 js2c action,一个 .cc。没有 asar,没有中间目录,没有运行期解析。

三个时代放在一起看,变的是"JS 代码在哪里、以什么形态存在":

第一代第二代第三代(45)
源码位置resources/electron.asar二进制内 js2c二进制内 js2c
打包器无(原样)webpackrolldown
运行期模块解析Node 正常解析 + 钩子Node + 钩子无(全部构建期解析)
单文件编译粒度每文件一次每 bundle 一次每 bundle 一次
code cacheV8 自动(磁盘)无(每次冷编译)构建期生成,随二进制发布
可被用户替换是否否
栈里的文件名electron.asar/...js:12bundle 内偏移bundle 内偏移

最后一行是这一代最实在的代价:你没法再在框架代码里下断点了。 调试器看到的文件名是 internal/electron/js2c/browser_init,行号是打包后的行号,跟 browser-window.ts 对不上。这是为了启动速度和完整性付的账,第 23 章会算总账。

8.1.4 一个反直觉的收益:类型检查变成了构建门槛

bundle.gni 里有一条不起眼的依赖:

build/bundle/bundle.gni
    deps += [
      # rolldown only strips types; refuse to bundle code that does not check.
      "//electron:electron_lib_typecheck",
      "//electron/buildflags",
    ]

注释说得很直白:rolldown 只剥类型,不检查类型。所以类型检查被单独拎出来,作为一个前置依赖——类型不过,bundle 不生成。

typecheck.mjs 干的事只有一件:tsc --project tsconfig.electron.json --noEmit。它甚至不是 rolldown 的插件,而是一个独立的 npm action,因为它们之间没有数据流关系,只有顺序关系。

这件事的意义超出了工程便利。它意味着:从 45 开始,"lib/ 的类型是自洽的"成了构建产物的一部分保证。 在 webpack 时代,ts-loader 也可以做类型检查,但那是一个可选项(transpileOnly: true 能关掉);在这里它是一条硬依赖边,关不掉。

顺带解释了另一个现象:为什么 lib/ 里到处是 as typeof import('electron') 和 as NodeJS.ModuleInternal。因为这套代码同时跑在"有 Node 类型"和"没有 Node 类型"的进程里,类型系统必须被显式地骗过去——而这些骗术必须通过 tsc --noEmit 才能进 bundle。


8.1.5 构建期生成物的清单

第三代结构把大量逻辑搬到了构建期,代价是生成物变多。全部列出来,才能理解"改一行 lib/ 要重跑什么":

生成物生成者输入失效后果
filenames.auto.gniscript/gen-filenames.mts:134七次 --print-graphninja 不知道要重跑打包器,产物是旧的
<target>.bundle.js ×7bundle.mjslib/** + buildflags.h运行的是旧代码
buildflags.hGN buildflags 目标*.gni 里的 enable_*JS 与 C++ 的编译开关不一致
electron_natives.ccbuild/js2c.py → node_js2c7 个 bundlebundle id 缺失或内容旧
electron.d.tsdocs/api/*.md(194 项)文档类型与实现不一致,tsc 报错或漏报
Js2cCache*.cc ×5electron_natives_codecache_mainbundle + 快照 + flag缓存不命中,启动变慢且无日志

六种生成物,三种失效模式:旧(静默)、不一致(编译错)、不命中(静默变慢)。三种里两种是静默的,这解释了为什么仓库里要养 --check 模式(8.4.3)和那条 spec(8.5.7)——静默失效只能靠主动断言发现。

还有一条隐含依赖:buildflags.h 同时喂给 C++ 和 rolldown 的 buildflagPlugin。如果哪天有人手工改 out/gen/ 下的 buildflags.h,两边会同时变,但 ninja 不知道——下次增量构建会把这个改动覆盖掉一半。生成物永远不该被手改,但生成物越多,这条纪律越难守。

8.2 七张清单:targets.mjs 逐字段解剖

七个 bundle 不是"同一份代码打七次"。targets.mjs 用一张 7 行的表,加 5 个布尔字段,决定了每个 bundle 的语言环境:它能看见什么全局变量、能不能 require、require('electron') 指向哪张表、出错时是抛还是吞。

先把表完整抄下来(这是全章的骨架):

targets.mjs:23-30

// build/bundle/targets.mjs
export const targets = {
  browser:  { alwaysHasNode: true },
  renderer: { alwaysHasNode: true, targetDeletesNodeGlobals: true,
              wrapInitWithProfilingTimeout: true, wrapInitWithTryCatch: true },
  worker:   { loadElectronFromAlternateTarget: 'renderer', alwaysHasNode: true,
              targetDeletesNodeGlobals: true, wrapInitWithTryCatch: true },
  webview:  { alwaysHasNode: false, loadElectronFromAlternateTarget: 'renderer',
              wrapInitWithTryCatch: true },
  isolated_renderer: { alwaysHasNode: false, wrapInitWithTryCatch: true },
  node:     { alwaysHasNode: true },
  utility:  { alwaysHasNode: true }
};

文件顶部的注释把每个字段的语义写清楚了,但没说"为什么"。这一节逐条补上。

8.2.1 alwaysHasNode:一个字段,五个后果

alwaysHasNode 字面意思是"这个 bundle 运行时一定有 Node"。它在 bundle.mjs:154-162 里被读了五次,每一次都改变一个不同的层面:

后果一:platform。 bundle.mjs:154-161 把 rolldown 的 platform 设成 'node' 或 'browser'。这会影响 rolldown 对 process、global、Buffer 这些标识符的默认假设,也影响它对条件导出的解析(package.json:5 的 exports.import / exports.require / exports.browser 分支)。

后果二:Node 内置模块是保留还是报错。

bundle.mjs:154

const nodeExternalsPlugin = {
  name: 'electron-node-externals',
  resolveId: {
    filter: { id: /^[a-z0-9_:/]+$/ },
    handler(source, importer, { kind }) {
      const id = source.replace(/^node:/, '');
      if (!nodeModules.has(id) && !id.startsWith('internal/')) return null;
      if (!target.alwaysHasNode) {
        this.error(`'${id}' imported by ${path.relative(electronRoot, importer)} is not available without Node.js`);
      }
      ...

对 alwaysHasNode: true 的 bundle,require('fs')、require('internal/modules/helpers') 会被保留成一个外部依赖,运行期真的去调 Node 的 require。对 webview / isolated_renderer,同样的代码是构建期错误——不是运行期报错,是 bundle 生成不出来。

这个区别很重要。它把"沙箱渲染进程里没有 Node"从一条运行期约束,变成了一个编译期不可能。你不可能写出一个"在沙箱里 require('fs')"的 bundle,因为打包器根本不给你这个机会。

后果三:events 从哪来。

bundle.mjs:99

if (!target.alwaysHasNode) {
  exactAliases.set('events', path.resolve(libDir, 'common', 'node-events.ts'));
}

有 Node 的 bundle,import { EventEmitter } from 'events' 就是 Node 的 events 模块。没有 Node 的 bundle,events 被别名到 node-events.ts:1-5——一个用原生 C++ 实现的 EventEmitter 包装(第 7 章 7.9 讲过它的 GetEventEmitterTemplate)。同名模块,两种实现,靠一个 Map 切换。

后果四:process 从哪来。

bundle.mjs:141

if (!target.alwaysHasNode) {
  inject.process = ['@electron/internal/webview/process', 'default'];
}

process.ts:1-8 全文只有 11 行:

declare const binding: {
  get: NodeJS.Process['_linkedBinding'];
  contextIsolated: boolean;
};

const process = {
  _linkedBinding: binding.get,
  contextIsolated: binding.contextIsolated,
  sandboxed: true,
  type: 'renderer'
};

export default process;

注意它 declare 了一个叫 binding 的自由变量,然后从它身上取 get。这个 binding 是 bundle 的函数参数——js2c_bundle_ids.h:38 里 kWebViewBundleParams = {"binding"}。所以沙箱里的 process 是一个四字段的手工对象,_linkedBinding 指向 C++ 注入的 binding.get,而 binding.get 背后是 preload_utils::GetBinding(8.8.3)。

这四个字段的选择本身就是一份设计文档:沙箱里需要"取绑定"、"知道是否隔离"、"知道自己是沙箱"、"知道自己是渲染进程",别的都不需要。没有 nextTick,没有 env,没有 argv。 一个假的 process 只提供四周代码真正用到的东西,多一个字段都是攻击面。

后果五:global 是否存在。

bundle.mjs:144

const define = target.alwaysHasNode ? {} : { global: 'globalThis' };

沙箱渲染进程里没有 Node 的 global。但 lib/ 里与 Node 共享的代码会写 global.xxx。于是打包器把 global 这个自由标识符替换成 globalThis。这不是运行时 polyfill,是源码级替换——global.foo = 1 变成 globalThis.foo = 1。

8.2.2 loadElectronFromAlternateTarget:为什么 worker 用 renderer 的表

worker 和 webview 都写着 loadElectronFromAlternateTarget: 'renderer'。含义在 bundle.mjs:54:

const electronAPIFile = path.resolve(
  libDir,
  target.loadElectronFromAlternateTarget ?? args.target,
  'api',
  'exports',
  'electron.ts'
);

也就是说:worker bundle 的 require('electron') 指向 lib/renderer/api/exports/electron.ts,而不是 lib/worker/...(那个目录下根本没有 api/exports)。

为什么?因为 worker 里能拿到的 Electron API 就是渲染进程那一套:ipcRenderer、webFrame、contextBridge、webUtils、crashReporter、sharedTexture——六项,与 lib/renderer/api/module-list.ts:5 一字不差。Worker 没有自己的 BrowserWindow,也不可能 new Notification。给它一张与渲染进程相同的表,是用类型系统表达能力边界:worker 里的 require('electron') 的类型就是渲染进程的类型,多一个属性都编译不过。

webview 走同一条路,理由更直接:lib/webview/init.ts:1-10 的第一行就是

import { webViewInit } from '@electron/internal/renderer/web-view/web-view-init';

它本来就是渲染进程代码的一部分,只是被打成了独立 bundle 以便在没有 Node 的环境里跑(8.7.3)。

8.2.3 targetDeletesNodeGlobals:三个变量会在运行时消失

renderer 和 worker 都开了这个字段,注释写得很短:

// targetDeletesNodeGlobals:
//   `process`, `global` and `Buffer` may be deleted from the global scope
//   before bundle code runs later on, so free references to them are rewritten
//   to the copies captured by lib/common/node-globals.ts.

"may be deleted" 指的是 lib/renderer/init.ts:125:

const shouldDeleteRendererNodeGlobals = !nodeIntegration && !process.contextIsolated;

当一个渲染进程既没有 nodeIntegration、又没有开启 contextIsolation 时,process、Buffer、setImmediate、clearImmediate、global、root、GLOBAL 会被从全局删掉(8.11.2 讲时序)。删掉之后,bundle 里那些"以后才会执行"的代码如果还写 process.nextTick,就会 ReferenceError。

node-globals.ts:10-13 是解药:

const _global = typeof globalThis !== 'undefined' ? globalThis.global : (self || window).global;
const process = _global.process;
const Buffer = _global.Buffer;

export { _global, process, Buffer };

它在模块求值那一刻把三个值抓进闭包。注意 _global 那一行的写法:globalThis.global——先拿 globalThis,再从它身上取 global,而不是直接写 global。文件注释解释了原因:

// Rip global off of window (which is also global) so that the bundler doesn't
// auto replace it with a looped reference to this file

如果直接写 global,inject 插件会把这个文件自己的 global 也替换成 _global,形成 const _global = globalThis._global 的自引用。所以必须绕一层。

这就是 inject 的第三个条目:

bundle.mjs:130

if (target.targetDeletesNodeGlobals) {
  // See the Module.wrapper override in lib/renderer/init.ts.
  Object.assign(inject, {
    Buffer: ['@electron/internal/common/node-globals', 'Buffer'],
    global: ['@electron/internal/common/node-globals', '_global'],
    process: ['@electron/internal/common/node-globals', 'process']
  });
}

process → node-globals.process,Buffer → node-globals.Buffer,global → node-globals._global。三个自由标识符被重写成三个 import。从"运行时可能不存在的全局变量"变成"构建期一定存在的模块绑定"。

第三个注入项 Promise 无条件生效:

bundle.mjs:127

const inject = {
  Promise: ['@electron/internal/common/primordials', 'Promise']
};

primordials.ts:4 只有两行有效代码:export const Promise = global.Promise;。注释说明"用户改 global.Promise.resolve 会连带改到这里,这没关系"——因为要防的不是方法被改,是构造函数被换。如果用户在页面里写 Promise = MyPromise,bundle 里的 await 语义仍然是原生的。

8.2.4 两个 wrapInitWith*:错误处理的两种策略

wrapInitWithTryCatch 在 bundle 外面套一层:

bundle.mjs:262

if (target.wrapInitWithTryCatch) {
  code = `try {
${code}
} catch (err) {
  console.error('Electron ${outputFilename} script failed to run');
  console.error(err);
}
`;
}

谁开了?renderer、worker、webview、isolated_renderer。谁没开?browser、node、utility。

这个分布不是随意的。主进程的 init 抛异常必须炸:主进程起不来,应用就该退出,静默吞掉只会让用户看到一个永远不出现的窗口。而渲染进程的 init 跑在别人的页面里,抛出去会变成页面的 uncaughtException,把应用代码的错误和框架的错误混在一起;webview / isolated_renderer 更极端,它们跑在 <webview> 的隔离世界里,抛出去没人接。

node_util.cc:73 的注释正好从另一头印证了这个分工:

  // This will only be caught when something has gone terrible wrong as all
  // electron scripts are wrapped in a try {} catch {} by
  // build/bundle/bundle.mjs

"所有 electron 脚本都被 try/catch 包着"——其实只有四个包了。这句注释是在四个 bundle 的语境下写的,但它描述的是一个跨文件的约定,写注释的人把"多数"记成了"全部"。这种小误差正好说明:约定活在代码里,不在注释里。

wrapInitWithProfilingTimeout 只有 renderer 开:

bundle.mjs:250

if (target.wrapInitWithProfilingTimeout) {
  code = `function ___electron_init__() {
${code}
};
if ((globalThis.process || binding.process).argv.includes("--profile-electron-init")) {
  setTimeout(___electron_init__, 0);
} else {
  ___electron_init__();
}
`;
}

注意 (globalThis.process || binding.process):渲染进程 bundle 两种形态都可能(有 Node / 无 Node),所以取 process 的方式要兼容。这个表达式的存在本身就承认了"同一个 target 字段组合可以产出两种运行环境"。

--profile-electron-init 的作用是把 init 推迟一个 tick,让 profiler 有时间挂上。为什么只有 renderer 需要?因为只有渲染进程的 init 会在页面加载的关键路径上,且耗时与页面内容相关;主进程的 init 在启动早期,profiler 通常已经在 --inspect-brk 下就位了。

8.2.5 五个参数名,三个签名

targets.mjs 决定"打什么",js2c_bundle_ids.h 决定"怎么调"。这两份文件必须严格对齐,因为参数名进了 V8 的 code cache key:

// shell/common/js2c_bundle_ids.h
inline constexpr std::array<std::string_view, 1> kWebViewBundleParams = { "binding" };
inline constexpr std::array<std::string_view, 1> kIsolatedBundleParams = { "isolatedApi" };
inline constexpr std::array<std::string_view, 2> kInitBundleParams = { "process", "require" };

三种签名,对应三类 bundle:

签名参数用在运行时调用点
(process, require)2 个browser / renderer / worker / utility / nodeNodeBindings::LoadEnvironment、NodeBindings::RegisterBuiltinBindings
(binding)1 个webviewElectronSandboxedRendererClient::DidCreateScriptContext
(isolatedApi)1 个isolated_rendererRendererClientBase::DidCreateScriptContext

"参数名进 cache key"这句话需要展开,否则它只是个耸人听闻的说法。V8 的 ScriptCompiler::CreateCodeCache 生成的缓存块与编译时的参数列表绑定:同一个源文件,用 (a, b) 编译和用 (x, y) 编译,产生的字节码里变量槽位不同,缓存不通用。所以:

  • 构建期生成缓存的工具(8.5)必须用完全相同的参数名编译;
  • 运行期 CompileBundle 也必须用完全相同的参数名;
  • 两边的参数名都来自这个头文件的 constexpr 数组。

一条链上三个环节,共享一份字符串常量。这就是这个头文件存在的唯一理由——如果只是为了让代码好看,MakeBundleParams 完全可以在调用点手写 {"process", "require"}。

头文件顶部的注释把风险写明了:

// The ids and params feed V8's code-cache key (source + params hash), so the
// build-time codecache generator (electron_natives_codecache_main.cc) must
// compile each bundle with the exact same params its runtime CompileAndCall
// site uses -- this header keeps both sides in sync. spec/api-js2c-code-cache.spec.ts
// also asserts every bundle's cache is consumed, catching any drift.

最后一句是关键:编译器管不了这件事。参数名拼错一个字母,代码照样编译,运行照样跑,只是缓存永远不命中,启动慢 30ms。所以需要一个测试去断言"缓存被消费了"(8.5.6)。这是本书里少见的"用测试替代类型系统"的例子。


8.2.6 把七个 target 排成能力矩阵

前面五个字段是"怎么打"。把七个 target 摆成一张能力矩阵,能看到"为什么是这个组合":

能力browserrendererworkerutilitywebviewisolatednode
Node 内置模块✓✓✓✓✗✗✓
真实 process✓✓✓✓假(4 字段)✗✓
require('electron')42 项8 项8 项4 项8 项*✗✗
原生 EventEmitter✓✗✗✓✗✗✗
preload✗✓✗✗✗✗✗
ipcMain✓✗✗✗✗✗✗
ipcRenderer✗✓✓✗✓✓✗
<webview> 实现✗主世界✗✗隔离世界主世界✗
创建窗口✓✗✗✗✗✗✗
ASAR(node_init)✓✓✓✓✗✗✓
code cache flavorbrowserrendererworkerutilitysandboxsandboxbrowser

(*webview 的别名存在但 init.ts 没用到——"有表无调用"。node 连表都没有。)

这张矩阵有三处"缺口",每一处都是刻意的:

缺口一:webview 能用 ipcRenderer,但没有 node_init。 所以它读不了 asar 里的文件。<webview> 的实现不需要读文件——它的所有资源访问都通过浏览器进程的 guest 通道。

缺口二:utility 没有 ipcRenderer,但有 parentPort。 它走的是 worker 式的 MessagePort,不是渲染进程那条 IPC 通道。第 16 章会讲这条差异。

缺口三:node(RUN_AS_NODE)有 require('electron') 的别名,但那张表指向 renderer 的表? 不是——node target 没有 loadElectronFromAlternateTarget,所以 electronAPIFile 会解析到 lib/node/api/exports/electron.ts,而这个文件不存在。这意味着 node bundle 里任何 require('electron') 都会在打包时失败。事实是它没有——lib/node/init.ts 只碰 fs、child_process、path、module。

换句话说:require('electron') 在 ELECTRON_RUN_AS_NODE 模式下根本不可用,而且这一点由"缺失一个文件"来保证。 没有运行期检查,没有错误信息,打包器会因为解析失败而拒绝生成 bundle。如果哪天有人想在 lib/node/ 里 import electron,构建会立刻失败——用构建失败替代运行期 undefined,这是这套设计的典型手法。


8.3 rolldown 流水线:六个插件与两次重写

bundle.mjs:50-52 一共 280 行,做的事情可以概括成一句话:把一个 TypeScript 目录树,压成一个没有 require 调用、没有 process 引用、没有 BUILDFLAG 宏的纯函数体。

压的过程有六道工序,每道都是一个 rolldown 插件或一个编译选项。按执行顺序:

8.3.1 入口探测:init.ts 优先,init.js 兜底

bundle.mjs:50

const entry = ['init.ts', 'init.js']
  .map((file) => path.resolve(libDir, args.target, file))
  .find((file) => fs.existsSync(file));

三个字符的信息量:每个 bundle 的入口必须叫 init.ts(或 init.js),必须直接躺在 lib/<target>/ 下。 没有配置文件指定入口,没有多入口。这条约定让"有哪些 bundle"这个问题可以用 ls lib/ 回答:

lib/browser/init.ts   lib/renderer/init.ts   lib/worker/init.ts
lib/utility/init.ts   lib/webview/init.ts    lib/isolated_renderer/init.ts
lib/node/init.ts

七个目录,七个 init.ts,一一对应 targets.mjs 的七个键。.js 兜底是给 lib/node/ 留的余地——那里现在也是 .ts,但 node/ 目录下的代码风格更接近 Node 本体,保留 .js 入口的可能性。

8.3.2 aliasPlugin:require('electron') 的第一次重写

bundle.mjs:94

const exactAliases = new Map(
  ['electron', 'electron/main', 'electron/renderer', 'electron/common', 'electron/utility']
    .map((id) => [id, electronAPIFile])
);

五个名字,一个目标:lib/<target>/api/exports/electron.ts。这是本章最重要的一行代码,因为它决定了 require('electron') 在 bundle 内部的语义。

关键在 filter 的正则:new RegExp('^(electron|electron/main|...)$')——精确匹配,不是前缀匹配。所以:

  • require('electron') → 被重写;
  • require('electron-store') → 不动,rolldown 照常解析它,解析不到就让构建失败——lib/ 不允许依赖应用侧的包;
  • require('electron/main') → 被重写,而且不管当前是哪个进程。

最后一点值得停一下。lib/common/init.ts 的注释说得很直白:

// It is intentional that these can be `require()`-ed from both the main process
// as well as the renderer process regardless of the names, they're superficial
// for TypeScript only.

electron/main 不是"只能主进程用"的入口,它只是一个给 TypeScript 看的名字。运行期,五个名字全部塌缩到当前 bundle 的那张表。所以渲染进程里 require('electron/main').app 会得到 undefined(不是报错),因为渲染进程的表里没有 app。

这个设计有代价:类型系统能拦住"在渲染进程用 app",运行期拦不住。 但这正是 Electron 一贯的取舍——类型是给写代码的人看的,运行期只保证"没有的东西就是 undefined"。

8.3.3 nodeExternalsPlugin:让 require 保持懒惰

bundle.mjs:153

const nodeShimPrefix = '\0electron-node-external:';

这个插件处理两类导入:Node 内置模块(fs、path、events…)和 internal/*(Node 的私有模块,如 internal/modules/helpers)。做法分两种:

bundle.mjs:165-166

if (kind === 'require-call') return { id, external: true };
return { id: `${nodeShimPrefix}${id}`, moduleSideEffects: false };
  • 源码里写的是 require('fs') → 直接标成 external,保留成运行期的 require('fs');
  • 源码里写的是 import * as fs from 'fs' → 转成一个虚拟模块,内容是一行 module.exports = require("fs")。

为什么要分两种?注释解释了:

// A plain external `import` would be hoisted to a require() at the very top of
// the bundle; routing it through a one-line CommonJS shim instead keeps the
// require() lazy, so a built-in is only loaded once the (lazily evaluated)
// module importing it actually runs, as it was with webpack.

ESM 的 import 语义是提升到模块顶部立即求值。如果 lib/utility/api/net.ts:4 有 import { Socket } from 'net',打包后 bundle 的第一行就会 require('net')——哪怕这个模块永远不被用到。而 module-list 的全部设计就是"惰性"(8.9),两者冲突。

用虚拟模块绕开:import 变成"从虚拟模块取默认导出",虚拟模块的求值本身也是惰性的(moduleSideEffects: false 让打包器敢把它放在懒路径里),真正 require('net') 发生在虚拟模块第一次被求值时。

一行 shim,换回整个惰性语义。这是这一代打包器比 webpack 干净的地方:webpack 需要 externals 配置 + externalsType,行为由配置决定;这里行为由模块图决定,插件只负责插入一个中间节点。

8.3.4 buildflagPlugin:把 C++ 的编译开关搬进 JS

bundle.mjs:73

const buildflagPlugin = {
  name: 'electron-buildflag',
  transform: {
    filter: { code: 'BUILDFLAG(' },
    handler(code, id) {
      if (!args.buildflags) return null;
      return code.replace(/\bBUILDFLAG\(\s*([A-Za-z0-9_]+)\s*\)/g, (_, name) => {
        if (!buildflags.has(name)) {
          this.error(`${path.relative(electronRoot, id)}: BUILDFLAG(${name}) is not defined in ${args.buildflags}`);
        }
        return `(${buildflags.get(name)})`;
      });
    }
  }
};

它读的是 out/gen/electron/buildflags/buildflags.h,用正则 #define BUILDFLAG_INTERNAL_(.+?)\(\) \(([01])\) 抽出所有开关,然后把 JS 里的 BUILDFLAG(ENABLE_XXX) 替换成 (true) 或 (false)。

这一步的意义:同一个布尔值,C++ 和 JS 两边必须一致,而它们的一致性由构建系统保证。 如果 BUILDFLAG(IS_MAS_BUILD()) 在 C++ 里是 true、在 JS 里是 false,就会出现"主进程认为自己是 MAS 构建、渲染进程认为不是"的诡异 bug。这种 bug 在运行期几乎无法定位。

注意 filter: { code: 'BUILDFLAG(' }——只对包含这个字符串的文件跑 transform。这是个纯性能优化,但也说明一个事实:BUILDFLAG 在 lib/ 里的出现次数不多,多到需要过滤的文件很少。

return null 那个分支(没有 --buildflags 参数时)服务于 --print-graph:只列模块图、不生成产物时,没有 buildflags 可读,宏留给 typings 里的声明去满足类型检查。

8.3.5 两次重写之后的产物形状

六道工序之后,bundle.generate() 被调用:

bundle.mjs:210

format: 'cjs',
exports: 'none',
codeSplitting: false,
keepNames: true,
minify,
strict: false

四个选项,每一个都在解决一个具体问题:

format: 'cjs' + exports: 'none':产物是一个 CommonJS 风格的函数体,但不生成 exports 对象。因为 bundle 不需要被 require,它是被 fn->Call() 直接调的。exports: 'none' 还顺带保证了"没有模块导出"——这跟下一节要讲的"假 Module"直接相关。

codeSplitting: false:强制单 chunk。后面的代码会断言这一点:

bundle.mjs:229

if (rest.length) {
  throw new Error(`Expected a single output chunk, got ${1 + rest.length}`);
}

单 chunk 是 js2c 的前提(一个 id 对应一段字节),也是 code cache 的前提(一个 id 一个缓存块)。

keepNames: true 加上 official 构建的 minify 配置:

bundle.mjs:201

const minify = args.mode === 'production'
  ? { compress: { keepNames: { function: true, class: true } },
      mangle: { toplevel: true, keepNames: true } }
  : false;

压缩但保留函数名和类名。原因写在注释里:

// Function and class names show up in stack traces and in the API
// (e.g. BrowserWindow.name), keep them through scope hoisting renames.

BrowserWindow.name 是 API 的一部分——用户会写 if (win.constructor.name === 'BrowserWindow')。压缩掉类名会让这类代码静默失效。这是一个"性能 vs 可观察行为"的选择,选了后者。

strict: false:不注入 'use strict'。但代码最后又被手动加了一行:

bundle.mjs:272

code = `'use strict';\n${code}`;

先关掉打包器的注入,再手动加在最外层。区别在于位置:打包器注入的 'use strict' 会在 (() => {...})() 内部,只作用于 chunk;手动加的在整个脚本顶部,作用于整个编译单元。差别微小,但说明作者在意"严格模式的作用域边界"。

8.3.6 外层包装:三层壳

最终产物是三层嵌套:

'use strict';
try {                                  // ① wrapInitWithTryCatch
  function ___electron_init__() {      // ② wrapInitWithProfilingTimeout
    (() => {                           // ③ 固定壳
      /* chunk.code */
    })();
  };
  if ((globalThis.process || binding.process).argv.includes("--profile-electron-init")) {
    setTimeout(___electron_init__, 0);
  } else {
    ___electron_init__();
  }
} catch (err) {
  console.error('Electron renderer_init.js script failed to run');
  console.error(err);
}

第 ③ 层壳的注释值得抄下来:

// The bundle is compiled as a function body (by Electron with the parameters
// in shell/common/js2c_bundle_ids.h, and by node_mksnapshot with Node's
// built-in module parameters: exports, require, module, process,
// internalBinding, primordials), so keep the hoisted top-level declarations
// of lib/ in their own scope rather than let one of them redeclare a
// parameter.

信息量很大:同一个 bundle 可能被两个不同的宿主编译——Electron 自己(参数是 process, require)和 node_mksnapshot(参数是 Node 内置模块那一套 exports, require, module, process, internalBinding, primordials)。两个宿主的参数列表不同,如果 chunk 顶层有一个 const require = ...,在 Electron 里会撞参数,在 mksnapshot 里也会撞。包一层 IIFE,把顶层声明关进自己的作用域,两个宿主都安全。

这条注释也解释了为什么 format: 'cjs' 却不生成 module/exports:真正的 CJS 包装由宿主提供,bundle 只是函数体。


8.4 js2c:把 JS 变成 C++ 数组的最后一步

8.4.1 十二行 Python

build/js2c.py 全文:

#!/usr/bin/env python3
import os, subprocess, sys

def main():
  js2c = sys.argv[1]
  root = sys.argv[2]
  natives = sys.argv[3]
  js_source_files = sys.argv[4:]

  subprocess.check_call(
    [js2c, natives] + js_source_files + ['--only-js', "--root", root])

if __name__ == '__main__':
  sys.exit(main())

它自己什么都不做,只是把参数重排后转交给 third_party/electron_node:node_js2c——Node 的 js2c 工具。三个参数:

  • natives:输出的 .cc 路径(electron_natives.cc);
  • root:源码根目录($root_gen_dir),决定生成的 id 前缀;
  • --only-js:只要 JS,不要 Node 那些 .js + .json 的混合打包逻辑。

--root 是关键。js2c 生成的 id 是文件路径相对 root 去掉扩展名:

$root_gen_dir/internal/electron/js2c/browser_init.js   →  internal/electron/js2c/browser_init

这就是为什么 BUILD.gn 把产物写在 $root_gen_dir/internal/electron/js2c/ 下,而不是随便一个目录。目录结构就是 id。 改一个目录名,js2c_bundle_ids.h 里的常量、node_bindings.cc 的字符串拼接、code cache 工具的 id 全部失配。

8.4.2 electron_natives.cc 里有什么

js2c 的产物是一个 C++ 文件,形态大致是:

// 每个 bundle 一组静态数组
static const uint8_t browser_init_js[] = { 39,117,115,101,32,115,116,114,105,99,116,39,59,10, ... };
static const uint8_t renderer_init_js[] = { ... };
...

// 一张总表
struct node_builtin_js { const char* name; const uint8_t* source; size_t source_len; };
static const node_builtin_js electron_natives[] = {
  { "internal/electron/js2c/browser_init", browser_init_js, sizeof(browser_init_js) },
  ...
};

三个特征:

  1. 名字是 internal/electron/js2c/*。internal/ 前缀让这些 id 落在 Node 的"私有内置模块"命名空间里,用户代码 require('internal/electron/js2c/browser_init') 在 Node 的权限模型下本来就不该可达,即使可达也只会拿到一段立即执行并返回 undefined 的函数。
  2. 字节数组,不是字符串。 避免 C++ 字符串字面量的转义、长度和 \0 问题;也方便 code cache 生成工具按 byte span 处理。
  3. 与 Node 自己的内置模块共用一张表。 node_js2c 同时处理 third_party/electron_node 的 lib/**/*.js,Electron 的七个 bundle 插在同一张 electron_natives 表里。所以 BuiltinLoader 看到的 id 空间是"Node 的 + Electron 的",两者共用一个加载器——这正是 CompileBundle 能直接复用的原因(8.6)。

8.4.3 filenames.auto.gni:GN 看不见模块图

Ninja 要求每个 action 显式声明输入。但 rolldown 的输入是"从入口能走到的所有文件",这在 GN 里无法静态表达——GN 不做模块解析。

Electron 的解法是提前跑一遍打包器,只问模块图:

bundle.mjs:236-237

// bundle.mjs
if (printGraph) {
  console.log(JSON.stringify([...graphFiles].sort()));
}

graphPlugin 的 buildEnd 把所有绝对路径收集起来,相对化、正斜杠化,然后 --print-graph 直接打印。script/gen-filenames.mts:134 对七个 target 各跑一次,把结果写进 filenames.auto.gni。

实测的依赖数量:

bundle模块图文件数
browser65
renderer29
worker18
webview15
utility15
isolated_renderer9
node5

七个数字加起来 156,而 lib/ 一共只有 94 个 .ts 文件(10,147 行、355,049 字节)。156/94 ≈ 1.66,说明平均每个文件被 1.66 个 bundle 打包。共享的核心是 lib/common/ 与 lib/renderer/api/——后者被 renderer、worker、webview 三个 bundle 共用。

browser 的 65 是最大的,因为它拖进了整个主进程 API 面(40 个模块 + 各自的依赖)。node 的 5 最小:lib/node/init.ts:2 只依赖 asar wrapper、child_process、path、module 几样。

生成脚本还有 --check 模式:

gen-filenames.mts:130-134

if (process.argv.includes('--check')) {
  const existing = fs.existsSync(gniPath) ? fs.readFileSync(gniPath, 'utf8') : '';
  if (existing !== generated) {
    console.error(`${path.relative(rootPath, gniPath)} is out of date. Run 'node script/gen-filenames.mts' to regenerate.`);
    process.exit(1);
  }
}

CI 里跑 --check,文件不同步就挂。这条检查的存在说明一件事:模块图是构建系统的一部分,必须被版本控制。 一个新增的 import 若没同步到 filenames.auto.gni,ninja 不会重跑打包器——产物是旧的,测试却在新的源码上跑。这类"读的是旧代码"的 bug 极难发现,所以宁可用一个生成文件 + 一条检查把它钉死。

8.4.4 两个 restat 细节

打包产物写盘前有一段判断:

bundle.mjs:274

// Leave an unchanged bundle's mtime alone so that ninja (GN actions are
// restat) does not regenerate and recompile electron_natives.cc for it.
const outputFile = path.resolve(args['output-path'], outputFilename);
if (!fs.existsSync(outputFile) || fs.readFileSync(outputFile, 'utf8') !== code) {
  fs.writeFileSync(outputFile, code);
}

GN 的 action 默认是 restat = 1:如果输出文件没变,下游不重跑。但如果无条件写文件,mtime 会变,ninja 认为输出变了,于是 electron_natives.cc 重编、整个二进制重链。一次重链在 Electron 这种规模上是分钟级。

所以:内容一样就不写。用一次文件读取换一次重链。

typecheck.mjs:34-36 里也有对称的一手:

// An existing stamp is left untouched: its dependents only need to rebuild when
// their own sources change, and ninja (GN actions are restat) can then tell.
if (args.stamp && !fs.existsSync(args.stamp)) {
  fs.mkdirSync(path.dirname(args.stamp), { recursive: true });
  fs.writeFileSync(args.stamp, '');
}

stamp 文件存在就不动。两个地方,同一个思路:在 GN 的 restat 语义下,"没变"必须表现为"没写"。


8.4.5 体量倒挂:5 个文件的 node bundle

node_bundle_deps 只有 5 项:

2493  lib/node/asar-fs-wrapper.ts
  93  lib/node/init.ts
 159  package.json
  11  tsconfig.electron.json
  25  tsconfig.json

三个是配置文件,真正的代码只有两个文件、2,586 行。而 browser_bundle_deps 有 65 项、6,484 行代码(其中最大的是 net-client-request.ts 570 行)。

按文件数,browser 是 node 的 13 倍;按行数,只有 2.5 倍。这个倒挂说明一件事:模块图的节点数不反映体量,asar-fs-wrapper.ts 一个文件就顶得上 40 个普通模块。

它不是"一个小 hook"。2,493 行,重写了 fs 的绝大多数入口:stat/lstat/readdir/readFile/open/read/writeFile/copyFile/realpath/createReadStream,以及 fs.promises 那一整套。为什么必须这么大,8.12.1 会讲。


8.5 构建期代码缓存:把 V8 的编译结果也烤进二进制

8.5.1 问题:js2c 解决了"在哪",没解决"多慢"

js2c 把 JS 放进二进制,省掉了文件 IO 和 asar 解析。但 V8 拿到字节数组之后,仍然要做完整的 parse + compile:词法、语法、作用域分析、字节码生成。一个 browser_init bundle 压缩前是几百 KB 的 JS,冷编译成本在几十毫秒量级。

V8 有 code cache 机制:编译一次,把字节码序列化存起来,下次直接反序列化。传统的用法是存磁盘(--cache=code),但 Electron 的框架代码在主进程启动的最前面跑,等不及磁盘 IO,也没有"第一次启动预热"的机会。

所以 Electron 45 做了一件更彻底的事:在构建期就把 code cache 生成好,跟着二进制一起发布。

8.5.2 五个 flavor:为什么不能只有一份缓存

V8 的 code cache key 包含两个容易忽略的东西:

node_natives_code_cache.h:19-24

// shell/common/node_natives_code_cache.h
// V8's code cache key includes the non-default flag set and the snapshot's
// read-only checksum, both of which differ per process type, so one cache
// variant is generated per flavor and each process consumes the matching one.
enum class Js2cCacheFlavor {
  kSandbox,   // sandboxed renderer (no Node env)
  kRenderer,  // normal renderer
  kBrowser,
  kUtility,
  kWorker,
};
  • 非默认 V8 flag 集合。渲染进程的 V8 flag 与主进程不同(比如 --expose-gc、--js-flags 传入的东西),flag 集合参与 hash;
  • 快照的 read-only heap 校验和。主进程的 isolate 从 Node 的启动快照反序列化而来,快照不同,校验和不同。

一份缓存只对一个 (flag 集合, 快照) 组合有效。所以必须按 flavor 分别生成,运行时按当前进程挑对应的那份。选 flavor 的逻辑在 node_natives_code_cache.cc:15-22:

Js2cCacheFlavor CurrentProcessJs2cCacheFlavor(bool has_node_env) {
  if (IsBrowserProcess() || IsUtilityProcess()) {
    if (JavascriptEnvironment::NodeSnapshot())
      return Js2cCacheFlavor::kBrowser;
    const bool build_embeds_node_snapshot =
        node::SnapshotBuilder::GetEmbeddedSnapshotData() != nullptr;
    return IsUtilityProcess() || build_embeds_node_snapshot
               ? Js2cCacheFlavor::kUtility
               : Js2cCacheFlavor::kBrowser;
  }
  if (IsRendererProcess()) {
    // No Node env means the V8 flag set stays frozen -- a distinct flavor.
    return has_node_env ? Js2cCacheFlavor::kRenderer : Js2cCacheFlavor::kSandbox;
  }
  return Js2cCacheFlavor::kWorker;
}

渲染进程那两行注释是本章最精确的一句技术说明:沙箱渲染进程没有 Node 环境,所以 V8 的 flag 集合"保持冻结"。有 Node 的渲染进程里,Node 的初始化可能追加 V8 flag;没有 Node 的进程里没人动 flag,flag 集合就是启动时那一份。两种情况的 hash 不同,必须分开。

主进程那一段更绕,因为要处理三种构建形态(嵌入 Node 快照 / 不嵌入 / 用户自定义 V8 快照)。分支的最终效果是:挑一个与当前 isolate 的 flag 集合和快照校验和都匹配的 flavor;挑不到就用一个"少一个 bundle"的 flavor,让它退化成源码编译。

8.5.3 每个 flavor 编哪几个 bundle

electron_natives_codecache_main.cc:49

std::vector<Bundle> BundlesForFlavor(std::string_view flavor, bool from_node_snapshot) {
  if (flavor == "sandbox")    return {kWebView, kIsolated};
  if (flavor == "renderer")   return {kRendererInit, kNodeInit, kIsolated};
  if (flavor == "browser" && from_node_snapshot) return {kBrowserInit, kUtilityInit, kNodeInit};
  if (flavor == "browser")    return {kBrowserInit, kNodeInit};
  if (flavor == "utility")    return {kUtilityInit, kNodeInit};
  if (flavor == "worker")     return {kWorkerInit, kNodeInit};
  return {};
}

整理成表:

flavorbrowser_initrenderer_initworker_initutility_initnode_initwebviewisolated
sandbox✓✓
renderer✓✓✓
browser (有 Node 快照)✓✓✓
browser (无 Node 快照)✓✓
utility✓✓
worker✓✓*

(*worker 一行不含 isolated:worker 进程不走 RendererClientBase::DidCreateScriptContext,只有渲染进程的 worker 线程宿主才会。)

三处值得注意:

第一,node_init 出现在几乎所有 flavor 里。 它是 ASAR 支持、child_process.fork 钩子、Module._nodeModulePaths 收窄的载体(8.12),每个跑用户代码的进程都需要它。

第二,browser flavor 在"有 Node 快照"时额外编 utility_init。 因为那时 utility 进程的 isolate 是从同一份 Node 快照反序列化的,flag 集合与主进程相同,可以共用主进程那份缓存。注释写得很清楚:

// On builds that embed a Node startup snapshot the browser flavor is keyed to
// the isolate that snapshot produces and serves every process created from it,
// which includes the node service's utility process.

第三,sandbox flavor 只有两个 bundle。 沙箱渲染进程连 renderer_init 都不跑——它的初始化完全由 C++ 侧的 ElectronSandboxedRendererClient 手工搭出来(8.7.3)。所以只需要 <webview> 元素实现和隔离世界那半份。

8.5.4 生成工具:在构建机上重演一次启动

electron_natives_codecache_main.cc:148-154 是一个宿主工具(host tool),在构建机上跑,不在用户机器上跑。它做的事,本质上是"在构建机上模拟一次进程启动,把编译结果录下来":

v8::V8::InitializeExternalStartupDataFromFile(snapshot_blob_path.c_str());
if (!v8_flags.empty())
  v8::V8::SetFlagsFromString(v8_flags.c_str(), v8_flags.size());

const node::SnapshotData* node_sd = node::SnapshotBuilder::GetEmbeddedSnapshotData();
const bool from_node_snapshot = node_sd != nullptr;
if (from_node_snapshot)
  node::SnapshotBuilder::InitializeIsolateParams(node_sd, &create_params);

第一步加载快照 blob,第二步设置这个 flavor 的 V8 flag,第三步(如果链接了真实快照)从快照建 isolate。第三步的注释是整段代码里最重要的一处:

// Building the cache here, against the shipped snapshot, is the only way its
// read-only checksum matches the runtime browser isolate.

必须用"最终会发布的那份快照"来建 isolate。 如果构建工具自己现造一个快照,read-only heap 的校验和与用户机器上的不同,所有缓存全部失效——而且失效是静默的(V8 检测到不匹配就回退到源码编译),没有任何报错。

然后逐个 bundle 编译:

electron_natives_codecache_main.cc:197-202

loader.SetEagerCompile();
for (const auto& b : BundlesForFlavor(flavor, from_node_snapshot)) {
  loader.LookupAndCompileFunction(context, b.id, &params, /*optional_realm=*/nullptr);
  std::unique_ptr<v8::ScriptCompiler::CachedData> cd(
      v8::ScriptCompiler::CreateCodeCacheForFunction(fn));
  caches.emplace_back(b.id, std::vector<uint8_t>(cd->data, cd->data + cd->length));
}

SetEagerCompile() 是关键的一行。默认情况下 V8 只编译顶层函数,内层函数在第一次调用时才编译(惰性编译)。但框架 bundle 的特点是"启动时全部跑一遍",所以惰性编译最终也会发生。SetEagerCompile 把这一步提前到构建期,让缓存覆盖整个 bundle 的每一个内层函数。

代价是缓存体积变大;收益是运行期一次编译都不会发生。

8.5.5 Node 自己的 builtins:另一半 12MB

framework bundle 之外,工具还处理 Node 的内置模块:

electron_natives_codecache_main.cc:243-249

if (with_node_builtins && !from_node_snapshot) {
  node::builtins::BuiltinLoader node_loader;
  std::vector<node::builtins::CodeCacheInfo> node_caches;
  node_loader.CompileAllBuiltinsAndCopyCodeCache(context, /*eager_builtins=*/{}, &node_caches);
  for (const auto& info : node_caches) {
    if (!ShouldCacheNodeBuiltin(info.id)) continue;
    caches.emplace_back(info.id, ...);
  }
}

条件 !from_node_snapshot 值得注意:如果进程的 isolate 是从 Node 启动快照反序列化来的,Node 的 builtins 已经在快照里带着缓存了,不用再生成。只有从零 bootstrap 的进程(每个渲染进程、每个 web worker、无快照构建下的 utility)才需要这份缓存,否则要现场编译 120–140 个内置模块。

排除规则:

electron_natives_codecache_main.cc:93-97

bool ShouldCacheNodeBuiltin(std::string_view id) {
  constexpr std::string_view kJs2cPrefix = "internal/electron/js2c/";
  constexpr std::string_view kDepsPrefix = "internal/deps/";
  return id.substr(0, kJs2cPrefix.size()) != kJs2cPrefix &&
         id.substr(0, kDepsPrefix.size()) != kDepsPrefix;
}

两个前缀被排除:

  • internal/electron/js2c/:这些 id 也是注册过的 builtins,但这一轮是用 Node 的默认参数编译的,而 Electron 的 bundle 需要自己的参数(process, require)。混进来会生成错误参数的缓存条目,把上面正确的那份覆盖掉。
  • internal/deps/:undici、acorn、amaro、minimatch 这些打包进来的第三方库,启动路径上一个都不用,按需加载。注释给了量化理由:
// ... would roughly double the per-flavor cache (~5.5 of ~12 MB) for no
// startup benefit.

5.5MB / 12MB。将近一半的缓存体积来自启动时根本不加载的代码,所以砍掉。

还有一个细节:这第二轮用的是另一个不带 SetEagerCompile 的 loader,理由是"让 eagerness 策略与 node_mksnapshot 一致"——per_context / bootstrap / main 这类脚本急切编译,其余只编顶层。同一个进程里两个 loader、两种策略,因为它们服务的代码有不同的生命周期。

8.5.6 运行时:三处注入,一个覆盖顺序

缓存生成了,得让运行时用上。三个注入点:

第一处,进程级默认缓存。

node_util.cc:88

void InstallProcessCodeCache() {
  static const bool installed = [] {
    const auto& cache = GetNativesCodeCache(CurrentProcessJs2cCacheFlavor());
    if (!cache.empty())
      node::builtins::BuiltinLoader::SetProcessDefaultCodeCache(&cache);
    return true;
  }();
  (void)installed;
}

SetProcessDefaultCodeCache 是 Node 的静态方法:之后创建的每个 BuiltinLoader 都默认带这份缓存。一次性、幂等(static 初始化)。

第二处,bundle 专用 loader。

node_util.cc:25

v8::MaybeLocal<v8::Function> CompileBundle(v8::Local<v8::Context> context,
                                          const char* id,
                                          v8::LocalVector<v8::String>* parameters) {
  static base::NoDestructor<base::ThreadLocalOwnedPointer<node::builtins::BuiltinLoader>> builtin_loader;
  if (!builtin_loader->Get()) {
    auto loader = std::make_unique<node::builtins::BuiltinLoader>();
    const bool has_node_env = node::Environment::GetCurrent(context) != nullptr;
    const auto& cache = GetNativesCodeCache(CurrentProcessJs2cCacheFlavor(has_node_env));
    if (!cache.empty())
      loader->RefreshCodeCache(cache);
    builtin_loader->Set(std::move(loader));
  }
  return builtin_loader->Get()->LookupAndCompileFunction(context, id, parameters, node::Realm::GetCurrent(context));
}

thread_local 是必须的:一个进程里可能有多个 isolate(渲染进程 + worker,或多 frame 的隔离世界),BuiltinLoader 内部有按 isolate 的编译产物,不能跨线程共享。

has_node_env 参数说明 flavor 判定要在拿到 context 之后做——沙箱和普通渲染进程的唯一区别就是当前 context 有没有 node::Environment。

第三处,最微妙的一处:环境级缓存,以及覆盖顺序。

node_bindings.cc:1006

void NodeBindings::LoadEnvironment(node::Environment* env) {
  // Re-assert Electron's build-time cache for the internal/electron/js2c/*
  // framework bundles (browser_init etc.). Every BuiltinLoader already starts
  // from it (InstallProcessCodeCache), but when booting from the Node startup
  // snapshot Environment's constructor then merges the caches node_mksnapshot
  // embedded for the same bundle ids over it; RefreshCodeCache uses
  // insert_or_assign, so this puts the build-time (eagerly compiled) entries
  // back on top while the node-internal entries are kept.
  electron::util::FeedEnvironmentCodeCache(env);
  ...

这段话描述了一个隐蔽的冲突:node_mksnapshot 在造启动快照时,也把 internal/electron/js2c/* 这些 id 编了一遍(因为它们注册成了 builtins),并把缓存塞进了快照。进程从快照启动时,Environment 构造函数会把快照里的缓存合并进来——用 insert_or_assign,也就是覆盖同名条目。

于是构建期那份"用正确参数、eager 编译"的缓存,被快照里那份"用默认参数、非 eager"的缓存盖掉了。表现是:缓存还在,但不匹配,V8 静默回退到源码编译。

解法就是第一行的 FeedEnvironmentCodeCache(env):在 node::LoadEnvironment 之前,把构建期那份重新盖回去。 由于 insert_or_assign 的语义,后来的赢——这次是 Electron 赢。

一行调用,恢复了整个缓存机制。如果没有这行,缓存生成的工程量白做,而且没有任何报错,只有启动慢几十毫秒。这类 bug 是性能工程里最难查的一类:功能正确、指标下降、无日志。

8.5.7 用测试替代类型系统

参数名、id、flavor 三者的一致性,编译器一概管不了。所以有一条专门的测试:

api-js2c-code-cache.spec.ts:70-74

// spec/api-js2c-code-cache.spec.ts
expectConsumed(r.browser, 'internal/electron/js2c/browser_init');
expectConsumed(r.browser, 'internal/electron/js2c/node_init');
expectConsumed(r.sandbox, 'internal/electron/js2c/webview_bundle');
expectConsumed(r.renderer, 'internal/electron/js2c/renderer_init');
expectConsumed(r.utility, 'internal/electron/js2c/utility_init');

怎么验证"缓存被消费了"?靠 fixture 应用里读 V8 的内部状态(isTestingBindingAvailable() 门控),把每个 id 的命中情况打成一个 JSON,父进程解析。

最值得注意的是测试为什么要另起进程:

// Runs in a separately-spawned app: spec/index.js injects --js-flags=--expose_gc
// suite-wide which changes V8's FlagList::Hash, so the production-flavor cache
// would (correctly) be rejected if run inside the spec runner.

测试框架自己会给 V8 加 --expose-gc。加了 flag,FlagList::Hash 变了,缓存的 key 变了,缓存应该失效。所以这个测试不能在测试进程内跑——它必须 spawn 一个不带那些 flag 的干净进程。

这段注释同时是一份文档:它告诉读者"V8 flag 集合是缓存 key 的一部分"这条规则在实践中意味着什么。一个测试的设计,反过来解释了系统的约束。


8.6 运行时装载:CompileBundle 与它的两个调用者

8.6.1 一次完整的装载

node_bindings.cc:1027

const std::string bundle_id =
    "internal/electron/js2c/" + std::string(ProcessType()) + "_init";
node::LoadEnvironment(env,
    [&](const node::StartExecutionCallbackInfo& info) {
      v8::LocalVector<v8::String> params = js2c::MakeBundleParams(isolate, js2c::kInitBundleParams);
      v8::Local<v8::Value> args[] = {info.process_object, require};
      v8::Local<v8::Function> bundle;
      if (!electron::util::CompileBundle(context, bundle_id.c_str(), &params).ToLocal(&bundle)) {
        return v8::MaybeLocal<v8::Value>();
      }
      return bundle->Call(context, v8::Null(isolate), std::size(args), args);
    }, &OnNodePreload);

六个动作,每个都有讲究:

① id 是拼出来的,不是常量。 "internal/electron/js2c/" + ProcessType() + "_init"。ProcessType() 返回 "browser" / "renderer" / "worker" / "utility" 之一。所以 js2c_bundle_ids.h:29 里那四个 kBrowserInitId、kRendererInitId、kWorkerInitId、kUtilityInitId 在运行时的这条路径上一次都没被用到——它们只服务于构建期的 code cache 工具。

这是个不对称设计:常量是给构建工具用的,运行时用拼字符串。后果是:如果 ProcessType() 的返回值与文件名不一致(比如哪天改名 worker → web_worker),运行时会拿到一个不存在的 id,CompileBundle 返回空,启动失败;而编译器一句话都不会说。防线只有两条:spec/api-js2c-code-cache.spec.ts 里逐个 id 的存在性断言,以及启动时的 LOG(ERROR) << "Failed to compile electron script"。

② info.process_object 是 Node 给的,不是自己造的。 LoadEnvironment 的回调收到 StartExecutionCallbackInfo,里面是 Node 已经建好的 process 与 require。Electron 不重新造一个 process,而是把 Node 的这个直接传给 bundle。所以 bundle 里的 process 与用户代码里的 process 是同一个对象——这也是为什么 lib/browser/init.ts 能直接改 process.exit 而用户代码立刻受影响。

③ 没有 v8::TryCatch。 注释:

// The init bundle is this process's entry script: like Node's own runMain it
// runs without a v8::TryCatch, so an exception thrown while it loads the app
// reaches process.on('uncaughtException') through V8's message listener.

如果这里加了 TryCatch,init 里抛的异常会被 C++ 吞掉,用户注册的 process.on('uncaughtException') 永远收不到。Electron 要的是"init 就是入口脚本",入口脚本的异常该走正常的未捕获异常通道。

对照 CompileAndCall(另一个调用者),它有 TryCatch:

node_util.cc:53

v8::MaybeLocal<v8::Value> CompileAndCall(...) {
  v8::TryCatch try_catch{isolate};
  ...
  if (try_catch.HasCaught()) {
    std::string msg = "no error message";
    ...
    LOG(ERROR) << "CompileAndCall failed to evaluate electron script (" << id << "): " << msg;
  }

分工很清楚:入口脚本不设防(异常必须冒出去),辅助脚本设防(异常记日志,不能污染上层)。 CompileAndCall 服务的是 node_init、webview_bundle、isolated_bundle 这三个"辅助" bundle。

④ break_first_line 的掩码。 --inspect-brk 的本意是"在用户代码第一行断住"。但如果 Node 在跑 embedder 入口之前就断住,断点会落在 bundle 的第一行('use strict';),用户看到的是一堆框架代码。所以:

node_bindings.cc:1025-1029

const bool break_first_line = debug_options->break_first_line;
debug_options->break_first_line = false;
...
if (break_first_line) {
  debug_options->break_first_line = true;
  RefreshCachedNodeOptions(context, require);
}

先收起来,等 bundle 开始跑之前再放回去,并刷新 JS 侧缓存的 options(internal/options 的 refreshOptions)。用户按"继续"之后,断点落在应用自己的 main 脚本上。

这个细节说明一件事:"入口脚本"这个概念在 Electron 里有两层——框架 bundle 是 Node 眼里的入口,应用的 main 是用户眼里的入口。调试器默认断在前者,必须手工把它推到后者。

⑤ EmitEvent(..., "loaded")。 LoadEnvironment 的最后一行:

node_bindings.cc:1052

gin_helper::EmitEvent(env->isolate(), env->process_object(), "loaded");

bundle 跑完,process 上发一个 loaded 事件。第 7 章讲过这个事件的用途:contextBridge / ipcRenderer 的延迟初始化靠它触发。它同时也是"框架已经就位"的信号。

8.6.2 三个调用点,两种语义

全仓库 CompileBundle 只有一个调用者(LoadEnvironment),CompileAndCall 有三个:

调用点bundle语义
node_bindings.cc:1257node_init装 ASAR / fork 钩子 / 路径收窄,返回值忽略
electron_sandboxed_renderer_client.cc:132webview_bundle在隔离世界注册 <webview>,参数 binding
renderer_client_base.cc:735isolated_bundle在主世界装 <webview> 元素,参数 isolatedApi

注意 LoadEnvironment 用的是 CompileBundle + 手工 fn->Call(),而不是 CompileAndCall。差别就是那个 TryCatch。同一个底层能力,两种异常策略,用两个函数暴露。 这比在一个函数里加 bool catch_exceptions 参数干净——布尔参数在调用点读起来是无意义的 true/false。


8.6.3 为什么是 BuiltinLoader,而不是 v8::Script::Compile

js2c 产出的是一段字节。最直接的做法是 v8::Script::Compile 一个 v8::String,然后 Run()。Electron 没有这么做,而是绕道 Node 的 node::builtins::BuiltinLoader。四个理由:

① id 到源码的映射已经存在。 js2c 生成的表就是 name → bytes,BuiltinLoader 的构造函数会 self-register 全部 builtins。自己 Compile 的话,得另写一张表去查"这个 id 对应哪段字节"。

② code cache 的挂载点是现成的。 RefreshCodeCache / SetProcessDefaultCodeCache 都是 BuiltinLoader 的接口(8.5.6)。自己 Compile 就要自己管 CachedData,还要自己保证 key 一致。

③ realm 支持。 LookupAndCompileFunction(context, id, params, node::Realm::GetCurrent(context))。Node 的 Realm 抽象让同一个 bundle 可以在不同 realm 里编译出独立的函数实例——渲染进程的多个隔离世界需要这个。

④ 与 Node 的 builtins 共用一条加载路径。 LoadEnvironment 传给 bundle 的 require 是 env->principal_realm()->builtin_module_require(),它认识的 id 空间就是 BuiltinLoader 的 id 空间。所以 bundle 里 require('internal/modules/helpers') 能直接工作——这不是 Electron 实现的能力,是"寄生"在 Node 加载器上得到的能力。

第四点最关键。如果 Electron 自己 Compile,就得自己实现一个 require 去服务 internal/* 请求;用了 BuiltinLoader,这一切免费。代价是 bundle 必须活成"一个 Node 内置模块"的样子:有 internal/ 前缀的 id,接受 (process, require) 这样的参数。8.6.1 讲的"id 是拼出来的",根子在这里。


8.7 七个 bundle 的进场时刻

把七个 bundle 放进时间轴,才能看清它们各自解决什么问题。

bundle何时执行调用者参数之前发生过什么
browser_init主进程 Node 环境建立后NodeBindings::LoadEnvironment(process, require)Chromium 启动完成、app 对象已建、package.json 已解析
renderer_init渲染进程 Node 环境建立后同上(ProcessType()=="renderer")同上Blink 已创建 context、preload 路径已推入
worker_initNode worker 线程环境建立后同上("worker")同上worker 的 isolate 已建、self.location 可用
utility_initutility 进程 Node 环境建立后同上("utility")同上入口脚本路径已通过 hidden value 传入
node_init每次 Node 环境建立后追加NodeBindings::RegisterBuiltinBindings 末尾同上browser/renderer/worker/utility_init 已跑完
webview_bundle沙箱渲染进程创建文档时ElectronSandboxedRendererClient::DidCreateScriptContext(binding)已建 process/electron 假对象
isolated_bundle任意渲染进程(开 contextIsolation)RendererClientBase::DidCreateScriptContext(isolatedApi)隔离世界已建、isolatedApi 已注入

8.7.1 node_init 为什么是"追加"

前四个 bundle 是互斥的:一个进程只会跑其中一个。node_init 不是——它在每一个跑 Node 的进程里都会跑一次,紧跟在那个进程的 *_init 之后。

它的四个职责(8.12 展开)都与"Node 的默认行为不符合 Electron 的需要"有关:ASAR 支持、fork 的环境注入、模块搜索路径收窄、Linux 上 crashpad 的 fd 传递。这四件事都必须发生在用户代码之前、框架代码之后。

8.7.2 <webview> 为什么需要两个 bundle

<webview> 是一个自定义元素,但它的实现横跨两个世界:

  • 主世界(页面的世界):要有 HTMLElement 子类、要有 connectedCallback、要能被 document.createElement('webview') 创建。这部分在 isolated_bundle 里,通过 isolatedApi 参数拿到与浏览器进程通信的通道。
  • 隔离世界(Electron 的世界):要处理 WebViewImpl 的状态机、要转发事件、要管 guest 实例。这部分在 webview_bundle 里,通过 binding 参数拿 _linkedBinding。

为什么必须分开?因为主世界的代码是页面可以改的。如果状态机跑在主世界,页面只要 WebView.prototype.attachGuest = () => {} 就能劫持。所以真正干活的逻辑被关在隔离世界,主世界只有一个薄壳。

两个 bundle 的参数名也不同(isolatedApi vs binding),因为它们需要的能力不同:主世界那半需要"与 C++ 通信的完整通道",隔离世界那半只需要"取绑定"。

8.7.3 沙箱渲染进程没有 renderer_init

这是最容易搞错的一点。lib/renderer/init.ts:29-35 里那一大堆逻辑(改 Module.wrapper、装 preload、删全局、重定向 window.onerror)只在有 Node 的渲染进程里跑。

沙箱渲染进程的初始化是纯 C++ 的:

// electron_sandboxed_renderer_client.cc
ElectronSandboxedRendererClient::SetUpPreloadEnvironment(...) {
  ...
  v8::Local<v8::Object> preload_process = preload_environment::CreateProcessObject(context, process, startup_data);
  v8::Local<v8::Object> electron_module = preload_environment::CreateElectronModule(context, preload_environment::Flavor::kRenderer);
  preload_environment::RunPreloadScripts(context, render_frame, nullptr, preload_process, electron_module, ...);
}

CreateElectronModule 是 module-list 的C++ 版本:

v8::Local<v8::Object> CreateElectronModule(v8::Context, Flavor flavor) {
  v8::Local<v8::Object> module = v8::Object::New(isolate);
  for (size_t i = 0; i < kModules.size(); ++i) {
    if (kModules[i].renderer_only && flavor != Flavor::kRenderer) continue;
    module->SetLazyDataProperty(context, gin::StringToSymbol(isolate, kModules[i].name),
                                ModuleGetter, v8::Integer::New(isolate, i),
                                v8::ReadOnly | v8::DontDelete).Check();
  }
  return module;
}

同一件事,两种实现:JS 版用 Object.defineProperties + getter 闭包,C++ 版用 SetLazyDataProperty + 整数索引。后者更省内存(没有闭包),但需要一张 C++ 侧的模块表。

这解释了一个常见困惑:为什么沙箱 preload 里 require('electron') 能用,但它不是 Node 的 require? 因为沙箱里的 require 是 preload 环境手工给的函数,'electron' 被特判成返回这个 C++ 造的对象。它不是模块系统的产物,是一个查表结果。


8.8 注册表一:process._linkedBinding 的字符串契约

8.8.1 一个前缀,一个世界

process._linkedBinding('electron_browser_app')      // 主进程:有
process._linkedBinding('electron_common_v8_util')   // 各进程:有
process._linkedBinding('electron_renderer_ipc')     // 主进程:No such binding

三段式命名:electron_<进程域>_<模块名>。进程域是 common / browser / renderer / utility,模块名是全小写下划线。

第 7 章数过:56 个 NODE_LINKED_BINDING_CONTEXT_AWARE 注册点(37 browser / 12 common / 5 renderer / 2 utility)。这个数字与 module-list 的 52 个条目(42 + 6 + 4)不相等,因为:

  • 有些绑定注册了但没进 module-list(比如 electron_browser_event_emitter,它只被 init.ts 用来装原型);
  • module-list 的一个条目可能对应一个绑定里的一个属性(electron_browser_image_view 提供 ImageView,electron_browser_view 提供 View);
  • 有些条目(如 app)是"薄壳模块",app.ts 全文两行:const { app } = process._linkedBinding('electron_browser_app'); export default app;。

所以两个数字不必相等,它们的对应关系是多对多。

8.8.2 为什么前缀重要:权限模型撞上了注册表

fix_allow_electron_s_linked_bindings_under_the_permission_model.patch:6-13 讲了一个很能说明问题的故事:

https://github.com/nodejs/node/pull/65432 made process._linkedBinding()
throw ERR_ACCESS_DENIED when the permission model is enabled without
--allow-addons. Electron exposes all of its built-in modules to JS as
linked bindings (electron_common_*, electron_browser_*, ...), and its
own bootstrap script (node_init and friends) reaches them through
process._linkedBinding(), so with that change `electron --permission`
in ELECTRON_RUN_AS_NODE mode can no longer initialise Electron's Node.js
integration (ASAR support etc.) and logs a CompileAndCall error.

Node 20+ 的权限模型把 linked binding 视为 addon 的一种,没有 --allow-addons 就拒绝。Electron 把所有内置模块都做成了 linked binding,于是 --permission 模式下连自己的 bootstrap 都跑不起来。

补丁的解法是按前缀豁免:

-  THROW_IF_INSUFFICIENT_PERMISSIONS(env, permission::PermissionScope::kAddon, module_name_v.ToStringView());
+  if (!module_name_v.ToStringView().starts_with("electron_")) {
+    THROW_IF_INSUFFICIENT_PERMISSIONS(env, permission::PermissionScope::kAddon, module_name_v.ToStringView());
+  }

理由写在补丁说明里:

fix_allow_electron_s_linked_bindings_under_the_permission_model.patch:15-18

In an Electron build the linked-binding list only ever contains
Electron's own runtime modules; applications cannot link bindings into
the binary and real native addons still go through process.dlopen(),
which remains gated on --allow-addons.

这段话精确地描述了注册表的边界:这个链表里只可能有 Electron 自己的东西。用户装上来的原生模块走 process.dlopen,是另一条路。所以"electron_ 前缀"不只是一个命名约定,它是一个可被权限系统依赖的不变量。

如果不遵守这个前缀,后果不是"名字难看",而是"权限模型下 bootstrap 失败"。命名在这个系统里是可执行的语义。

8.8.3 三个入口,一个函数

同一个注册表,有三种取法:

入口进程实现错误信息
process._linkedBinding(name)主进程 / 有 Node 的渲染、worker、utilityNode 的 GetLinkedBindingNo such binding 之类,由 Node 抛
process._linkedBinding(name)沙箱渲染进程preload_utils::GetBindingNo such binding: <name>
binding.get(name)沙箱 bundle 内部同上同上

沙箱那份实现只有 30 行:

// shell/renderer/preload_utils.cc
v8::Local<v8::Value> GetBinding(v8::Isolate* isolate, v8::Local<v8::String> key) {
  const std::string binding_key = gin::V8ToString(isolate, key);
  gin_helper::Dictionary cache(isolate, GetBindingCache(isolate));
  if (cache.Get(binding_key, &exports)) return exports;

  auto* const mod = NodeBindings::GetLinkedBinding(binding_key);
  if (!mod) {
    gin_helper::ErrorThrower{isolate}.ThrowError(base::StrCat({"No such binding: ", binding_key}));
    return exports;
  }

  exports = v8::Object::New(isolate);
  DCHECK_EQ(mod->nm_register_func, nullptr);
  DCHECK_NE(mod->nm_context_register_func, nullptr);
  mod->nm_context_register_func(exports, v8::Null(isolate), isolate->GetCurrentContext(), mod->nm_priv);
  cache.Set(binding_key, exports);
  return exports;
}

四个细节:

① 抓不到就直接抛,不返回 undefined。 沙箱里的命名错误会立刻炸,而不是留到后面变成 undefined.foo 的 TypeError。

② 结果被缓存,缓存挂在全局的 hidden value 上("native-binding-cache")。所以同一个绑定在一个 context 里只会注册一次,instanceof 关系稳定。

③ 两个 DCHECK 划出了边界:只接受 context-aware 的注册函数(nm_context_register_func),不接受 legacy 的(nm_register_func)。因为沙箱里的绑定需要当前 context 才能建对象。

④ 它绕过了 Node 的 Environment,直接调 NodeBindings::GetLinkedBinding。沙箱进程里没有 node::Environment,所以不能走 Node 的那条路——但注册表是进程级的静态链表,不依赖 Environment,所以能直接查。

这就是"注册表"这个词的确切含义:它不是 Node 的模块系统的一部分,它是一个 C 链表 + 一个宏。 Node 的 process._linkedBinding 只是这张链表的一个读接口。


8.8.4 一个反例:electron_browser_event_emitter 在 utility 里也能取

lib/utility/init.ts 第 29 行:

process._linkedBinding('electron_browser_event_emitter').setEventEmitterPrototype(EventEmitter.prototype);

名字里写着 browser,但调用发生在 utility 进程。这不是笔误,同一行在 lib/browser/init.ts 第 12 行也出现过。

它说明:前缀是标签,不是强制边界。 注册表本身没有"进程域"这个概念——NODE_LINKED_BINDING_CONTEXT_AWARE(electron_browser_event_emitter, ...) 只是把函数指针挂进进程的链表,链表中所有条目对当前进程可见。所谓"browser 模块在渲染进程里取不到",是因为那些 .cc 文件没有被链接进渲染进程的可执行体(shell/browser/ 的目标只依赖 browser 侧),而不是因为注册表做了过滤。

这个区分很重要:

  • 链接期隔离:模块根本没进这个二进制 → No such binding;
  • 注册表过滤:模块在,但按进程域拒绝 → 不存在这种机制。

所以 electron_browser_event_emitter 能被 utility 取到,只因为它被链接进了 utility 目标。而 electron_browser_app 在渲染进程里取不到,是因为 electron_api_app.cc:2274 不在渲染进程的依赖里。边界由构建图决定,不由命名决定。

这也能解释 8.8.2 那个补丁为什么敢按前缀豁免权限检查:前缀虽然不强制,但构建图强制——一个 electron_ 开头的名字,来源只可能是 Electron 自己的目标。


8.9 注册表二:module-list 与惰性 getter

8.9.1 四张表,52 个条目

lib/common/api/module-list.ts    2 项:nativeImage、shell
lib/browser/api/module-list.ts  40 项:app … webFrameMain
lib/renderer/api/module-list.ts  6 项:contextBridge、crashReporter、ipcRenderer、
                                     sharedTexture、webFrame、webUtils
lib/utility/api/module-list.ts   4 项:LanguageModelUtility、localAIHandler、net、systemPreferences

组合规则(exports/electron.ts:5-7):

// lib/browser/api/exports/electron.ts
module.exports = {};
defineProperties(module.exports, commonModuleList);
defineProperties(module.exports, browserModuleList);

lib/renderer/api/exports/electron.ts:5-7

// lib/renderer/api/exports/electron.ts
module.exports = {};
defineProperties(module.exports, commonModuleList);
defineProperties(module.exports, rendererModuleList);
// lib/utility/api/exports/electron.ts
module.exports = {};
defineProperties(module.exports, utilityNodeModuleList);   // 注意:不含 common

三行差异里藏着一条信息:utility 进程不共享 common 表。 所以 utility 进程里没有 nativeImage 和 shell——它连 require('electron') 的完整形态都不需要,只给自己那四个模块(其中 systemPreferences 还是从 browser 目录借的)。

8.9.2 defineProperties:一次调用,一堆 getter

define-properties.ts:22-28

// lib/common/define-properties.ts
export function defineProperties(targetExports: Object, moduleList: ElectronInternal.ModuleEntry[]) {
  const descriptors: PropertyDescriptorMap = {};
  for (const module of moduleList) {
    descriptors[module.name] = {
      enumerable: true,
      get: handleESModule(module.loader)
    };
  }
  return Object.defineProperties(targetExports, descriptors);
}

三个决定:

① 用 Object.defineProperties(复数)而不是循环 defineProperty。 前者是一次 V8 调用,后者是 N 次。对一个 40 项的表,这是 40 倍的跨语言调用差距。而且 PropertyDescriptorMap 一次性传入,V8 可以做批量 map transition。

② configurable 没写,默认 false。 所以 require('electron').app 一旦被读取,不能重新定义。这防止了用户代码 Object.defineProperty(require('electron'), 'app', ...) 劫持框架——但也意味着测试里想 stub 一个还没读过的属性可以,读过之后就不行了。

③ enumerable: true。 Object.keys(require('electron')) 能列出全部名字。这一点对 Electron 很重要:大量工具(打包器、依赖分析器、jest 的 automock)靠 Object.keys 判断一个模块导出什么。

8.9.3 handleESModule:为 webpack 遗留问题写的一段代码

define-properties.ts:1-8

const handleESModule = (loader: ElectronInternal.ModuleLoader) => {
  let resolved: any;
  return () => {
    if (resolved !== undefined) return resolved;
    const value = loader();
    if (!value.__esModule) {
      resolved = value;
    } else if (value.default) {
      resolved = value.default;
    } else {
      // require() of a bundled ES module returns a fresh, read-only copy of
      // its namespace on every call; settle on a single plain object instead so
      // that the module keeps its identity and its exports can be replaced
      // (e.g. stubbed out by tests) like those of any CommonJS module.
      resolved = { ...value };
    }
    return resolved;
  };
};

三分支对应三种模块形态:

  • 普通 CJS(!value.__esModule):直接用 module.exports;
  • 有默认导出的转译 ESM(value.default):取 .default——这是 export default app 那种写法;
  • 只有具名导出的转译 ESM(无 default):拷贝成一个新对象。

第三个分支的注释解释了原因:打包器产出的 ESM namespace 是只读的,每次 require 还是一个新的副本。两个问题:

  1. 身份不稳定:require('electron').x !== require('electron').x,instanceof 和 WeakMap 都会出错;
  2. 不可替换:只读,测试没法 stub。

{ ...value } 一次拷贝同时解决两个问题:得到一个普通可写对象,且被 resolved 缓存住,身份稳定。

一段 15 行的代码,同时是打包器兼容层和测试友好层。它也解释了为什么 resolved !== undefined 用 undefined 判断而不是 null——loader() 理论上可能返回 null(虽然实际不会),用 undefined 是"未初始化"的安全哨兵。

8.9.4 40 项里只有 7 项直接碰 C++

lib/browser/api/module-list.ts 的 40 项中,用 process._linkedBinding 直接取的有 7 项:

crashReporter   → electron_browser_crash_reporter
ImageView       → electron_browser_image_view).ImageView
inAppPurchase   → electron_browser_in_app_purchase).inAppPurchase
MessageChannelMain → electron_browser_message_port).MessageChannelMain
Notification    → electron_browser_notification).Notification
View            → electron_browser_view).View
WebContentsView → electron_browser_web_contents_view).WebContentsView

剩下 33 项写的是 require('./xxx')。但打开 ./xxx 看,绝大多数还是第一行 _linkedBinding:

app.ts:1-2

// lib/browser/api/app.ts 全文
const { app } = process._linkedBinding('electron_browser_app');
export default app;

那为什么不全写在表里?三个理由:

① 有些模块需要 JS 侧的逻辑。browser-window.ts 要处理构造参数、要兼容 BrowserView 的弃用路径、要做 new 与函数调用两种形态的分派。这些不能放在 C++ 里(会污染 gin 层)。

② 有些模块要延迟求值。session 需要 app.ready;screen 需要 display 信息;protocol 要在 ready 后有内容。

③ 有些模块是纯 JS 组合。net.ts 由 net-fetch.ts 与 net-websocket.ts 拼起来,本身没有 C++ 对应物。

所以准确的说法不是"两张表",而是:一张 52 项的表 + 一层 33 个薄壳 + 一个 7 项的直连快车道。 三种写法,一个语义:模块名到值的映射,取值时才发生。


8.9.5 三个都叫 electron 的东西

同一个名字,在三个位置指三样东西,混起来会得出完全错误的结论:

位置是什么生命周期
node_modules/electron/一个 npm 包,导出可执行文件路径开发期,打包时被剔除
运行期 require('electron')一个假 Module,导出API 对象应用运行全程
node_modules/electron/electron.d.ts类型声明,52 个模块的名字与签名编译期

第一个的证据是 npm/index.js:25-30:

function getElectronPath() {
  let executablePath;
  if (fs.existsSync(pathFile)) executablePath = fs.readFileSync(pathFile, 'utf-8');
  if (process.env.ELECTRON_OVERRIDE_DIST_PATH) {
    return path.join(process.env.ELECTRON_OVERRIDE_DIST_PATH, executablePath || 'electron');
  }
  ...
}
module.exports = getElectronPath();

所以 require('electron') 在 Node 里跑(比如 electron-forge 的构建脚本)返回的是一个字符串;在 Electron 里跑返回的是 API 对象。同一个 require,两套解析,取决于宿主。

这就是为什么 const { app } = require('electron') 在纯 Node 脚本里会得到 undefined 而不报错——字符串上取 .app 是合法操作。这个坑每年都会绊倒一批人,根源是三种"electron"共用一个名字。

第三个(类型声明)由 docs/api/*.md 经 @electron/typescript-definitions 生成(package.json:69 的 gn-typescript-definitions 脚本),与运行期的 52 个模块条目不是同一份真相:类型可能比实现新,也可能旧。8.3 讲的"类型检查是构建门槛"只保证 lib/ 与 typings/ 自洽,不保证类型与实现一致——那是另一条链(文档 → d.ts)的职责。


8.10 require('electron') 的真身:一个假 Module

8.10.1 32 行造一个模块

lib/common/init.ts:80

const makeElectronModule = (name: string) => {
  const electronModule = new Module('electron', null);
  electronModule.id = 'electron';
  electronModule.loaded = true;
  electronModule.filename = name;
  Object.defineProperty(electronModule, 'exports', {
    get: () => require('electron')
  });
  Module._cache[name] = electronModule;
};

makeElectronModule('electron');
makeElectronModule('electron/common');
if (process.type === 'browser') makeElectronModule('electron/main');
else if (process.type === 'renderer') makeElectronModule('electron/renderer');
else if (process.type === 'utility') makeElectronModule('electron/utility');

逐行读,每一步都在骗 Node:

new Module('electron', null):parent 传 null,这个模块没有父模块。正常模块的 parent 是用来算 paths 和显示调用栈的,这里不需要。

loaded = true:告诉 Node "这个模块已经加载完了"。如果 false,循环 require 检测会介入。

filename = name:filename 通常是一个绝对路径。这里塞的是 'electron' / 'electron/main' 这种裸名。这行是给 require.resolve 和错误信息用的——报错时显示 electron,而不是一个不存在的路径。

exports 是一个 getter,不是值。取值时才调 require('electron')。

Module._cache[name] = electronModule:直接塞进 Node 的模块缓存。

8.10.2 为什么不会无限递归

第一次看到 get: () => require('electron') 会觉得必然栈溢出:require('electron') → 命中缓存 → 取 exports → 又 require('electron')。

不会,因为这个 require 不是 Node 的 require。

lib/common/init.ts 是 bundle 的一部分,它里面的 require('electron') 在构建期就被 aliasPlugin 替换成了对 lib/<target>/api/exports/electron.ts 那个内部模块的引用(8.3.2)。它根本不经过 Module._load。

所以运行期实际发生的是:

用户代码 require('electron')
  → Node 的 Module._load
  → _resolveFilename('electron') → 'electron'     [8.10.3 的钩子]
  → Module._cache['electron'] 命中
  → 读 exports getter
  → bundle 内部的 exports 模块(一个普通对象,40 个 getter)

而那个内部模块,与用户代码拿到的对象是同一个。所以:

require('electron') === require('electron')          // true(同一个缓存项)
require('electron').app === require('electron').app  // true(同一个 getter 结果)

一个只有 6 个字段的假 Module,撑起了整个"electron 是一个模块"的幻觉。

8.10.3 五个名字塌缩成一个键

lib/common/init.ts:101

const originalResolveFilename = Module._resolveFilename;
const electronModuleNames = new Set([
  'electron', 'electron/main', 'electron/renderer', 'electron/common', 'electron/utility'
]);
Module._resolveFilename = function (request, parent, isMain, options) {
  if (electronModuleNames.has(request)) {
    return 'electron';
  } else {
    return originalResolveFilename(request, parent, isMain, options);
  }
};

Set 里有 5 个名字,返回值永远是 'electron'。而 _cache 里却塞了 2–3 个键(electron + electron/common + 当前进程对应的那个)。

看起来矛盾:_cache['electron/main'] 存在,但 _resolveFilename 永远不返回 'electron/main',所以这个缓存项永远不会被命中。

为什么要塞?为了让 require.cache 看起来"正常"——某些工具会遍历 require.cache 找模块。更实际的原因可能是历史遗留:在 _resolveFilename 钩子出现之前,五个名字各自解析到各自的键。

这是一处冗余但无害的代码。它不影响行为,只影响 Object.keys(require.cache) 的内容。读代码时不必为它找深刻理由——有些代码只是没删。

真正的机制是那个 Set:五个名字,一个键,一个对象。 所以 require('electron/main') 和 require('electron') 返回同一个对象,不管在哪个进程。

8.10.4 时序:为什么必须在最前面

makeElectronModule 在 lib/common/init.ts 的顶层执行,而这个文件被每个 lib/*/init.ts 在最前面 require:

// lib/browser/init.ts
require('@electron/internal/common/init');   // 第 10 行

所以顺序是:

  1. browser_init bundle 开始求值;
  2. 第一件事是 require('@electron/internal/common/init')(构建期已内联,实际是执行那个模块);
  3. 那里装好 5 个名字的 _resolveFilename 钩子和 2–3 个缓存项;
  4. 然后才轮到 lib/browser/init.ts 里自己的 require('electron')(第 34 行 const { app } = require('electron'))。

第 4 步能成功,完全依赖第 3 步已经完成。如果顺序反了,require('electron') 会走正常的文件解析,然后报 Cannot find module 'electron'——因为硬盘上确实没有这个模块。

这段代码的脆弱性在于:它依赖一个模块被 require 的先后顺序,而这个顺序没有任何机制强制。 唯一的保障是"每个 init.ts 的第一行都写了这行 require",靠人守。


8.10.5 为什么 delete require.cache['electron'] 会把应用弄坏

热重载的常规套路是:

delete require.cache[require.resolve('./my-module')]
const fresh = require('./my-module')

对 electron 用同一招,结果是永久坏掉:

delete require.cache['electron']
require('electron')
// Error: Cannot find module 'electron'

原因链条有三环:

① require.resolve('electron') 返回 'electron'(8.10.3 的钩子),所以 delete require.cache['electron'] 确实删掉了那条记录。

② 下一次 require('electron') 走 Module._load:先 _resolveFilename 得到 'electron',再查 _cache——空了。

③ 于是按文件加载 'electron':Module._load 会把它当成路径去解析,硬盘上没有这个东西,抛 Cannot find module 'electron'。而 _resolveFilename 已经被永久改写,返回的永远是 'electron',所以再也回不到那个假 Module。

更绝的是:即使不删缓存,你也改不动它。

Object.defineProperty(require.cache['electron'], 'exports', { value: {} })
// TypeError: Cannot redefine property: exports

makeElectronModule 里 Object.defineProperty(electronModule, 'exports', { get }) 没有写 configurable,默认 false。所以 exports 是不可重定义、不可删除的访问器。同理,defineProperties 造的 52 个模块属性也没写 configurable(8.9.2)。

三个后果:

  • 测试里不能 stub require('electron')。 想在单元测试里替换 app,只能换掉整个模块加载器(proxyquire 之类),或者在应用代码里留一个注入点;
  • 框架不能被"热替换"。 任何"重新加载 electron 模块"的尝试都会失败,这是设计意图,不是缺陷;
  • require.cache 只读不写。 把它当普通缓存操作,会踩到三处 configurable: false。

这条设计线的逻辑是一致的:框架的对象图在进程生命周期内不变。 不可配置的 exports、不可配置的 52 个属性、被 delete process.appCodeLoaded 收走的内部回调(8.11.4),都是同一个决定的不同表现:框架给自己留后门,但不给用户留。

8.10.6 同一个 require('electron'),三种身份

把 8.7.3 和 8.10 合起来看,会得到一个反直觉的结论:同一行 require('electron').ipcRenderer,在不同进程里拿到的是三个不同的对象。

场景require 是谁的electron 是什么身份
主进程 / nodeIntegration: true 的渲染进程Node 的 Module._load假 Module → bundle 里的 exports 对象进程内唯一
沙箱渲染进程的 preloadpreload 环境手工给的函数CreateElectronModule 造的 C++ 对象每个 context 一份
utility 进程Node 的 Module._load假 Module → utility 的 exports 对象(4 项)进程内唯一

三者的行为相同(都有 ipcRenderer),身份不同:

// 沙箱 preload 里
require('electron') === require('electron')   // true(C++ 侧有 hidden cache)
// 但把它传给页面(contextBridge)会失败
contextBridge.exposeInMainWorld('electron', require('electron'))
// Error: object could not be cloned

最后一行是第 15 章的主题,但根在这里:C++ 造的对象不是普通 JS 对象,它带着 gin 的 wrapper 信息、internal field、可能的 cppgc 引用,structuredClone 的算法不认识它。

这也解释了一个常见困惑:为什么沙箱应用里 window.electron 通常是逐个方法暴露的(exposeInMainWorld('api', { send: (...) => ipcRenderer.send(...) })),而不是把整个 ipcRenderer 丢过去。不是因为"整个丢过去不优雅",是因为整个丢过去会抛异常。


8.11 六份 init.ts 的分诊表

七个 bundle,六份 init.ts(webview 只有 9 行)。把它们并排看,能看出一套"按进程能力分配初始化"的策略。

做的事browserrendererworkerutilitywebviewisolated
require common/init✓(10)✓(44)✓(6)✓(27)——
装 EventEmitter.prototype✓(12)——✓(29)——
uncaughtException → 对话框✓—————
app.on('quit') → process exit✓—————
process.exit → app.exit✓—————
改 Module.wrapper—✓(35)————
造 global.require—✓(66)✓(12)———
伪造 __filename/__dirname—✓✓———
加载 preload—✓(152)————
删 Node 全局—✓(130)————
建 parentPort———✓(31)——
注册 <webview>✓(common)✓(common)——✓✓
跑应用入口脚本✓(104)——✓(58)——

括号里是 lib/*/init.ts 的行号。

8.11.1 两处"看着该有却没有"

worker 没有 EventEmitter.prototype 注入。 而 utility 有。为什么?因为 worker 里的 require('electron') 只有 6 项,其中 ipcRenderer 需要 EventEmitter——但它走的是 ipc-renderer.ts:1-3,那里的 EventEmitter 来自 Node 的 events 模块(alwaysHasNode: true),不是 C++ 注入的原生版本。utility 不一样:它要 LanguageModelUtility 之类继承自原生 EventEmitter 的对象,所以必须装原型。

worker 不加载 preload。 preload 是"文档的 preload",worker 没有文档。worker 里的代码是世界自己 new Worker() 起来的,没有"注入点"这个概念。

8.11.2 renderer 的四道自保

lib/renderer/init.ts:11-15 是六份里最复杂的(180 行)。四件事值得单列:

① vm 模块的警告不拦截,只提示。

lib/renderer/init.ts:11-15

const originalModuleLoad = Module._load;
Module._load = function (request: string) {
  if (request === 'vm') {
    console.warn("The vm module of Node.js is unsupported in Electron's renderer process ...");
  }
  return originalModuleLoad.apply(this, arguments as any);
};

为什么不禁用?因为禁用会让一些库在 require 阶段直接崩,而它们的 vm 用法可能根本不会执行。警告 + 放行,是"给出后果提示但不替用户做决定"。

② Module.wrapper 双闭包。

lib/renderer/init.ts:35-38

Module.wrapper = [
  '(function (exports, require, module, __filename, __dirname, process, global, Buffer) { ' +
    'return function (exports, require, module, __filename, __dirname) { ',
  '\n}.call(this, exports, require, module, __filename, __dirname); });'
];

外层接收 8 个参数(多了 process、global、Buffer),内层只有标准 5 个。为什么套一层?注释:防止模块代码用局部变量覆盖 process 和 Buffer。内层函数的参数列表里没有这两个名字,所以模块里的 var process = ... 只是模块自己的局部变量,不影响外层捕获的那份。

这个 hack 需要 Node 补丁配合(pass_all_globals_through_require.patch:26):Module.prototype._compile 调用 wrapper 时多传三个实参 process, localGlobal, localBuffer。补丁里那两个 localGlobal / localBuffer 的捕获,正是为了"全局被删之后还能传"。

③ 删全局的时机被推迟到 preload 之后。

lib/renderer/init.ts:125-129

const shouldDeleteRendererNodeGlobals = !nodeIntegration && !process.contextIsolated;
const onPreloadsLoaded = () => {
  if (shouldDeleteRendererNodeGlobals) {
    delete (global as any).process;
    ...
  }
  appCodeLoaded!();
};

注释解释了为什么不能用 'loaded' 事件:

// The 'loaded' event fires on the next tick after init returns, which is
// before any async ESM preload finishes executing, leaving its code with no
// `process` (#46142).

loaded 事件在"init 返回后的下一个 tick"发。同步 preload 在那个 tick 之前就跑完了,但 ESM preload 是异步的,可能还没跑。所以改成显式回调:CJS preload 同步跑完、ESM preload await 完之后,才删。

④ preload 按扩展名分两批。

lib/renderer/init.ts:146-147

const cjsPreloads = preloadPaths.filter((p) => path.extname(p) !== '.mjs');
const esmPreloads = preloadPaths.filter((p) => path.extname(p) === '.mjs');

判定依据是扩展名,不是内容。.mjs 走 ESM loader,其余走 Module._load。这个规则简单到粗暴,但可预测:用户改扩展名就能改加载方式,不需要看 package.json 的 type 字段。

8.11.3 utility 的"反向注入"

utility 是唯一一个由 C++ 把数据塞给 JS、而不是 JS 去 C++ 取的进程:

lib/utility/init.ts:8-9

const entryScript: string = v8Util.getHiddenValue(process, '_serviceStartupScript');
process.argv.splice(1, 0, entryScript);

入口脚本路径不是通过命令行参数传的,是塞在 process 对象的 hidden value 里。为什么?因为 process.argv 是用户可见的,如果在 argv 里塞一个内部路径,process.argv 的形状就与 utilityProcess.fork(path) 的语义不一致。

先取出、再插回 argv 的第 1 位——这样用户脚本里 process.argv[0] 是可执行文件、process.argv[1] 是自己的路径,与 Node 一致。

同处还注册了三个 hidden value 判定函数(isReadableStream、isLanguageModel、isLanguageModelClass),供 C++ 侧在跨语言传值时判断类型。这是第 7 章讲过的"反向类型检查":C++ 需要知道一个 JS 值是什么类型,但又不能 include 那个 JS 类,于是让 JS 注册一个谓词。


8.11.4 browser_init 的十四件事,逐条

lib/browser/init.ts 一共 120 行,按顺序做了十四件事。这个顺序本身是设计:

#动作为什么在这个位置
1require common/init必须先装 require('electron') 的钩子,后面才有 require('electron') 可用
2装 EventEmitter.prototype之后创建的每个 C++ 对象都要继承它
3uncaughtException → dialog.showErrorBox要在用户代码注册 handler 之前就位
4app.on('quit') → process.emit('exit')让 Node 的 exit 语义在 GUI 应用里成立
5process.exit → app.exit第四件事的配套:改了 exit 的事件,也得改触发点
6ipc-dispatch渲染进程的 IPC 要有落点,早于任何窗口创建
7rpc-serverwebContents.executeJavaScript 之类的 RPC 通道
8guest-view-manager<webview> 的浏览器侧管理器
9读 appPackage hidden value应用路径与入口脚本
10app.setAppPath让 app.getAppPath() 在用户代码里立刻可用
11预加载 4 个模块(protocol / service-worker-main / web-contents / web-frame-main)注释说"确保 ready 时已填充"——这些模块的 C++ 侧初始化在 ready 时才需要,但 JS 侧的对象必须提前存在
12window-all-closed 默认退出只在没有别的监听者时生效(listenerCount === 1)
13取走 appCodeLoaded 并 delete process.appCodeLoaded只给框架用一次,不留给用户
14v8Flags / ESM 或 CJS 入口最后一步:先把一切准备好,再交出控制权

三处细节值得单独说:

第三件事的"自定义 handler 优先"逻辑。 if (process.listenerCount('uncaughtException') > 1) return;——> 1 而不是 > 0,因为这个 handler 自己就是一个监听者。用户注册过 handler,count 就是 2;没注册过,count 是 1。所以 > 1 意味着"用户已经有了自己的处理方式,我不插手"。

第十二件事的 listenerCount === 1。 同理:应用如果自己监听了 window-all-closed,框架就不退出。=== 1 表示"只有框架自己这一个监听者"。两处都在用"把自己算进去"的方式表达"只有我",这是 EventEmitter 语义下唯一可行的写法。

第十三件事的 delete。 appCodeLoaded 被从 process 上删掉,之后用户代码调不到它。这不是洁癖:appCodeLoaded 的作用是"告诉 C++ 应用代码已就位",如果用户能调用,就能在代码还没加载完时提前触发窗口显示,制造难以复现的竞态。把内部回调暴露给用户,等于把竞态暴露给用户。


8.12 lib/node/init.ts:四件 Node 不打算做的事

这份文件只有 93 行,但四件事都是"改 Node 的默认行为"。

8.12.1 wrapFsWithAsar:2,493 行,因为补不动 fs

第一行就是 wrapFsWithAsar(require('fs'))。看起来像给 fs 打几个补丁,实际上 asar-fs-wrapper.ts:28-31 有 2,493 行,重写了 fs 的大半个 API 面。原因在于它不能只 patch 公开的 fs 对象,它必须站在 internalBinding('fs') 上重新实现:

const binding = internalBinding('fs');
const dirBinding = internalBinding('fs_dir');
const uvBinding = internalBinding('uv');
const { kUsePromises } = binding;

三件事决定了这个规模:

① Node 内部有大量代码绕过 require('fs')。 Module._findPath 用 internalModuleStat,fs.readFileSync 内部走 binding.read。只在模块导出上套一层,对这些路径完全无效。所以包装器直接接管 internalModuleStat,并给出一个 statTypeForReaddir(返回 1 目录 / 0 文件 / 负数缺失),让递归 readdir 在 asar 内部也能下钻。

② 错误码必须匹配平台。 注释里有一行很容易漏掉:

// libuv's error numbers differ from POSIX errno on Windows (UV_EACCES is
// -4092 there, not -13); Node decodes `errno` through libuv's table, so the
// errors created here must carry libuv's values.

所以它 internalBinding('uv') 拿 libuv 的常量,而不是硬编码 -13。一个在 Linux 上能跑的 asar 错误,在 Windows 上会变成"未知错误",除非用 libuv 的表。

③ 符号链接与目录环。 statTypeForReaddir 的注释解释了为什么不跟随 asar 内的 symlink:

// ... Unlike internalModuleStat itself, symbolic links inside archives are not
// followed: recursive readdir descends into whatever this reports as a
// directory, and archives may legitimately contain link cycles (a real
// filesystem walk would only be stopped by ENAMETOOLONG).

真文件系统靠 ENAMETOOLONG 兜底,asar 里没有这个限制,所以必须主动不跟随。

还有三个开关:process.noAsar(运行期关掉)、ELECTRON_NO_ASAR(环境变量,且只在非 browser/renderer 进程生效)、ELECTRON_LOG_ASAR_READS(把每次读文件的 offset 记进 tmpdir 的日志)。第三个是排查打包问题的利器:应用读不到文件时,先看这张表里有没有那次读。

位置选择也重要:它必须在 node_init 里、在用户代码之前。 放在 browser_init 里,渲染进程就读不了 asar;放在 browser/api/fs 之类的模块里,用户 require('fs') 拿到的还是原生版本。

8.12.2 child_process.fork 的两道闸

lib/node/init.ts:28-29

if (!process._linkedBinding('electron_common_features').isRunAsNodeEnabled()) {
  throw new Error('child_process.fork() is not supported when the runAsNode fuse is disabled; use utilityProcess.fork() instead');
}

runAsNode fuse 关掉之后,fork 出来的子进程不会变成 Node,而是又启动一个 Electron 应用——无限递归。所以直接拒,并给出替代方案(utilityProcess.fork)。

放行时设置 ELECTRON_RUN_AS_NODE=1,并在 macOS 上把 execPath 换成 helper:

lib/node/init.ts:37-38

if (!options.execPath && process.platform === 'darwin') {
  options.execPath = process.helperExecPath;
}

macOS 的应用主二进制不能直接以"Node 模式"启动(会因为缺少 GUI 上下文而异常),必须走 Helper 子进程。这行是平台差异的补丁。

8.12.3 Module._nodeModulePaths 收窄

lib/node/init.ts:82-87

Module._nodeModulePaths = function (from) {
  const paths = originalNodeModulePaths(from);
  const fromPath = path.resolve(from) + path.sep;
  if (fromPath.startsWith(resourcesPathWithTrailingSlash)) {
    return paths.filter((candidate) => candidate.startsWith(resourcesPathWithTrailingSlash));
  }
  return paths;
};

Node 默认会从当前目录一路往上找到根,每一层都加一个 node_modules。Electron 把搜索范围限制在 resources/ 之内——如果 from 在 resources/ 里,就只保留 resources/ 下的候选路径。

这不是安全边界(第 22 章会讲为什么),而是一个行为一致性措施:打包后的应用不应该意外加载到应用目录之外的 node_modules,否则开发机上能跑、用户机器上行为不同。

8.12.4 Linux 的 crashpad fd 传递

最后 30 行只在 Linux 生效:给 ELECTRON_RUN_AS_NODE 子进程的 env 里加 CRASHDUMP_SIGNAL_FD 和 CRASHPAD_HANDLER_PID,让子进程的崩溃也能被父进程的 crashpad 捕获。做法是替换 ChildProcess.prototype.spawn 与 childProcess.spawnSync——又一次 monkey-patch,因为 Node 没有提供"spawn 前修改 envPairs"的钩子。

四件事,四种手法:包装(asar)、拦截(fork)、替换(_nodeModulePaths)、monkey-patch(spawn)。没有统一的"扩展点",因为 Node 没打算被扩展。


8.13 第二个岔口:ESM 入口

lib/browser/init.ts:104-111 末尾的入口分派是启动链的终点,也是唯一按"模块系统"分岔的地方:

if (appPackage.esm) {
  const { runEntryPointWithESMLoader } = require('internal/modules/run_main');
  const main = pathToFileURL(path.join(appPackage.path, appPackage.main));
  runEntryPointWithESMLoader(async (cascadedLoader) => {
    try {
      await cascadedLoader.import(main.toString(), undefined, Object.create(null));
      appCodeLoaded!();
    } catch (err) {
      appCodeLoaded!();
      process.emit('uncaughtException', err);
    }
  });
} else {
  appCodeLoaded!();
  Module._load(path.join(appPackage.path, appPackage.main), Module, true);
}

8.13.1 主进程入口的两条路

三个观察:

① CJS 分支先调 appCodeLoaded(),ESM 分支后调。 注释说 CJS 分支"提前调无所谓,因为 _load 是同步的"。appCodeLoaded 是 C++ 侧的回调(第 5 章 5.15),告诉浏览器进程"应用代码已就位,可以显示窗口"。CJS 同步,前后没有可观察差异;ESM 异步,必须在 await 之后调。

② 错误被手工转成 uncaughtException。 ESM loader 抛出的是 Promise rejection,不走 V8 的未捕获异常通道。catch 里显式 process.emit('uncaughtException', err)——把一种错误通道翻译成另一种,让用户只需要写一个 handler。

8.13.2 preload 的收尾

渲染进程的 preload 走同一套机制,但收尾用 .finally(onPreloadsLoaded) 而不是 .then:无论成功失败都要删全局、都要调 appCodeLoaded。preload 抛错时错误已经通过 IPC 报给浏览器进程,页面还得继续跑。


8.13.3 utility 的入口只有 ESM 一条路

lib/utility/init.ts:56-62 没有 esm 分支,它无条件走 ESM loader:

const mainEntry = pathToFileURL(entryScript);
runEntryPointWithESMLoader(async (cascadedLoader) => {
  try {
    await cascadedLoader.import(mainEntry.toString(), undefined, Object.create(null));
  } catch (err) {
    const { internalBinding } = require('internal/bootstrap/realm');
    internalBinding('errors').triggerUncaughtException(err);
  }
});

三处与主进程不同:

① 没有 appCodeLoaded。 utility 进程没有窗口要显示,不需要"应用代码已就位"的信号。C++ 侧也印证:process.SetMethod("appCodeLoaded", ...) 只在 kBrowser 与 kRenderer 两个环境下注册(node_bindings.cc:943)。

② 错误走 internalBinding('errors').triggerUncaughtException,不是 process.emit。 因为没有 process.on('uncaughtException') 的传统入口——utility 的 process 是 Node 的,但它的错误要经 V8 的未捕获异常通道上报,再由 C++ 侧转成 utilityProcess 的 exit 事件。这是一条没有 JS 中间层的错误路径。

③ cascadedLoader 是"级联"的。 它不只是加载入口文件,还承载了入口文件里所有 import 的解析。utility 进程的用户代码可以 import 任意 ESM,也可以 require CJS(Node 的 ESM loader 支持混合),但入口本身必须能被 ESM loader 接受——一个用了 __dirname 的 CJS 脚本被当作入口时,会在 ESM 语义下拿到 undefined。

第三条是实际踩坑点:utilityProcess.fork(path) 的 path 如果是一个依赖 CJS 全局的脚本,它会"能跑但行为不同"。这类问题的特征是没有报错,只有 undefined。


8.14 失败模式手册

现象原因定位
白屏无错误,只有 Electron renderer_init.js script failed to runwrapInitWithTryCatch 吞了异常去掉该 target 的 try/catch 重编
Failed to compile electron script (internal/electron/js2c/xxx_init)id 不存在:ProcessType() 与文件名不一致查 $root_gen_dir/internal/electron/js2c/
Unable to find a valid appappPackage hidden value 没设第 5 章的 package.json 解析链
require('electron') 返回 {}common/init 没跑Object.keys() 为空即此因
Cannot find module 'electron'钩子没装就 require 了检查 init.ts 第一行
No such binding: electron_renderer_ipc名字拼错,或进程不对对照 module-list 的进程域
打包后 Cannot find module 'x',开发时正常_nodeModulePaths 把范围收在 resources/ 内把依赖放进应用目录
fork() is not supported when the runAsNode fuse is disabledfuse 关闭改用 utilityProcess.fork()
启动慢 30–80ms 且无报错code cache 未命中跑 spec/api-js2c-code-cache.spec.ts
页面里 process is not definedshouldDeleteRendererNodeGlobals 生效设计行为,用 preload 暴露

两类错误最难查,各记一句:

"白屏无错误"几乎总是 try/catch。 四个 bundle 被 try{}catch{} 包着,错误只 console.error,不冒泡、不弹窗、不退出。

"慢但没错"几乎总是 code cache。 参数名、flavor、id 任一漂移,V8 静默回退源码编译,没有任何日志,只能靠测试断言。

共性是:这套设计用字符串换来了构建期解耦,代价是把一部分错误推到了运行期。


8.14.1 三步定位法

面对"应用起不来 / 白屏 / 慢"三类症状,按顺序做三件事,能覆盖 8.14 表里的绝大多数行:

第一步:确认 bundle 跑没跑。 在 lib/browser/init.ts 第一行加一句 console.log('[init] enter'),重编。没有输出 → 问题在 CompileBundle 或更早(id、js2c、链接);有输出 → 问题在 bundle 内部。

第二步:确认 require('electron') 通没通。 在 init.ts 里 console.log(Object.keys(require('electron')).length)。期望 42(主进程)。得到 0 → common/init 没跑到;抛 Cannot find module → 钩子没装;得到 8 → 走错 bundle 了。

第三步:确认缓存命中。 跑 spec/api-js2c-code-cache.spec.ts。它是唯一能区分"慢是因为缓存没命中"和"慢是因为别的原因"的工具,因为这条路径没有任何运行期日志。

三步的价值在于把"没反应"切成三段:构建产物、bundle 执行、缓存。每段有自己的失败模式,混在一起查会浪费几个小时。


8.15 性能账本

三句话:

启动快在"零解析、零编译",不是快在"打包"。 打包只省了文件 IO;真正的收益来自 8.5 的 code cache。没有缓存,bundle 化只省几毫秒,却付出可调试性的代价。

体积换时间。 约 12MB 缓存换几十毫秒启动,对桌面应用划算——一次启动省下的时间超过下载 12MB 的时间,前提不是每次启动都下载。

构建期成本转移。 七次 rolldown、一次独立 tsc、五个 flavor 的 codecache、一个生成的 filenames.auto.gni、一条 --check。维护者承担复杂度,用户拿到启动速度。这是一个明确的"把成本推给上游"的决策。


8.16 练习题

8.1(入门) 执行 Object.getOwnPropertyDescriptor(require('electron'), 'app'),解释 set 为何是 undefined、configurable 为何是 false(8.9.2)。

8.2(入门) 对比 require('electron') 与 require('electron/main') 的 === 结果,解释 _cache 有 3 个键但只有一个会被命中(8.10.3)。

8.3(进阶) 在 module-list.ts 里加一个假模块 { name: 'test', loader: () => ({ a: 1 }) },验证 require('electron').test 可用,并说明为什么不再需要 module-keys(8.1.2)。

8.4(进阶) 把 kInitBundleParams 的 "process" 改成 "proc",重编后观察启动是否变慢,并用 spec/api-js2c-code-cache.spec.ts 验证(8.5.7)。

8.5(进阶) 用 --print-graph 求 renderer 与 worker 模块图的差集,解释那 11 个文件为什么进不了 worker(8.4.3)。

8.6(深入) 去掉 CompileBundle 里的 thread_local,用渲染进程 + web worker 同时启动复现问题,解释为什么 BuiltinLoader 不能跨 isolate 共享(8.5.6)。

8.7(深入) 注释掉 FeedEnvironmentCodeCache(env),用 V8 的 code cache 跟踪 flag 观察 browser_init 是否退化为源码编译(8.5.6)。

8.8(挑战) 只保留 browser target,删掉其余六个 bundle 与其 js2c 输入,让 electron --version 仍能跑。记录每一处被删掉的依赖。


8.17 下一章预告

第 9 章《NativeWindow:一个窗口的四个身体》接住本章的三条尾巴。

尾巴一:BrowserWindow 不是 7 个直连绑定之一,它走 browser-window.ts 这层薄壳——把 JS 构造参数翻译成 gin_helper::Dictionary,再交给 NativeWindow。第 9 章从 new BrowserWindow({ width: 800 }) 追到 views::Widget::InitParams。

尾巴二:8.11.2 的 Module.wrapper 双闭包,是为了让 preload 在全局被删之后还能用 process。preload 跑在哪个 context,是第 12 章的主题;第 9 章只需一个结论:窗口的创建发生在浏览器进程,与渲染进程的 context 无关。

尾巴三:8.5.3 的表里 sandbox flavor 只有两个 bundle——沙箱渲染进程的 window、document、process 全是 C++ 手工搭的。第 9 章的 WebContentsView 会展示这套手工搭建的另一半。

一句话预告第 9 章的立论:Electron 的窗口不是一个对象,是四个:JS 的 BrowserWindow、C++ 的 NativeWindow、Chromium 的 views::Widget、平台的 HWND/NSWindow/GtkWindow。四个身体,一条命,而它们的寿命并不同步。