《Electron 45.2.3 内核解剖》第 24 章 演进与展望:把「薄薄一层」放回版本史
24.0 四条边界,和一张全书的回声地图
第 23 章末尾留了一句话:这一章要把前面反复出现的那类「薄薄一层」——补丁、fuse、mojom 扩展、进程旁路——放回版本史里,看哪些是历史包袱、哪些正在被上游吸收、哪些会在下一个 Chromium 大版本里消失。这句话要收紧一半:本仓库不提供整体路线图。全树对 docs/ 检索「Electron 46」只命中两行,且指向同一个 API 的移除预告;docs/tutorial/ 下的安全、沙箱、隔离、版本文档里,找得到「自 Electron 20 起 sandbox 默认开启」这类已经发生的默认值变更记录,找不到「将来会把 X 翻成默认值」的承诺(24.13.4)。所以本章能写的「展望」只有两类:当前源码里已经存在、但尚未稳定的机制(ENABLE_PROMPT_API 的 buildflag 链、66 处 _Experimental_ 标记、2026 年的 217 个补丁、fuses.json5 里预留的 'r' 墓碑位),以及文档里明确写了目标 major 的那一条移除预告(24.7.5)。两类都是可验证的当下,不是预测。
先钉死四条边界。这一章几乎每个结论都能归到其中一条,越界就会写成博客式的版本点评。
| 边界 | 两侧 | 本章的判据 |
|---|---|---|
| ① 机制 / 预测 | 生成脚本、lint 规则、wire 布局 vs「下个版本会怎样」 | 只写能从文件行号推出的结论;没有承诺就明写「未找到」 |
| ② 版本史 / 路线图 | breaking-changes.md 44 个已发布段落 vs 未来计划 | 未来计划已被并入正文,只剩 :5 的免责声明(24.8.2) |
| ③ 仓库内 / 仓库外 | build.py 生成 getter vs @electron/fuses 翻转二进制 | wire 兼容契约由两侧共同承担,仓库内只有一半(24.9.5) |
| ④ 兼容性契约 / 实现细节 | 'r' 位永不回收、[EnableIf] 条件编译 vs 具体 API 列表 | 前者决定「能怎么演进」,后者只说明「现在有什么」 |
按这四条边界,把本章涉及的设施摊开:
| 设施 | 文件 | 回答什么 | 位置 |
|---|---|---|---|
DEPS / electron_version.h | DEPS:3-17、BUILD.gn:129-150 | 45.2.3 由哪几个上游版本拼成 | 24.1 |
| 发布节奏与 SemVer | electron-timelines.md、electron-versioning.md | 为什么 8 周一次必须重打补丁 | 24.2 |
config.json + 17 个 .patches | patches/、patches.py | 380 个补丁落在哪些仓库、按什么顺序 | 24.3 |
| 补丁理由的三分类与 lint | patches.md:7、script/lint.js:273-279 | 补丁为什么必须写「何时能删」 | 24.4 |
| 24 章 ↔ 补丁主题对照 | 全书 23 章点名过的补丁 | 哪些缝合点长期稳定、哪些是 2026 新伤 | 24.5 |
| rolldown / Node 快照 / Perfetto | bundle.mjs、patches/node/.patches | 三条正在发生的主线 | 24.6 |
deprecate.ts / EmitDeprecationWarning | deprecate.ts:1-47 | 弃用告警如何只发一次 | 24.7 |
breaking-changes.md 与 api-history | docs/breaking-changes.md 3606 行 | 破坏性变更如何变成机器可校验的数据 | 24.8 |
fuses.json5 与 build.py | build/fuses/ | 二进制位如何跨版本不失效 | 24.9 |
5 个 .mojom 与 [EnableIf] | api.mojom | 跨进程接口如何加方法 | 24.10 |
utilityProcess / webUtils 五层落地 | shell/→lib/→docs/→spec/ | 一个新 API 要改多少处 | 24.11 |
4 个 buildflag 与 _Experimental_ | buildflags.gni:5-27 | 「实验性」到底是谁的承诺 | 24.12 |
| 三次默认值翻转 | security.md:161,226,252 | 历史包袱如何被清掉 | 24.13 |
| 十五条纠偏 | 本书取证中的阴性结果 | 旧版 Electron 认知在 45.2.3 的失效点 | 24.14 |
| 全书收束与升级检查单 | 本章 | 拿到一份新源码时先读哪六个文件 | 24.15 |
24.0.1 为什么「演进」必须写成可验证的
技术书谈演进最容易滑向两种注水:一是按年份罗列 release note,二是用「未来可期」收尾。前者不产生理解,后者不产生判据。本章换一个更硬的问题:当上游换了版本,Electron 靠什么保证自己那些「不在上游的改动」还能对得上? 这个问题的答案全部落在文件里——DEPS 钉版本、.patches 钉顺序、fuses.json5 钉位序、api-history.schema.json 钉文档结构、[EnableIf] 钉接口条件编译。它们才是「演进」的实体,版本号只是它们的输出。
顺着这个问题读,会得到一个贯穿全章的判断:Electron 的演进成本不在写新功能,而在维持这些「对齐契约」。第 3 章讲 380 个补丁如何被打进 Chromium,第 4 章按主题分类;本章不重复分类,而是看这批补丁作为一份时间档案告诉了我们什么:哪个上游接口被反复改、哪类改动始终无法上游化、以及 2026 年这一批补丁为什么集中在启动与追踪。
24.0.2 三条会推翻旧版认知的纠偏
取证过程中有三处与「Electron 一直如此」的印象直接冲突,先摆出来,后文逐条给出行号:
- 弃用机制换了内核。
ELECTRON_ENABLE_DEPRECATION_WARNINGS、deprecate.removeIn、用Set缓存已告警项,在 45.2.3 全部不存在。deprecate.ts:13-21用的是闭包里的一个布尔变量,开关改用 Node 标准的process.noDeprecation/throwDeprecation/traceDeprecation(24.7.2)。 - fuses 不是源码文件。
shell/common/fuses.h/fuses.cc在树里找不到,它们由BUILD.gn:458-469的 action 在构建期从fuses.json5生成。第 20 章讲过 wire,本章补上「生成脚本的索引算法为什么不许插队」(24.9.3)。 - mojom 接口没有
ElectronBrowser。shell/下零命中;它被拆成ElectronFrame/ElectronRenderer/ElectronApiIPC等,跨版本兼容也不用MinVersion或 ordinal,而是[EnableIf=enable_prompt_api]加 buildflag 条件编译(24.10.3)。
这三条不是措辞差异,是升级排查时会直接把人带错路的差异:按旧路径去找弃用告警开关会一无所获,按旧接口名去 grep mojom 会以为接口被删了,按「fuse 定义在 shell/common」去找会以为源码缺失。
24.0.3 与前面 23 章的呼应方式
本书六个部分,各自留下了至少一个「版本敏感点」,本章按节号把它们接上:
| 部分 | 章 | 留下的版本敏感点 | 本章接手 |
|---|---|---|---|
| 一 · 基础架构 | 01–04 | 380 个补丁、17 个上游仓库 | 24.3 / 24.4 / 24.5 |
| 二 · 启动与绑定 | 05–08 | 七个 bundle、两个注册表、构建期 code cache | 24.6.1 rolldown |
| 三 · 窗口与视图 | 09–13 | preload 预推、共享纹理、隔离世界 | 24.6.2 快照 / 24.10.2 |
| 四 · 通信 | 14–16 | mojom 消息定义、[Sync]、utility process | 24.10 / 24.11 |
| 五 · 子系统 | 17–20 | fuse wire、asar integrity、发布校验 | 24.9 / 24.8.5 |
| 六 · 工程与运维 | 21–23 | spec 权重、zip manifest、Perfetto 汇流 | 24.6.4 / 24.12 |
所以这一章既是收束,也是一份**「换版本时该重读哪些文件」的索引**。24.15 会把它压成一张可执行的检查单。
24.1 版本坐标:45.2.3 到底由什么拼成
24.1.1 DEPS 是唯一权威
版本对应关系不从 package.json:125 读,也不从任何教程读,只读 DEPS。文件开头 15 行就把上游钉死了:
# DEPS:3-17
vars = {
'chromium_version':
'156.0.8078.80',
'node_version':
'v24.22.2',
'nan_version':
'675cefebca42410733da8a454c8d9391fcebfbc2',
'squirrel.mac_version':
'fffea30e4a339a7f7d69a3391314b72548d209bd',
'reactiveobjc_version':
'74ab5baccc6f7202c8ac69a8d1e152c29dc1ea76',
'mantle_version':
'2a8e2123a3931038179ee06105c9e6ec336b12ea',
'sparkle_version':
'79bc9e872948e47877e76f194cb0c8e0412b0b90',
DEPS:78-90 把变量拼进 git url:
DEPS:79-86
DEPS:79-86
DEPS:79-86
# DEPS:79-90
'src': {
'url': (Var("chromium_git")) + '/chromium/src.git@' + (Var("chromium_version")),
'condition': 'checkout_chromium and process_deps',
},
'src/third_party/nan': {
'url': (Var("nodejs_git")) + '/nan.git@' + (Var("nan_version")),
'condition': 'checkout_nan and process_deps',
},
'src/third_party/electron_node': {
'url': (Var("nodejs_git")) + '/node.git@' + (Var("node_version")),
'condition': 'checkout_node and process_deps',
},
于是坐标确定:Chromium 156.0.8078.80 + Node.js v24.22.2。总目录首页写的「Chromium 156 × Node 24 的融合架构」正是从这两行来的。注意 nan_version、squirrel.mac_version 这些是 commit SHA 而非语义版本——Electron 对「没有正式 release 的上游依赖」直接钉提交,这是第一层版本策略差异。
24.1.2 V8 没有独立版本号
一个常见误解是「Electron 版本表里有 V8 版本」。本树找不到 v8_version 变量:V8 随 Chromium 的 src/v8 一起 checkout,config.json:5 把补丁目录映射到 "repo": "src/v8",all.gn:11 写 node_v8_path = "//v8",:17 写 v8_embedder_string = "-electron.0"。三条证据合起来的意思是:V8 与 Chromium 同源、Node 复用同一个 V8、且 Electron 在 V8 版本串尾部加了自己的后缀。
所以 process.versions.v8 末尾那个 -electron.0 不是 V8 官方版本号,是 embedder string。第 3 章讲「V8 同源」时用的是架构理由,这里补的是版本管理理由:不给 V8 独立变量,是因为一旦允许它偏离 Chromium,Node 与 Blink 就会跑在两套 V8 上,这正是第 6 章「两个事件循环共享一个 isolate」的前提。
all.gn:5 的 node_module_version = 150 是另一个容易混淆的数:它是 Node 的 ABI 模块版本号,不是 V8 版本,决定原生模块能否加载(第 8 章讲 .node 加载时用到)。
24.1.3 从 git tag 到 electron_version.h 的六步
Electron 自己的版本号不在 DEPS 里。package.json:3 固定是 "version": "0.0.0-development",真正版本来自构建期读取 git tag:
BUILD.gn:129-150
if (override_electron_version != "") {
electron_version = override_electron_version
} else {
# When building from a source code tarball there is no git tag available and
# builders must explicitly pass override_electron_version in gn args.
...
electron_git_ref_paths =
exec_script("script/get-git-ref-paths.py", [], "list lines")
...
read_file(electron_git_ref_paths[0], "string")
# Set electron version from git tag.
electron_version = exec_script("script/get-git-version.py",
[],
"trim string",
electron_git_ref_paths)
}
script/get-git-version.py:22-36
try:
output = subprocess.check_output(
['git', 'describe', '--tags', '--abbrev=0'],
cwd=os.path.abspath(os.path.join(os.path.dirname(__file__), '..')),
stderr=subprocess.PIPE,
universal_newlines=True)
# only remove the 'v' prefix from the tag name.
version = re.sub('^v', '', output.strip())
print(version)
except Exception:
...
print('0.0.0-no-git-tag-found')
完整链路六步,任何一步错配都会让二进制报出与源码不符的版本:
| 步 | 文件:行号 | 动作 | 失败时的表现 |
|---|---|---|---|
| 1 | buildflags.gni:20 | override_electron_version 默认为空 | 打包方未设置则走 git |
| 2 | script/get-git-version.py:23-29 | git describe --tags --abbrev=0,去掉前缀 v | 源码 tarball 无 tag → 0.0.0-no-git-tag-found |
| 3 | script/generate-version-json.js:8-31 | semver.parse() 拆出 major/minor/patch/prerelease | 版本号不合法直接抛异常 |
| 4 | BUILD.gn:406-423 | npm_action("electron_version_args") → templated_file("electron_version_header") | 生成目录缺 .args 文件 |
| 5 | electron_version.tmpl:8-21 | 生成 6 个宏,含 ELECTRON_VERSION_STRING | 预发布版本少一个宏 |
| 6 | BUILD.gn:425-432、:442-449 | 同参数生成 electron.rc 与 $root_build_dir/version | Windows 资源版本与 JS 版本不一致 |
第 3 步值得单独看,它把 semver 的预发布段单独拆成两个字段:
script/generate-version-json.js:8-31
const parsed = semver.parse(currentVersion);
let prerelease = '';
if (parsed.prerelease && parsed.prerelease.length > 0) {
prerelease = parsed.prerelease.join('.');
}
const { major, minor, patch } = parsed;
fs.writeFileSync(
outputPath,
JSON.stringify(
{
full_version: currentVersion,
major,
minor,
patch,
prerelease,
prerelease_number: prerelease ? parsed.prerelease[parsed.prerelease.length - 1] : '0',
has_prerelease: prerelease === '' ? 0 : 1
},
null,
2
)
);
has_prerelease 直接控制模板里的 #if $has_prerelease 分支(electron_version.tmpl:11-19):稳定版宏是 "45.2.3",alpha/beta 版宏是 "46.0.0-alpha.1"。这解释了一个排查经验——同一份源码打出的两个二进制,ELECTRON_VERSION_STRING 不同,只因为构建时的 git tag 不同;这也是 override_electron_version 存在的理由(buildflags.gni:17-20 明说「Packagers and vendor builders should set this」)。
24.1.4 process.versions 是两处显式写入
process.versions.electron 与 process.versions.chrome 不是 Node 给的,是 Electron 在主进程和沙箱渲染进程各写一次:
node_bindings.cc:1236-1250
// Set custom process properties.
gin_helper::Dictionary dict(env->isolate(), process.As<v8::Object>());
dict.SetReadOnly("resourcesPath", GetResourcesPath());
base::FilePath helper_exec_path; // path to the helper app.
base::PathService::Get(content::CHILD_PROCESS_EXE, &helper_exec_path);
dict.SetReadOnly("helperExecPath", helper_exec_path);
gin_helper::Dictionary versions;
if (dict.Get("versions", &versions)) {
versions.SetReadOnly(ELECTRON_PROJECT_NAME, ELECTRON_VERSION_STRING);
versions.SetReadOnly("chrome", CHROME_VERSION_STRING);
#if BUILDFLAG(HAS_VENDOR_VERSION)
versions.SetReadOnly(BUILDFLAG(VENDOR_VERSION_NAME),
BUILDFLAG(VENDOR_VERSION_VALUE));
#endif
}
preload_utils.cc:238-251
if (key == "cldr")
versions.SetReadOnly(key, *cldr_version);
else if (key == "tz")
versions.SetReadOnly(key, *tz_version);
else
versions.SetReadOnly(key, value);
}
versions.SetReadOnly(ELECTRON_PROJECT_NAME, ELECTRON_VERSION_STRING);
versions.SetReadOnly("chrome", CHROME_VERSION_STRING);
#if BUILDFLAG(HAS_VENDOR_VERSION)
versions.SetReadOnly(BUILDFLAG(VENDOR_VERSION_NAME),
BUILDFLAG(VENDOR_VERSION_VALUE));
#endif
return versions.GetHandle();
两个细节:ELECTRON_PROJECT_NAME 是键名宏,允许品牌化构建(fork 把 electron 换成自己的名字);node / v8 / modules / cldr / tz 等字段来自 Node 自身,Electron 只在这两处追加。第 12 章讲沙箱 preload 的 process 对象是「Electron 拼出来的」,preload_utils.cc:245 就是拼装现场——沙箱渲染器没有 Node 环境,必须靠浏览器进程把 versions 数据预推过去(这正是 24.6.3 与 23.4 的 RendererStartupData 交叠处)。
CHROME_VERSION_STRING 的定义文件不在本树(来自 Chromium 的 chrome/VERSION),全树只命中三处引用:node_bindings.cc:1245、preload_utils.cc:246、app_shim_constants.cc:20。读源码时若追不到定义,别以为缺失,那是上游路径。
24.1.5 0.0.0-development 与 vendor 版本位
electron-versioning.md:252 一句话把 npm 侧说清:「All package.json:3 values are fixed at 0.0.0-development.」即 npm 包版本是发布管道注入的,仓库里永远是同一个固定值。这也意味着不能用 require('electron/package.json').version 判断源码版本,得读 process.versions.electron。
定制构建还有一条追加通道:buildflags.gni:22-26 的 electron_vendor_version 要求是 "key:value" 格式,buildflags/BUILD.gn:18-27 据此生成 HAS_VENDOR_VERSION=true 与 VENDOR_VERSION_NAME / VENDOR_VERSION_VALUE,再由上面两处 versions.SetReadOnly 写进 process.versions。于是分发方可以在不 fork 源码的前提下,给二进制打上自己的标识位。这是一个小而完整的「演进接口」:留一个编译期开关,而不是让下游改源码——与 24.9 的 fuse、24.10 的 [EnableIf] 是同一类设计。
24.1.6 一条实用判据
把上面几节压成一条排查动作:拿到一个自称 45.2.3 的二进制,依次核对 process.versions.electron(来自 tag)、process.versions.chrome(来自 Chromium chrome/VERSION)、process.versions.node(来自 Node)、以及是否存在 vendor 键。四者对不上,说明构建时用的 tag、DEPS 或 gn args 至少有一个不是这份源码树。第 22 章讲过发布时 zero_zip_date_time() 会让 checksum 与本地 dist.zip 不同;这里是同一问题的另一面:版本身份也不在 zip 里,而在二进制的宏里。
24.2 发布节奏与 SemVer:为什么补丁总在「追」
24.2.1 8 周、4 周 alpha、4 周 beta
electron-timelines.md 是节奏的权威来源,前 26 行给了三条硬约束:
<!-- docs/tutorial/electron-timelines.md:3,14-26 -->
Electron frequently releases major versions alongside every other Chromium release.
...
> [!IMPORTANT]
> Electron's official support policy is the latest 3 stable releases. Our stable
> release and end-of-life dates are determined by Chromium, and may be subject to
> change. While we try to keep our planned release and end-of-life dates frequently
> updated here, future dates may change if affected by upstream scheduling changes,
> and may not always be accurately reflected.
...
Electron's cadence between major version releases is 8 weeks long. Before each major
version hits stable, it goes through a four-week **alpha** phase and a four-week
**beta** phase.
:63-75 进一步限定支持面:只支持最新 3 个 stable major、每条线只支持最新 minor、最老的那条线只收安全修复。:82-83 给了根因——「Electron targets Chromium even-number versions, releasing every 8 weeks」,即大版本节奏由 Chromium 决定,不由 Electron 决定。:59-60 记了两次节奏调整史:Electron 6 起改为隔一个 Chromium major 发一次,Electron 16 起定为 8 周。
这条约束直接解释了补丁体系的形态:每 8 周,Chromium 换一个 major,17 个上游仓库的 checkout 点全部前移,380 个补丁要在新代码上重新应用一次。第 3、4 章讲的「e sync 之后跑 gclient hooks」不是一次性的构建准备,而是每个版本周期都要重跑的高频动作。
24.2.2 SemVer 表格的三层含义
electron-versioning.md:21-29 的表常被读成「版本号怎么加」,其实它同时是变更分类法:
| Major Version Increments | Minor Version Increments | Patch Version Increments |
|---|---|---|
| Electron breaking API changes | Electron non-breaking API changes | Electron bug fixes |
| Node.js major version updates | Node.js minor version updates | Node.js patch version updates |
| Chromium version updates | fix-related Chromium patches |
三行分别对应 Electron 自身、Node、Chromium 三个变更源。最要紧的是 :29 那句补充:「most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.」——Chromium 更新默认算 major,而能合回旧线的修复以 cherry-pick 形式变成补丁。这一句把 24.2 与 24.3 缝上了:全库 380 个补丁里 127 个文件名以 cherry-pick-<sha>.patch 开头,正是这条策略的产物(24.3.3)。
于是版本号的每一次跳动都有三种可能的物理含义:Electron 自己改了 API、Node 换了版本、Chromium 换了版本。排查「升级后行为变了」时,先看 DEPS 里 Chromium 与 Node 是否同时变了,比直接读 release note 更快。本书第 17 章网络栈、第 19 章打印、第 13 章合成这几处行为差异,多数能追到上游 major 而非 Electron 自己的改动。
24.2.3 commit 前缀就是版本号
electron-versioning.md:240-244 把版本号规则落到了 PR 标题上:
* Commits that would result in a SemVer **major** bump must start their body with `BREAKING CHANGE:`.
* Commits that would result in a SemVer **minor** bump must start with `feat:`.
* Commits that would result in a SemVer **patch** bump must start with `fix:`.
The `electron/electron` repository also enforces squash merging, so you only need to make sure that your pull request has the correct title prefix.
这与 24.3.3 的补丁命名统计同源:git.py:263-267 的 munge_subject_to_filename() 把 subject 里所有非 [A-Za-z0-9-] 的字符替换成下划线并转小写,于是 Subject: feat: add ... → feat_add_....patch,fix: → fix_,chore: → chore_。也就是说,补丁文件名前缀不是随手起的分类标签,是 commit 约定的序列化结果,而 commit 约定又直接决定下一个版本号怎么跳。一条从开发者敲下 PR 标题,到 8 周后版本号变化,再到补丁文件如何命名的链,就在这两处文件里闭合。
24.2.4 三个渠道与 main 分支
electron-versioning.md:246-252 定了分支与渠道:
## Versioned `main` branch
* The `main` branch always corresponds to the major version above the current pre-release line.
* Unstable nightly releases of `main` are released under the [`electron-nightly`](https://www.npmjs.com/package/electron-nightly) package on npm.
* Release branches are never merged back to `main`.
* All `package.json` values are fixed at `0.0.0-development`.
:14 的 npm install --save-dev electron@latest 与 :249-250 的 electron-nightly 构成两个公开渠道;beta/alpha 走预发布版本号(electron-versioning.md:125-180 有 -alpha.1 / -beta.1 标签示例)。「Release branches are never merged back to main」 是一条容易被忽略的工程约束:这意味着每个 backport 都是显式 cherry-pick,而不是合并分支。docs/breaking-changes.md:65 那句「This change was also backported to Electron 44.3.0, 43.7.0 and 42.11.3」就是这条约束的具体表现——同一个修复要人工落到三条旧线上,各发一个 patch 版本。
一个负面结论要如实记下:全树检索 dist-tag、npm publish、publishConfig、npmTag、distTag 均无命中,script/release/ 下只有上传器(upload.py / upload-symbols.py / upload-to-github.mts 等),本仓库不含 npm 发布脚本。渠道标签由外部 CI 管道决定,仓库内只负责产出 electron-api.json 与 electron.d.ts 这类资产(24.11.4)。把这点写清,是为了避免读者在树里徒劳地找「nightly 是怎么打 tag 的」。
24.2.5 Node 版本策略:偶数 LTS
electron-timelines.md:85-97 说明 Node 侧的规则:main 跟随进入 Active LTS 的偶数 Node 版本,stable 分支接收 Node 的 minor 与 patch 更新。这解释了 DEPS:6-7 为什么是 v24.22.2——24 是偶数 LTS,.22.2 是该线上的 minor/patch。对照 SemVer 表第二行,Node minor 更新只让 Electron 跳 minor,所以一条稳定线里出现多个 Electron minor,往往不是 Electron 加了功能,而是 Node 升了小版本。
这条规则有一个直接的工程后果:原生模块的 ABI 可能在 minor 版本之间变化。all.gn:5 的 node_module_version = 150 若随 Node minor 变动,@electron/rebuild 就得重跑。第 8 章讲 .node 加载、第 22 章讲打包时都提到过原生模块,其版本敏感性的根源在这里。
24.2.6 节奏如何塑造补丁集
把 24.2 收成一句因果:8 周节奏 + 上游三个变更源 + 只支持 3 条线 = 补丁必须同时具备「可重放」与「可丢弃」两种性质。可重放,因为每个周期要在新 checkout 上重新 git am 一遍;可丢弃,因为上游一旦接受重构,补丁就该从 .patches 里删掉。下一节开始的 24.3、24.4 分别讲这两种性质的实现:.patches 顺序文件负责重放,patches.md:7 的三类理由与 script/lint.js 的强制描述负责标注「何时可丢」。
第 4 章按「改了什么」给 380 个补丁分类,本章按「为什么能长期存在」再分一次类——这是同一批文件的两种读法,不是重复。
24.3 380 个补丁的地理与年代
第 3 章讲过 e sync 之后如何把补丁打进 Chromium,第 4 章按主题把 380 个补丁分了类。本节换一个视角:把这批文件当作一份时间档案,看它们分布在哪些仓库、按什么顺序、来自哪些年份。这三个数字决定了升级时的工作量与风险面。
24.3.1 config.json 只有两个字段
config.json:2-9 全文 19 行,是一个 17 元素的数组:
config.json:1-19
[
{ "patch_dir": "src/electron/patches/chromium", "repo": "src" },
{ "patch_dir": "src/electron/patches/boringssl", "repo": "src/third_party/boringssl/src" },
{ "patch_dir": "src/electron/patches/ffmpeg", "repo": "src/third_party/ffmpeg" },
{ "patch_dir": "src/electron/patches/v8", "repo": "src/v8" },
{ "patch_dir": "src/electron/patches/node", "repo": "src/third_party/electron_node" },
{ "patch_dir": "src/electron/patches/nan", "repo": "src/third_party/nan" },
{ "patch_dir": "src/electron/patches/libaddressinput", "repo": "src/third_party/libaddressinput/src" },
{ "patch_dir": "src/electron/patches/perfetto", "repo": "src/third_party/perfetto" },
{ "patch_dir": "src/electron/patches/squirrel.mac", "repo": "src/third_party/squirrel.mac" },
{ "patch_dir": "src/electron/patches/ReactiveObjC", "repo": "src/third_party/squirrel.mac/vendor/ReactiveObjC" },
{ "patch_dir": "src/electron/patches/webrtc", "repo": "src/third_party/webrtc" },
{ "patch_dir": "src/electron/patches/sqlite", "repo": "src/third_party/sqlite/src" },
{ "patch_dir": "src/electron/patches/skia", "repo": "src/third_party/skia" },
{ "patch_dir": "src/electron/patches/angle", "repo": "src/third_party/angle" },
{ "patch_dir": "src/electron/patches/pdfium", "repo": "src/third_party/pdfium" },
{ "patch_dir": "src/electron/patches/dawn", "repo": "src/third_party/dawn" },
{ "patch_dir": "src/electron/patches/minigbm", "repo": "src/third_party/minigbm/src" }
]
字段只有 patch_dir 与 repo,没有顺序、优先级、依赖声明。patches.md:23 那行目录树注释写得很直白:「config.json <-- this describes which patchset directory is applied to what project」。顺序由每个目录里的 .patches 文件维护(:19:「a .patches file which lists the order in which the patches should be applied」)。把「打到哪里」与「按什么顺序」拆成两份数据,是这套系统的第一个设计决定:新增上游仓库时只改 config,调整补丁次序时只改对应目录,两者互不干扰。
值得留意第 11 行:ReactiveObjC 的 repo 嵌在 squirrel.mac 的 vendor 子目录里。也就是说 17 个目标仓库不是 17 个平级依赖,而是包含嵌套。这解释了为什么 apply_all_patches.py:18-21 要检查 os.path.join(repo, '.git') 是否存在——未拉取的 gitlink 会留下空目录,git 会把它解析到父仓库去,静默地把补丁打到错误的地方。
24.3.2 逐目录计数:高度集中,且有一个空集
对 patches/*/*.patch 计数,结果与各目录 .patches 的行数逐个吻合(两个独立来源互相校验):
| 补丁目录 | 数量 | 补丁目录 | 数量 |
|---|---|---|---|
| chromium | 241 | pdfium | 3 |
| node | 58 | boringssl | 2 |
| v8 | 35 | ReactiveObjC | 2 |
| nan | 11 | squirrel.mac | 2 |
| angle | 8 | libaddressinput | 1 |
| skia | 6 | minigbm | 1 |
| ffmpeg | 4 | sqlite | 1 |
| dawn | 4 | webrtc | 1 |
| perfetto | 0 | ||
| 合计 | 380 |
三个结论直接可读。第一,241/380 ≈ 63.4% 集中在 Chromium,加上 Node 与 V8 是 334/380 ≈ 87.9%——升级风险几乎全部压在这三个仓库上,其余 14 个目录加起来只有 46 个。第二,第 3、4 章标题里的「380」是可复核的:ls patches/*/*.patch | wc -l 与 .patches 行数双向一致,不是文档里沿用的旧数字。第三,config.json:9 声明了 perfetto 补丁集,但 patches/perfetto/.patches 是 0 字节空文件、目录内 0 个 .patch:24.6.3 会讲清,Perfetto 的改动实际全部落在 node / chromium / v8 三个目录,这个空目录是为将来预留的挂载点,本身不产生任何构建行为。
第 3 点容易被误读成「Perfetto 支持还没做」。恰恰相反,2026 年的 11 个相关补丁已经在工作;空目录只是说明 Electron 至今没有需要直接改写 third_party/perfetto 源码的改动,因此保留 config 条目而不填内容。判断「某特性有没有实现」,看补丁内容比看目录是否存在可靠。
24.3.3 命名前缀是 commit 约定的投影
按文件名首段统计(^([A-Za-z0-9]+)_,cherry-pick-<sha>.patch 单独归类):
| 前缀 | 数量 | 含义来源 |
|---|---|---|
cherry-pick- | 127 | 上游提交的 SHA,非 Electron 命名 |
fix_ | 64 | fix: → patch bump |
feat_ | 27 | feat: → minor bump |
chore_ | 24 | chore:,工程性改动 |
build_ | 20 | 构建文件改动 |
src_ | 13 | Node 的 src/ 目录改动 |
test_ / refactor_ | 各 7 | 测试与重构 |
revert_ / allow_ / add_ | 各 6 | 撤销、放开、新增 |
expose_ | 5 | 暴露上游内部接口 |
分目录看更清楚:chromium 是 fix 40 / feat 24 / chore 15 / build 11 / revert 6 / refactor 6 / allow 6 / add 6,其余大量是 cherry-pick;node 是 fix 14 / src 12 / test 6 / build 6 / chore 5 / api 3;v8 的 35 个里 31 个是 cherry-pick-<sha>.patch。这个分布与 24.2.2 的 SemVer 策略完全对应:v8 目录几乎不写 Electron 自有的改动,只把上游修复拣回来;chromium 与 node 目录才承载真正的融合逻辑。
命名规则不是文档约定而是代码:git.py:263-267:
def munge_subject_to_filename(subject):
"""Derive a suitable filename from a commit's subject"""
if subject.endswith('.patch'):
subject = subject[:-6]
return re.sub(r'[^A-Za-z0-9-]+', '_', subject).strip('_').lower() + '.patch'
Subject: fix: use embedder perfetto client when available → fix_use_embedder_perfetto_client_when_available.patch:4。反过来也成立:git.py:270-283 的 get_file_name() 优先读取 patch 里的 Patch-Filename: 头,读不到才用 subject 反推。于是文件名、commit message、版本号三者构成一条可逆链——看到 feat_ 前缀,就知道它对应一次 minor bump 的提交。
24.3.4 年代分布:217 个补丁写在 2026 年
提取全部 380 个补丁的 Date: 行按年份统计:
| 年份 | 补丁数 | 年份 | 补丁数 |
|---|---|---|---|
| 2026 | 217 | 2020 | 17 |
| 2025 | 37 | 2019 | 17 |
| 2024 | 17 | 2018 | 24 |
| 2023 | 17 | 2016 | 1 |
| 2022 | 23 | ||
| 2021 | 10 |
grep -l '^Date: .*2026' patches/*/*.patch | wc -l = 217。 最早一例是 2016 年的 1 个补丁,2026 年一年就写了 57% 的补丁集。这个分布不能理解成「Electron 越来越需要改上游」——更准确的读法是:补丁集的主体会随上游大版本刷新而重写。Chromium 156 是 2026 年主线,Node v24.22.2 也是 2026 年的版本,每次 rebase 后大量补丁会以新 Date: 重新导出,因此年份分布反映的是当前 checkout 的刷新时间,而非每个改动的原始构思时间。
三个可直接核对的时间点:chore_register_node_as_a_dynamic_trace_category_prefix.patch:3 是 Tue, 31 Mar 2026;feat_carry_embedder_startup_data_in_createnewwindowreply.patch:3 是 Wed, 13 May 2026;fix_use_embedder_perfetto_client_when_available.patch:3 是 Fri, 7 Aug 2026。三者都是 23 章性能链路上的证据,第 23 章说的「2026 年补丁集」由此可验证。
24.3.5 .patches 为什么不带序号
patches.md:39 专门解释了不用 001- 前缀的理由:
the reason we use a
.patchesfile to maintain the order of applied patches, rather than prepending a number like001-to each file, is because it reduces conflicts related to patch ordering. It prevents the situation where two PRs both add a patch at the end of the series with the same numbering and end up both getting merged resulting in a duplicate identifier, and it also reduces churn when a patch is added or deleted in the middle of the series.
这是纯粹的多人协作工程经验:文件名带序号时,两个并行 PR 在末尾加补丁会撞号;插在中间则要让后续所有文件改名,diff 面积爆炸。改成纯文本清单后,加一行、删一行即可,git 把它当成一个文件的单行冲突。patches/chromium/.patches 前 30 行的实际形态:
1 build_gn.patch
2 build_resolve_pgo_profiles_from_electron_state_files.patch
3 accelerator.patch
4 blink_local_frame.patch
5 can_create_window.patch
6 disable_hidden.patch
7 dom_storage_limits.patch
8 render_widget_host_view_mac.patch
9 gin_enable_disable_v8_platform.patch
10 enable_reset_aspect_ratio.patch
...
27 build_add_electron_tracing_category.patch
28 worker_context_will_destroy.patch
29 frame_host_manager.patch
30 crashpad_pid_check.patch
顺序即语义:第 1、2 个必须先落(改 GN 构建文件与 PGO 路径解析),后续补丁才可能引用它们引入的接口。第 4 章按主题读这些文件时看不到这层约束,而升级排查恰恰常在这里——某个补丁失败,先查它在 .patches 里前面的依赖有没有被上游删掉。
24.4 补丁的生命周期:从「为什么存在」到落盘
24.4.1 每个补丁必须写出「何时能删」
patches.md:7-13 是整套体系的宪法:
Every patch in Electron is a maintenance burden. When upstream code changes, patches can break—sometimes without even a patch conflict or a compilation error. It's an ongoing effort to keep our patch set up-to-date and effective. So we strive to keep our patch count at a minimum. To that end, every patch must describe its reason for existence in its commit message. That reason must be one of the following:
- The patch is temporary, and is intended to be (or has been) committed upstream or otherwise eventually removed. Include a link to an upstream PR or code review if available, or a procedure for verifying whether the patch is still needed at a later date.
- The patch allows the code to compile in the Electron environment, but cannot be upstreamed because it's Electron-specific (e.g. patching out references to Chrome's
Profile). Include reasoning about why the change cannot be implemented without a patch (e.g. by subclassing or copying the code).- The patch makes Electron-specific changes in functionality which are fundamentally incompatible with upstream.
三类理由对应三种寿命:第 1 类有明确退出条件(上游合并后即删),第 2 类是编译适配(等上游重构出可注入点),第 3 类是永久性的(功能与上游目标冲突,理论上不会消失)。:13 还给出一句方针:「We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches」,并附了两个真实的上游协作链接。
把 24.3.3 的 127 个 cherry-pick 放回这里:它们大多属于第 1 类,是「等上游发布后即可删」的短期项;而 24.5 要讲的 can_create_window.patch、blink_local_frame.patch 这类,从第 1 章就存在的扩展点,多数属于第 3 类。一份补丁集的稳定性,不看总数,看第 3 类占多少、以及第 1 类是否真的在被清理。
24.4.2 lint 把「写理由」变成机器校验
规范若只写在文档里就会烂掉,所以 script/lint.js:273-279 用正则强制:
const regex = /Subject: (.*?)\n\n([\s\S]*?)\s*(?=diff)/ms;
const subjectAndDescription = regex.exec(patchText);
if (!subjectAndDescription?.[2]) {
console.warn(
`Patch file '${f}' has no description. Every patch must contain a justification for why the patch exists and the plan for its removal.`
);
return false;
}
即 Subject: 与 diff 之间必须有非空正文。package.json:121-124 的 lint-staged 把两条命令挂在 {*.patch,.patches} 上:
"{*.patch,.patches}": [
"node script/lint.js --patches --only --",
"node script/check-patch-diff.mts"
],
第二条 script/check-patch-diff.mts:5-11 用 export_all_patches.py --dry-run 重新导出一遍,检查磁盘上的补丁是否与上游仓库里的 commit 序列一致。也就是说提交一个补丁至少过两关:有没有写理由、有没有与工作树同步。全树检索 lint_patches.py 无命中,补丁检查是 lint.js 里名为 patches 的一门「语言」(script/lint.js:202-204 定义 key: 'patches'、roots: ['patches']、test: filename.endsWith('.patch'))。
一个具体例子说明正文写什么。chore_register_node_as_a_dynamic_trace_category_prefix.patch:6-14 解释了为什么不把 node 类别静态注册进 builtin_categories.h:静态注册走 constexpr ValidateCategories() 递归校验,加 node 类别会超过 512 的 constexpr 递归深度,得额外给 //base 加 -fconstexpr-depth;而动态注册同样无法上游化,于是「the minimal of the two changes is chosen here」。这段正文既给了退出条件(若上游放宽 constexpr 深度则可换方案),也给了验证方法(复现递归深度错误)。这就是第 1 类补丁该有的样子。
24.4.3 应用入口:gclient hooks 与并行 git am
补丁不在 GN 里应用,而在 DEPS 的 gclient hooks 里:
DEPS:113-120
DEPS:113-120
DEPS:113-120
# DEPS:113-152
pre_deps_hooks = [
{
'name': 'generate_mtime_cache',
'condition': '(checkout_chromium and apply_patches and use_mtime_cache) and process_deps',
'pattern': 'src/electron',
'action': [
'python3',
'src/electron/script/patches-mtime-cache.py',
'generate', '--cache-file', 'src/electron/patches/mtime-cache.json',
'--patches-config', 'src/electron/patches/config.json',
],
},
]
hooks = [
{
'name': 'patch_chromium',
'condition': '(checkout_chromium and apply_patches) and process_deps',
'pattern': 'src/electron',
'action': [
'python3',
'src/electron/script/apply_all_patches.py',
'src/electron/patches/config.json',
],
},
...
]
DEPS:34 的 'apply_patches': True 是总开关,DEPS:37 的 'use_mtime_cache': True 控制第二个 hook。script/apply_all_patches.py:42-52 揭示了并行策略:
def apply_config(config):
# Targets are independent git repos, so apply in parallel. The work is
# subprocess-bound (git am), so threads are sufficient. On roller/
# branches, patch conflicts are expected and interleaved failure output
# from multiple repos is hard to read, so force sequential there.
if is_roller_branch():
max_workers = 1
else:
max_workers = max(1, (os.cpu_count() or 4) - 2)
with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as pool:
futures = {pool.submit(apply_patches, t): t for t in config}
「17 个目标仓库互相独立,所以可以并行」是 24.3.1 那个扁平数组设计的直接收益;而 roller 分支上冲突是常态,并行输出会交错到无法阅读,于是强制 max_workers=1。这段注释比多数架构文档更能说明为什么补丁系统要用 Python 线程池而不是 GN action:这是 checkout 后的仓库级操作,与编译图无关。
script/apply_all_patches.py:13-30 里还有两个易漏的细节:THREEWAY = "ELECTRON_USE_THREE_WAY_MERGE_FOR_PATCHES" in os.environ 是三路合并开关;:18-21 明确注释「An unfetched gitlink leaves an empty dir, and git would resolve it to the parent repo」并 warnings.warn(f'repo not found: {repo}') 后跳过——这正是 24.3.1 嵌套仓库风险的兜底。
24.4.4 顺序与元数据:运行时注入,不落盘
.patches 清单如何变成一串 git commit,看 patches.py:6-13:
# script/lib/patches.py:6-8,14-40
PATCH_DIR_PREFIX = "Patch-Dir: "
PATCH_FILENAME_PREFIX = "Patch-Filename: "
...
def read_patch(patch_dir, patch_filename):
"""Read a patch from |patch_dir/filename| and amend the commit message with
metadata about the patch file it came from."""
ret = []
added_patch_location = False
patch_path = os.path.join(patch_dir, patch_filename)
with codecs.open(patch_path, encoding='utf-8') as f:
for l in f.readlines():
line_has_correct_start = l.startswith('diff -') or l.startswith('---')
if not added_patch_location and line_has_correct_start:
ret.append(f'{PATCH_DIR_PREFIX}{patch_dir}\n')
ret.append(f'{PATCH_FILENAME_PREFIX}{patch_filename}\n')
added_patch_location = True
ret.append(l)
return ''.join(ret)
def patch_from_dir(patch_dir):
"""Read a directory of patches into a format suitable for passing to
'git am'"""
with open(os.path.join(patch_dir, ".patches"), encoding='utf-8') as file_in:
patch_list = [line.rstrip('\n') for line in file_in.readlines()]
return ''.join([
read_patch(patch_dir, patch_filename)
for patch_filename in patch_list
])
关键判断:Patch-Dir: / Patch-Filename: 两行在磁盘上的任何 .patch 文件里都找不到(对 patches/ 全目录 grep Patch- 零命中)。它们是在 git am 输入流里动态插入的 commit message 元数据,导出时由 git.py:286-291 的 remove_patch_location() 剥掉,get_file_name() 则优先读它来恢复文件名。于是 .patch 文件保持干净可 upstream,而「它属于哪个目录、该叫什么名字」这些信息跟着 commit 走完整个 import/export 循环。
补丁头的全零 SHA 也有出处,git.py:214-236 的 format-patch 参数:
'format-patch',
'--keep-subject',
'--no-stat',
'--stdout',
'--no-signature',
# The name of the parent commit object isn't useful information in this
# context, so zero it out to avoid needless patch-file churn.
'--zero-commit',
# Some versions of git print out different numbers of characters in the
# 'index' line of patches, so pass --full-index to get consistent behaviour.
'--full-index',
'--ignore-submodules=all',
since
所以每个 .patch 首行都是固定的 From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001。--zero-commit 抹掉父提交哈希、--full-index 固定 index 行长度、--no-signature 去掉 git 版本签名——三个参数全是为了让重新导出的 diff 保持稳定,否则每次 rebase 都会产生几百个无关文件的改动。这与第 22 章 zero_zip_date_time() 抹 zip 时间戳是同一种工程直觉:确定性输出比信息完整更重要。
24.4.5 冲突处理与两条辅助链
patches.md:88-96 给了失败时的标准动作:
$ cd src/third_party/electron_node
# If the patch application failed midway through, you can reset it with:
$ git am --abort
# And then retry with 3-way merge:
$ ../../electron/script/git-import-patches -3 ../../electron/patches/node
:96 补充:三路合并若仍冲突,会停下来让人手工解决,之后 git add 加 git am --continue。script/git-import-patches:14-16 的 -3/--3way 就映射到 apply_all_patches.py:14 那个环境变量。patches.md:82 提到的 refs/patches/upstream-head 是「补丁应用前的上游 HEAD」,:74-79 的删除补丁流程第一步就是 git reset --hard refs/patches/upstream-head 回到干净基线再重放——因为补丁是 commit 序列,删一个也要重放后面全部。
两条辅助链值得记下,它们在排查构建异常时会冒出来:
script/patches-mtime-cache.py:14-20从patch_from_dir()的输出里筛出所有+++行,拼成被改动文件的路径清单,生成patches/mtime-cache.json;DEPS:141-152的apply_mtime_cachehook 再把这些文件的 mtime 恢复成缓存值。目的不是加速补丁应用,而是让增量编译只重编真正受补丁影响的文件——否则每次e sync都会让 Ninja 认为几百个上游文件变脏。script/patch-up.js:109在 CI 里用固定 commit message'chore: update patches'把重新导出的补丁推回 PR 分支;script/patches-stats.mjs:36-37,55,65统计补丁总数与总行数并上报 Datadog 指标electron.patches.count/electron.patches.lineCount。补丁数量是被持续监控的工程指标,这与patches.md:7的「maintenance burden」表述一致。
24.4.6 GN 侧唯一的补丁读取点
全树在 *.gn / *.gni 里搜 patch_dir、.patches、config.json,只命中一处实质逻辑——all.gn:19-31:
# Salt the hash V8 uses to key code caches and serialized wasm modules with a
# fingerprint of the patches we apply on top of the V8 release. Release
# branches cherry-pick V8 fixes without changing V8's own version number, so
# without this a build with a different patch set would still accept (and
# mis-link) serialized code written by the previous release. V8 hashes these
# files at `gn gen` time and re-runs gn whenever one of them changes.
_v8_patch_dir = "//electron/patches/v8"
v8_version_hash_salt_files = [ "$_v8_patch_dir/.patches" ]
foreach(_patch, read_file("$_v8_patch_dir/.patches", "list lines")) {
if (_patch != "") {
v8_version_hash_salt_files += [ "$_v8_patch_dir/$_patch" ]
}
}
这段注释把 24.2.2 的 cherry-pick 策略与第 23 章的 code cache 连了起来:release 分支 cherry-pick V8 修复时不会改 V8 版本号,若哈希盐不含补丁内容,新构建会误接受旧构建写下的序列化代码并错误链接。于是 GN 在 gn gen 时把 .patches 和全部 35 个 v8 补丁文件的内容一起哈希,补丁一变就重跑 gn、重算 code cache 键。第 23 章讲「构建期与运行期必须逐字节配套」时举的是 flags hash 与 source hash,这里补上第三重:V8 层面的补丁集指纹。
顺带回答「补丁是不是构建系统的一部分」:应用阶段不是(gclient hooks 负责),但补丁内容参与了构建图的哈希计算。这是两套系统唯一的交叉点,也解释了为什么改一个 v8 补丁会触发大范围重编。
24.4.7 一次完整的维护动作
把 24.4 压成可执行序列,供升级 Electron 或排查补丁冲突时照做:
| 步 | 命令 / 文件 | 目的 |
|---|---|---|
| 1 | DEPS:34 确认 apply_patches 开启 | 排除「根本没打补丁」 |
| 2 | 检查目标 repo/.git 是否存在 | 排除嵌套 gitlink 空目录 |
| 3 | 读对应目录 .patches,定位失败补丁的前置项 | 顺序即依赖 |
| 4 | git am --abort 回到干净状态 | 清掉半途应用的序列 |
| 5 | git-import-patches -3 <dir> 或设 ELECTRON_USE_THREE_WAY_MERGE_FOR_PATCHES | 让 git 用三路合并 |
| 6 | 手工解冲突后 git add + git am --continue | 继续后续补丁 |
| 7 | git-export-patches -o <dir> 重新导出 | 让磁盘与 commit 序列一致 |
| 8 | 提交前过 lint.js --patches 与 check-patch-diff.mts | 理由 + 同步双校验 |
第 7、8 步是很多人忽略的:补丁不是改完就完,必须重新导出并让 lint 校验正文。patches.md:56 还提醒重新导出时无关补丁的 shasum 可能变化,「generally harmless and can be ignored」但应一并提交,否则别人会在自己的 PR 里看到同样的噪声。这类细节不产生架构洞见,却决定了 8 周一次的重放能不能顺滑完成。
24.5 补丁作为架构的化石记录
24.3 数了补丁,24.4 讲了机制。本节回答第 3、4 章没正面处理的问题:把 380 个补丁按「为什么长期存在」再分一次类,能读出 Electron 架构里哪些缝合点从未变过、哪些是最近才被撕开的。方法是把本书前 23 章点名过的补丁文件,逐个放回 patches.md:7 的三类理由里。
24.5.1 一份跨章节对照表
| 本书章节 | 代表补丁 | 上游缺口 | 理由类别 | 稳定度 |
|---|---|---|---|---|
| 02 进程模型 | can_create_window.patch | 窗口创建需由嵌入方裁决 | ③ 功能不兼容 | 高 |
| 05 启动链路 | frame_host_manager.patch | 嵌入方需在 Frame 创建时注入 | ③ | 高 |
| 07 gin 绑定 | gin_enable_disable_v8_platform.patch | V8 platform 由 Electron 独占初始化 | ② 编译适配 | 高 |
| 08 模块加载 | node/pass_all_globals_through_require.patch | 需把 Electron 全局注入 Node 模块 | ③ | 高 |
| 08 模块加载 | node/build_modify_js2c_py_to_allow_injection_of_original-fs_and_custom_embedder_js.patch | 需往 Node 内建 JS 里注入 asar 包装 | ③ | 高 |
| 12 渲染初始化 | blink_local_frame.patch | Blink 不暴露 preload 注入点 | ③ | 高 |
| 13 视图系统 | osr_shared_texture_remove_keyed_mutex_on_win_dxgi.patch | Windows DXGI 共享纹理的互斥锁冲突 | ② | 中 |
| 14 IPC | 无上游补丁:接口定义在 api.mojom | Mojo 允许嵌入方自定义接口 | 不适用 | 高 |
| 17 网络栈 | build_add_electron_tracing_category.patch | 需 Electron 专属 trace 类别 | ② | 高 |
| 19 打印 / PDF | pdfium/ 3 个、chromium/ 打印相关 | 打印管线需嵌入方控制 | ③ | 中 |
| 20 崩溃报告 | crashpad_pid_check.patch | crashpad 的 pid 校验与多进程模型冲突 | ② | 高 |
| 23 性能 | node/electron_enable_node_startup_snapshot_generation_in_chromium_s_v8.patch | Node 快照需在 Chromium 的 V8 上生成 | ③ | 新 |
| 23 性能 | chore_register_node_as_a_dynamic_trace_category_prefix.patch | Node trace 类别需动态注册 | ② | 新 |
| 23 性能 | feat_carry_embedder_startup_data_in_createnewwindowreply.patch | 新窗回复需携带嵌入方启动数据 | ③ | 新 |
表里最右一列才是本节要点:前三章(进程、绑定、模块加载)对应的补丁全部落在 patches/chromium/.patches 的前 10 行或 patches/node/.patches 的前 8 行——它们既是应用顺序上的前置项,也是架构上最老的缝合点。而 2026 年的三个新补丁集中在启动与追踪,说明当前被撕开的位置不在进程模型,而在「启动关键路径」和「可观测性」。这条观察与第 23 章的结论互相印证:进程模型已经稳定到不需要新补丁,性能优化仍在改动上游接口。
24.5.2 第 3 类:不会消失的融合点
patches/node/.patches:1-8 前八项几乎定义了 Electron 与 Node 的整条边界:
1 build_add_gn_build_files.patch
2 pass_all_globals_through_require.patch
3 build_modify_js2c_py_to_allow_injection_of_original-fs_and_custom_embedder_js.patch
4 fix_handle_boringssl_and_openssl_incompatibilities.patch
5 feat_add_uv_loop_interrupt_on_io_change_option_to_uv_loop_configure.patch
6 support_v8_sandboxed_pointers.patch
7 build_ensure_native_module_compilation_fails_if_not_using_a_new.patch
8 fix_expose_the_built-in_electron_module_via_the_esm_loader.patch
第 2 项对应第 8 章讲的「require 里能看到 Electron 全局」,第 3 项对应第 22 章讲的 asar fs 包装如何被塞进 Node 内建模块,第 5 项对应第 6 章讲的 libuv 与 Chromium message loop 互相打断,第 6 项对应 V8 沙箱指针。这些改动的共同点是:上游不需要它们,甚至会因为它们而变得更复杂。Node 没有理由为「某个嵌入方想在 require 里注入全局」改自己的模块加载器,Chromium 也没有理由为「某个嵌入方想自己初始化 V8 platform」加开关。所以它们属于第 3 类,理论上永远不会被上游吸收。
这条判断有实用价值:升级 Electron 时,不必期待这些补丁消失。反过来,若某次升级后 pass_all_globals_through_require.patch 从 .patches 里没了,那多半不是上游接受了它,而是 Electron 换了一种实现方式(比如把全局注入搬进 bundle),应立刻去读第 8 章对应的模块注册表代码。
24.5.3 第 1、2 类:有退出条件的改动
平台与图形目录合计只有 46 个补丁(24.3.2),其中 angle 8、skia 6、dawn 4、pdfium 3、minigbm 1。这类改动多半是第 1 或第 2 类:某个平台 API 在特定版本上不兼容、某个图形后端需要 Electron 的窗口句柄、某个驱动路径需要放宽校验。它们的寿命取决于上游版本,因此每个 Chromium major 都可能让其中一批被删掉。
一个具体的第 1 类例子是 chore_register_node_as_a_dynamic_trace_category_prefix.patch(24.4.2 引过正文):作者明确写了「若走静态注册就要给 //base 加 -fconstexpr-depth,两种方案都无法上游化,故选改动最小的」。补丁正文里同时留了验证方法(复现 constexpr 递归深度),这正是 patches.md:9 要求第 1 类补丁提供的东西。读补丁正文比读补丁内容更能判断它的寿命。
24.5.4 从补丁名读「上游不提供什么」
把 24.5.1 的表竖着看,会得到一份「嵌入方需求清单」,每一项都是上游明确不给的能力:
| 上游不给 | Electron 的补法 | 影响到的章节 |
|---|---|---|
| 让嵌入方裁决窗口创建 | 在 CanCreateWindow 链上加回调 | 02、09、10 |
| 让嵌入方拥有 V8 platform | 加 gin_enable_disable_v8_platform 开关 | 05、06、07 |
| 让嵌入方注入脚本到 Blink 帧 | 暴露 blink::LocalFrame 钩子 | 12、15 |
| 让嵌入方打包自己的内建 JS | 改 js2c.py 允许注入 | 08、22 |
| 让嵌入方复用已编译的 preload | CreateNewWindowReply 携带 BigBuffer | 12、23 |
| 让嵌入方的 trace 类别生效 | 动态注册 + legacy macro shim | 23、24 |
这份清单就是「Electron 是什么」的另一种答案:它不是 Chromium 加 Node,而是 Chromium 与 Node 上这些「嵌入方插槽」的总和。第 1 章从目录结构讲缝合线,本节从补丁清单讲同一件事,且多了一层时间维度——插槽有老有新,新的那些正在被写进 2026 年的补丁里。
24.5.5 哪些算历史包袱
「历史包袱」不能靠感觉判断,用 24.4.1 的三类理由加两个可查条件来定:补丁正文里写着「一旦上游接受某改动即可删」,且该上游改动至今未发生。按这个口径,fix_handle_boringssl_and_openssl_incompatibilities.patch(第 4 项)与 resource_file_conflict.patch 属于典型:前者处理 BoringSSL 与 OpenSSL 的符号冲突,后者处理 //chrome 的 .pak 文件与 Electron 自己的资源冲突,两者都是「因为 Electron 的构建布局不同于 Chrome」而存在,而上游没有任何动力改自己的布局。
反过来,第 2 类里那些「因为 Electron 不用 Chrome 的 Profile 而必须 patch 掉引用」的改动,虽然是纯粹的历史包袱,却也最容易被误判成可以删——patches.md:10 专门要求这类补丁写清「为什么不能用子类化或复制代码代替」。判断能不能删,先读正文里的替代方案论证,而不是看 diff 有多小。
24.5.6 哪些正在被上游吸收:200 个补丁带着上游链接
第 23 章末尾预告过「哪些正在被上游吸收」。这一问有可复核的答案,且答案不在路线图里,而在补丁正文本身。patches.md:13 是整套体系的退出策略原文:
In general, all the upstream projects we work with are friendly folks and are often happy to accept refactorings that allow the code in question to be compatible with both Electron and the upstream project. (See e.g. this change in Chromium, which allowed us to remove a patch that did the same thing, or this change in Node, which was a no-op for Node but fixed a bug in Electron.) We should aim to upstream changes whenever we can, and avoid indefinite-lifetime patches.
两个链接说明了「吸收」的两种形态:Chromium CL 1637040 让上游自己提供了 Electron 需要的能力,于是对应补丁被删;Node PR 22110 对 Node 是空操作,却修好了 Electron 的 bug,同样让一个补丁失去存在理由。上游吸收不是「Electron 把代码推上去」,而是「上游改出一个可注入点,Electron 不再需要改它的源码」。这与 24.5.2 说的第 3 类补丁形成对照:第 3 类之所以长期存在,正是因为没有这样的注入点。
把这条策略量化:对 380 个补丁检索正文里的上游链接,200 个文件命中(grep -lE 'PR-URL:|chromium-review.googlesource|github.com/nodejs/node/pull|googlesource.com/c/chromium'),细分是 185 个含 Chromium code review 链接、18 个含 github.com/nodejs/node/pull、8 个含 PR-URL: 头。另有 45 行 PR-URL: / Reviewed-By: / Refs: 元数据。这组数字说明 24.4.1 的第 1 类理由不是少数派:过半补丁的正文里都留了「去哪里核对上游状态」的线索。
一个具体样本是 build_perfetto-sdk.patch:1-10:
From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Chengzhong Wu <legendecas@gmail.com>
Date: Sun, 2 Nov 2025 21:43:58 +0000
Subject: build: perfetto-sdk
Signed-off-by: Chengzhong Wu <cwu631@bloomberg.net>
PR-URL: https://github.com/nodejs/node/pull/64565
Refs: https://github.com/nodejs/diagnostics/issues/654
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ryuhei Shima <shimaryuhei@gmail.com>
它把上游 PR 的完整元数据搬进了补丁集,git.py:215 的 --keep-subject 保证 subject 不被改写。这类补丁属于最典型的第 1 类:上游 PR 已存在,Electron 只是提前把它拣进自己的 checkout;一旦 Node 发布包含该 PR 的版本,它就可以从 patches/node/.patches 里删掉。24.3.3 说 v8 目录 35 个补丁里 31 个是 cherry-pick-<sha>.patch,同属这一形态。
于是「这个补丁还能不能删」有了三步可执行的判据:① 读补丁正文,看它属于 24.4.1 的哪一类、有没有写退出条件或验证方法;② 按正文里的链接查上游状态(review 是否已合、PR 是否已进 release);③ 在新 checkout 上从 .patches 删掉该行,按 24.4.7 的序列重放并跑构建与 spec。第 ③ 步是唯一可靠的验证——patches.md:7 那句「patches can break sometimes without even a patch conflict or a compilation error」正是在警告:补丁消失后可能安静地产生错误行为。
最后一条阴性结论:本树没有自动判定「上游已合并」的工具。script/patches-stats.mjs:36-37,55,65 只上报补丁总数与总行数,script/check-patch-diff.mts 只校验磁盘与 commit 序列一致,script/lint.js:273-279 只校验正文非空。寿命判断完全靠人按上面三步做。这与 24.8.6 第 5 步「backport 没有自动校验」是同一类边界:Electron 把可自动化的部分(顺序、结构、一致性)做成了机器校验,把需要判断的部分(何时删补丁、要不要 backport)留在 PR 审查里。把这条记住,就不会误以为「补丁集被 CI 完整看管着」。
24.6 三条正在发生的主线
「展望」要落在可验证的当下。用两个条件从 380 个补丁里筛本节素材:Date: 在 2026 年、且改动的是 Electron 自有设施而非上游 bug 修复。筛出三条主线:bundler 换核、Node 启动快照重新启用、Node trace 汇入 Chromium Perfetto。第 23 章已经从性能角度讲过后两条,这里从演进方式讲:它们是怎么被引入的、留了什么兼容开关。
24.6.1 主线一:rolldown 取代 webpack
package.json:36 声明 "rolldown": "^1.2.8",:82-83 的 scripts 是 "bundle": "node build/bundle/bundle.mjs" 与 "typecheck": "node build/bundle/typecheck.mjs"。入口文件开头就写明立场:
bundle.mjs:1-14
// Builds one of Electron's internal JavaScript bundles (see targets.mjs) with
// rolldown. Driven by the `electron_bundle` GN template in bundle.gni:
//
// node build/bundle/bundle.mjs --target renderer \
// --output-path out/gen --output-filename renderer_init.js \
// --buildflags out/gen/electron/buildflags/buildflags.h --mode production
...
import { rolldown } from 'rolldown';
全树检索 webpack 只剩两处,都在 bundle.mjs:127-128 的对比注释里(:125 解释 inject 类似 webpack 的 ProvidePlugin、:151 解释为什么要保留 lazy require)——没有任何 webpack 依赖、配置或脚本。这条是可精确判定的:第 8 章讲的「七个 bundle」在 45.2.3 里已经换了生成器,bundle 的划分与注册表设计仍在,但产出它们的工具从 webpack 变为 rolldown。
迁移时真正费功夫的不是换 bundler,而是保住旧语义。bundle.mjs:124-129:
// Free variables that are rewritten to imports of an internal module, like
// webpack's ProvidePlugin. Every bundle captures the original Promise so that
// user land replacing the global does not affect Electron.
const inject = {
Promise: ['@electron/internal/common/primordials', 'Promise']
};
以及 :146-151 那段更关键的注释:Node 环境下 bundle 用的是 Node 内部 require,若直接生成顶层 import,会被提升到 bundle 最上方变成一次性 require();因此改用一行 CommonJS shim 转发,让内建模块在实际用到时才加载,「as it was with webpack」。也就是说,换 bundler 的验收标准不是能构建,而是不能改变第 8 章描述的懒加载时序——启动路径上多一个顶层 require 就是回归。
其余迁移痕迹:bundle.mjs:177-194 的 rolldown() 调用里 platform: target.alwaysHasNode ? 'node' : 'browser'、四个自定义插件(aliasPlugin、nodeExternalsPlugin、buildflagPlugin、graphPlugin)、以及把 warn 提升为 error 的 onLog;bundle.mjs:8-10 说明 --print-graph 供 script/gen-filenames.mts:72 同步 filenames.auto.gni;bundle.gni:51-53 把 //electron:electron_lib_typecheck 列为依赖并注释「rolldown only strips types; refuse to bundle code that does not check」。最后一条是迁移带来的新约束:rolldown 只擦类型不做检查,所以类型检查被前移成独立的 GN target,否则类型错误会静默进入产物。
24.6.2 主线二:Node 启动快照「重新启用」
第 23 章强调过这不是「一直开启」。electron_enable_node_startup_snapshot_generation_in_chromium_s_v8.patch:1-14 的正文直接给了动机:
From: Samuel Attard <sattard@anthropic.com>
Date: Tue, 19 May 2026 10:37:56 +0100
Subject: electron: enable node startup snapshot generation in Chromium's V8
Re-enable node_use_node_snapshot so node_mksnapshot generates an embedded
Node startup snapshot the Electron browser process can be created from,
eliminating the Node bootstrap recompile.
- node.gni: enable the snapshot (and the builtins' code cache that
关键词是 Re-enable:这个开关曾经开过、后来被上游条件关掉、现在由补丁重新打开。:93 删掉原有的 node_use_node_snapshot = (host_os == target_os) && !(host_cpu == "arm64" && target_cpu == "x64"),:107 改成 node_use_node_snapshot = node_snapshot_toolchain_runs_target_code,把「同平台且非交叉编译」的旧判据换成「工具链能否跑目标代码」的新判据;:344、:367、:386、:394、:530、:556 还有六处配套改动。
消费端在 BUILD.gn:1000-1013:
{
name = "utility"
flags = "--rehash-snapshot --no-freeze-flags-after-init"
node_builtins = !node_use_node_snapshot
},
...
# The browser flavor is special-cased below when a Node startup snapshot is
node_builtins = !node_use_node_snapshot 是整条链最值得记的一行:启用快照时不再编入 Node 内建 JS 源码,关闭时才需要。它把「构建期生成」与「运行期回退」做成一个布尔互补关系。第 23 章讲 loadBrowserProcessSpecificV8Snapshot fuse 会触发性能反噬,根因就在这里——那个 fuse 让主进程走另一条快照路径,最终退回从源码 bootstrap Node,正好抵消本补丁要消除的重编译。
从演进角度看,这条主线展示的是上游条件变化时的应对方式:不改 Electron 自己的代码,而是在 Node 的 node.gni 上打一个补丁,把开关判据换成 Electron 需要的语义,并在补丁正文里写清「eliminating the Node bootstrap recompile」这个可验证目标。补丁名的 electron_ 前缀(git.py:263-267 的规则)也标明了它是 Electron 专属、不会上游化。
24.6.3 主线三:Perfetto 汇流与「嵌入模式」
11 个相关补丁分布在 chromium 1、node 9、v8 1,patches/node/.patches 的第 44–51 行是密集区:
44 build_perfetto-sdk.patch
45 lib_add_perfetto_support.patch
46 src_fix_trace_macro_compatibility.patch
47 src_add_perfetto_trace_agent.patch
48 src_fix_perfetto_build_on_gettracefilepath.patch
49 src_test_disable_trace_events_tests_when_perfetto_is_enabled.patch
51 fix_use_embedder_perfetto_client_when_available.patch
核心动机写在最后一个补丁的正文里(fix_use_embedder_perfetto_client_when_available.patch:6-20):
Node.js v24.19.0 introduces a standalone perfetto SDK tracing agent which
initializes an in-process backend, creates independent tracing sessions,
and writes pftrace files. Electron already owns a process wide perfetto
client through Chromium, so creating Node.js owned clients in browser,
renderer processes duplicates tracing infrastructure and produces recording
state independent of contentTracing.
Keep Node.js standalone SDK capability behind `node_use_perfetto_sdk` for
ELECTRON_RUN_AS_NODE.
For embedded Electron processes, do not create Node.js tracing Agent.
Instead, register Node.js TrackEvent data source with Chromium
perfetto client. This preserves node.* event emission while
allowing contentTracing to remain the sole owner of category filtering,
recording sessions, output, and lifecycle.
这段正文把第 23 章的十条补丁串成一条因果:Node v24.19.0 上游新增了独立 Perfetto agent → Electron 已有 Chromium 的进程级 client → 两套并存会分裂会话状态 → 于是嵌入进程不建 agent 只注册 TrackEvent 数据源,独立能力仅保留给 ELECTRON_RUN_AS_NODE(此时没有 Chromium client,需要 Node 自己写 pftrace)。:32 的 + node_use_perfetto_sdk = true 与 :389 的 if (node_use_perfetto_sdk) 是这个分叉的实现。
另外两个补丁说明了「汇流」的代价:src_use_legacy_trace_macros_in_perfetto_to_support_all_phases.patch:1-22 为支持全部 phase 把 SDK 的分 phase 宏换回 legacy shim;chore_register_node_as_a_dynamic_trace_category_prefix.patch:4-24 让 node 成为动态 trace 类别前缀(24.4.2 已引正文)。第 23 章记下的「GLOBAL instant 降级成 THREAD」就是前一处的直接后果。
24.6.4 三条主线的共同形状
把三条并排看,会发现它们是同一种演进动作:
| 主线 | 上游发生了什么 | Electron 的应对 | 留的兼容开关 |
|---|---|---|---|
| rolldown | 自研工具链替换 webpack | 换生成器,用 shim 保住 lazy require | platform: 分叉、独立 typecheck target |
| Node 快照 | 上游收紧 node_use_node_snapshot 条件 | 打补丁重开,换判据 | node_builtins = !node_use_node_snapshot |
| Perfetto | Node v24.19.0 新增独立 SDK agent | 嵌入进程不建 agent,只注册数据源 | node_use_perfetto_sdk 留给 ELECTRON_RUN_AS_NODE |
三者的共同句式是:上游给了一个「独立运行时」的能力,Electron 需要把它改造成「嵌入模式」。rolldown 是自己的工具选择,但同样要保住 Node 内部 require 的惰性;快照与 Perfetto 更直接,都是把「Node 自己拥有一份」改成「与 Chromium 共享一份」。第 6 章讲「两个事件循环共享一个进程」、第 23 章讲「单一 Perfetto 会话所有者」,本质上都是这个句式在不同年代的实例。
这也给「展望」一个不注水的落点:下一轮上游升级,最先出问题的仍是这类「谁拥有一份」的接口。判断方法很具体——看新补丁的正文里有没有 embedder、process wide、sole owner、standalone 这类词。24.6.3 那段正文里四个词占了三个,不是巧合。
24.6.5 一条边界:什么算「正在演进」
最后明确本章使用「正在演进」的口径,避免把任何新代码都算进去:需同时满足三条——① 有 2026 年的补丁或新增 buildflag 作为引入痕迹;② 存在明确的分叉开关或回退路径(node_use_perfetto_sdk、node_builtins、[EnableIf]);③ 文档或补丁正文里给出了尚未稳定的信号(_Experimental_ 标记、补丁的三类理由之一)。按这个口径,ENABLE_PROMPT_API 与 66 处实验性标记也在此列(24.12),而 utilityProcess、webUtils 这类已有完整 spec 与文档的 API 不算(24.11)。
24.3.2 那个空的 patches/perfetto/ 目录正好作为反例:它满足「预留了位置」,却不满足①(无补丁内容),因此不能算「Perfetto 支持正在开发」,只能算「config 里保留了一个尚未使用的挂载点」。把这类反例排除掉,本章剩下的「展望」才都是能指向文件行号的。
24.7 弃用机制:一个布尔变量撑起的兼容期
第 24.0.2 提到的第一条纠偏在这里展开。旧版 Electron 的弃用体系有一组广为流传的印象:环境变量 ELECTRON_ENABLE_DEPRECATION_WARNINGS、deprecate.removeIn()、把告警转发到 app 事件的 handler、用一个 Set 记录已告警项。在 45.2.3 里这四样都不存在,deprecate.ts 全文只有 164 行,换成了更贴近 Node 标准的一套实现。
24.7.1 十一个导出,四类动作
| 函数 | 行号 | 动作 |
|---|---|---|
warnOnce(oldName, newName?) | :5-11 | 返回一个「首次调用才告警」的函数 |
warnOnceMessage(msg) | :13-21 | 同上,直接给消息 |
setHandler / getHandler | :23-29 | 替换告警出口 |
warn(oldName, newName) | :31-35 | 每次调用都告警 |
log(message) | :37-47 | 分发到 handler 或 console |
removeFunction / renameFunction | :50-70 | 包装函数,触发时告警 |
event(emitter, oldName, newName, transformer) | :73-91 | 事件名迁移 |
removeProperty / renameProperty | :94-155 | 属性访问器迁移 |
moveAPI(fn, oldUsage, newUsage) | :157-163 | 整段调用方式迁移 |
前五个是告警内核,后六个是迁移工具:它们让一个 API 在「仍能工作」的同时,把旧名字、旧事件、旧属性访问自动转发到新实现并打一条警告。这正是 docs/breaking-changes.md:14 对 Deprecated 的定义——「will continue to function, but will emit a deprecation warning, and will be removed in a future release」——在代码里的兑现方式。
24.7.2 「只发一次」是闭包,不是集合
deprecate.ts:5-21
export function warnOnce(oldName: string, newName?: string) {
return warnOnceMessage(
newName
? `'${oldName}' is deprecated and will be removed. Please use '${newName}' instead.`
: `'${oldName}' is deprecated and will be removed.`
);
}
export function warnOnceMessage(msg: string) {
let warned = false;
return () => {
if (!warned && !process.noDeprecation) {
warned = true;
log(msg);
}
};
}
warnOnce() 在模块加载时被调用一次,返回一个带着自己 warned 变量的函数;调用方把这个函数挂在旧 API 的入口上。于是去重粒度是每个被弃用的 API 各自一个闭包,不需要全局 Set、不需要按消息字符串做键、也不会因为两条告警文本相同而互相吞掉。spec/deprecate.spec.ts:170-183 的用例名就是 warns only once per item,:179-182 连读三次属性、断言 messages 长度始终为 1。
这个实现有一个容易忽略的边界:warned 是模块实例级状态。第 8 章讲过 Electron 的 bundle 按进程分别加载,主进程与每个渲染进程各有自己的 deprecate 模块副本,因此「只发一次」是每进程一次,不是整个应用一次。多窗口应用看到同一条告警出现多次,符合源码语义,不是 bug。
24.7.3 开关全部换成 Node 标准
deprecate.ts:31-47
export function warn(oldName: string, newName: string): void {
if (!process.noDeprecation) {
log(`'${oldName}' is deprecated. Use '${newName}' instead.`);
}
}
export function log(message: string): void {
if (typeof deprecationHandler === 'function') {
deprecationHandler(message);
} else if (process.throwDeprecation) {
throw new Error(message);
} else if (process.traceDeprecation) {
return console.trace(message);
} else {
return console.warn(`(electron) ${message}`);
}
}
四个分支的优先级值得逐条读:自定义 handler 最优先;其次 process.throwDeprecation 让弃用变成抛异常(CI 里把兼容期债务暴露出来的常用手段);再其次 process.traceDeprecation 打调用栈;最后才 console.warn,且统一加 (electron) 前缀。全仓检索 ELECTRON_ENABLE_DEPRECATION_WARNINGS、enableDeprecationWarnings、removeIn 均无命中,命中的 process.* 开关只出现在 deprecate.ts:16,32,40,42 与 spec/deprecate.spec.ts:16,18,22。
换句话说,Electron 不再为弃用告警发明环境变量,直接复用 Node 的三个标准开关。这带来一个实用的 CI 配方:ELECTRON_RUN_AS_NODE 之外,用 --throw-deprecation 启动应用,就能让所有仍走旧 API 的调用直接失败——第 21 章讲的 spec 若想守住「不许用弃用 API」,靠的正是这个而不是自定义事件。
24.7.4 C++ 侧走 process.emitWarning()
原生模块的弃用不能走 TS 模块。声明在 node_util.h:37-45,实现在 node_util.cc:117-136:
void EmitDeprecationWarning(v8::Isolate* isolate,
const std::string_view warning_msg,
const std::string_view deprecation_code) {
node::Environment* env =
isolate ? node::Environment::GetCurrent(isolate) : nullptr;
if (!env) {
// No Node.js environment available, fall back to console logging.
LOG(WARNING) << "[DeprecationWarning] " << warning_msg
<< " (code: " << deprecation_code << ")";
return;
}
node::ProcessEmitWarningGeneric(env, warning_msg, "DeprecationWarning",
deprecation_code);
}
关键在于没有 Node 环境时的降级分支:拿不到 isolate 或 Environment(例如某些纯 Chromium 线程)就只写日志,不强造一个。C++ 侧的「只发一次」用 static bool,例见 electron_api_native_image.cc:322-327:getBitmap() 弃用转 toBitmap() 时,deprecated_warning_issued 是函数内静态变量。同类实现还有 electron_api_native_image_mac.mm:166-184、electron_api_web_frame.cc:949-987、electron_api_crash_reporter.cc:310-312。
于是两套实现、一个语义:JS 侧闭包布尔,C++ 侧函数静态布尔,都走 process.emitWarning / DeprecationWarning 这条路。把「只发一次」放在每个弃用点自己身上,是这套设计最简洁的地方,也解释了为什么全局 Set 被删掉了——它本来就不必要。
24.7.5 45.0 的实例如 safeStorage
safe-storage.ts:1,5-7,15,22 是本版本刚加上去的三处(中间跳过绑定与包装代码):
import * as deprecate from '@electron/internal/common/deprecate';
const isEncryptionAvailableDeprecated = deprecate.warnOnce(
'safeStorage.isEncryptionAvailable',
'safeStorage.isAsyncEncryptionAvailable'
);
const encryptStringDeprecated = deprecate.warnOnce('safeStorage.encryptString', 'safeStorage.encryptStringAsync');
const decryptStringDeprecated = deprecate.warnOnce('safeStorage.decryptString', 'safeStorage.decryptStringAsync');
对应 docs/breaking-changes.md:237 的 Deprecated 条目:三个同步方法被标为弃用,推荐异步版本。把这两处并排看,能读出完整兼容期协议:文档声明至少提前一个 major 版本(docs/breaking-changes.md:3)、代码同版本挂上 warnOnce、旧实现继续工作、未来某个 major 才真正移除。第 20 章讲 fuse 时说过「fuse 是打包期的一次性决策」,弃用则是「源码期的渐进式决策」,两者是 Electron 处理向后兼容的两套互补工具。
而且这一条给了本章唯一一个明确到目标版本的时间点。docs/breaking-changes.md:237-241 写的是:
The synchronous
safeStoragemethods are deprecated and will be removed in Electron 46, following Chromium's removal of the synchronous OSCrypt backend they are built on. Use the asynchronous methods instead, which use the same per-platform key stores.
safe-storage.md:12 复述了同一句,全树对 docs/ 检索 Electron 46 只命中这两行。所以 45.2.3 里没有成体系的「下个版本会移除什么」清单,只有这一个由上游变化驱动的实例:Chromium 删掉同步 OSCrypt 后端,Electron 的同步 safeStorage 便失去实现基础。它与 24.5.6 的「上游吸收」是同一枚硬币的两面——上游改出可注入点,补丁可以删;上游删掉底层能力,API 必须跟着移除。判断「某个弃用会不会真删」,看它有没有这样的上游根因,比看告警文本可靠。
其它调用点:session.ts:27,57,65,87,94,101,108、web-contents.ts:147-201(warnOnce / warnOnceMessage / moveAPI)。后者用 moveAPI 处理整段调用方式迁移,是比属性改名更粗粒度的工具。
24.7.6 一条负面结论:setHandler 没有生产调用者
全局检索 setHandler,除定义处外只命中 spec/deprecate.spec.ts 与 net-websocket.ts:303,309,315,321,325(后者是该文件自己的同名本地函数,与弃用模块无关)。也就是说 45.2.3 的生产代码不再把弃用告警转发到 app 事件,旧版那种 app.on('deprecation-warning', ...) 的写法在本树无对应实现。全树也没有 ELECTRON_ENABLE_DEPRECATION_WARNINGS。
这条阴性结果比正面清单更值得记:升级应用时若还在监听某个弃用事件,不会报错、也不会被调用,只会静默失去观测。正确替代是 24.7.3 的三个 Node 标准开关,或直接在 deprecate.ts 的 log() 上设 handler(那是内部模块,应用代码一般够不着,所以更推荐前者)。
24.8 破坏性变更的文档机器
弃用是代码侧,破坏性变更是文档侧。Electron 把后者做成了一份机器可校验的数据,而不是一篇给人读的 changelog。这是本章最值得单独讲的一套机制。
24.8.1 五类标注定义了「什么算破坏」
docs/breaking-changes.md:1-15:
# Breaking Changes
Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least [one major version](tutorial/electron-versioning.md#semver) before the change is made.
Note that breaking changes listed for future releases are always subject to change.
### Types of Breaking Changes
This document uses the following convention to categorize breaking changes:
* **API Changed:** An API was changed in such a way that code that has not been updated is guaranteed to throw an exception.
* **Behavior Changed:** The behavior of Electron has changed, but not in such a way that an exception will necessarily be thrown.
* **Default Changed:** Code depending on the old default may break, not necessarily throwing an exception. The old behavior can be restored by explicitly specifying the value.
* **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release.
* **Removed:** An API or feature was removed, and is no longer supported by Electron.
五类的判据不是「改动多大」,而是旧代码会不会抛异常、能不能靠显式传值恢复。第三类 Default Changed 单独列出尤其重要:24.13 要讲的三次安全默认值翻转全部属于这一类,它们的共同特征是应用代码一行没改却可能出问题,且只要把旧值显式写出来就能恢复。第 24.2.3 的 SemVer 表把「Electron breaking API changes」归 major,而这里把 breaking 细分成五种可操作的具体形态。
第 3 行「at least one major version before」是兼容期的硬承诺,deprecate.ts 就是它的代码侧兑现(24.7.5)。第 5 行「listed for future releases are always subject to change」则解释了为什么全树找不到 Planned Breaking API Changes 这样的独立段落:未来计划不再单列,全部并入按版本组织的正文,只留这一句免责声明。检索 Planned Breaking API Changes、Forthcoming 均无命中,唯一相关的是 :5。
24.8.2 三个可复核的数字
| 指标 | 数值 | 复核命令 |
|---|---|---|
| 文件总行数 | 3606 | wc -l docs/breaking-changes.md |
## Breaking API Changes (X.0) 段 | 44 个 | grep -c '^## Breaking API Changes' |
### Deprecated: 条目 | 54 个 | grep -c '^### Deprecated:' |
44 个版本段从 45.0(:17)一路排到 2.0(:3508),中间没有断档。几个关键锚点::259 是 44.0、:602 是 43.0、:679 是 42.0、:759 是 41.0、:781 是 40.0、:794 是 39.0、:876 是 37.0、:1318 是 30.0(BrowserView 弃用)、:1786 是 24.0、:2098 附近是 20.0 的默认 sandbox、:2470 是 12.0 的 contextIsolation、:3181 是 5.0 的三项默认值。
44 个连续段落本身就是一份版本史:它覆盖了从 2.0.0 采用 SemVer(electron-versioning.md:5)至今的全部 major。第 24.2.1 说「8 周一个 major、只支持最新 3 条线」,于是这份 3606 行文档里,绝大多数内容对当前版本已不适用——它的价值不是指导当下,而是在排查「某行为是哪一代变的」时提供可定位的时间坐标。本书第 10 章讲 BrowserWindow 从「窗口即页面」到「窗口是容器」、第 15 章讲隔离世界默认值,都能在这里找到对应的版本段。
24.8.3 YAML history 把文档与变更记录绑起来
单个 API 文档不是自由文本,开头带一段被 <!-- ... --> 注释包起来的结构化元数据。browser-view.md:3-9 的注释体内,是一个标为 YAML history 的代码围栏,内容如下:
deprecated:
- pr-url: https://github.com/electron/electron/pull/35658
breaking-changes-header: deprecated-browserview
:11-13 的正文则用 NOTE 明确写出 BrowserView 已被 WebContentsView 取代。
breaking-changes-header: deprecated-browserview 是一个锚点,指向 24.8.2 里 :1318 那条 30.0 的 Deprecated: BrowserView 条目。也就是说 API 文档与变更记录之间存在可校验的引用关系,不是靠人工保持一致。四种统计口径能说明这套元数据的规模:
| 口径 | 命中 | 文件数 |
|---|---|---|
deprecated / Deprecated 全部字样 | 199 行 | 18 |
_Deprecated_(标题上标注 API) | 82 处 | 14 |
deprecated:(YAML history 键) | 34 处 | 5 |
breaking-changes-header: deprecated | 40 处 | 7 |
_Deprecated_ 的分布:protocol.md 14 处、web-contents.md 32 处、session.md 8 处、browser-window.md 7 处(集中在 :483、:1789-1837 的 BrowserView 相关方法)、browser-view.md 6 处、notification.md 3 处、safe-storage.md 3 处、native-image.md 2 处、web-frame.md 2 处等,另有 web-preferences.md:1 与 base-window-options.md。第 24.7.5 的 safeStorage 三处正好落在这份表里。
24.8.4 lint 让结构成为契约
package.json:65:
"lint:api-history": "lint-roller-markdown-api-history --root \"./docs/api/\" --schema \"./docs/api-history.schema.json\" --breaking-changes-file \"./docs/breaking-changes.md\" --check-placement --check-strings \"*.md\"",
四个参数把校验内容说全了:以 docs/api-history.schema.json 校验 YAML 块结构、以 docs/breaking-changes.md 校验锚点确实存在、--check-placement 校验块放在正确位置、--check-strings 校验字符串格式。它被串在 package.json:58 的 lint:docs 里,与 js-in-markdown、fmt-in-markdown、ts-check-js-in-markdown、docs-fiddles、docs-relative-links、markdown 并列。
于是 24.8.1 的五类标注不只是写作规范:每条 breaking-changes-header 都必须在 3606 行文档里找到一个真实存在的锚点,否则 lint 失败。这就是本章说的「机器可校验」——把「文档与变更记录一致」从人工纪律变成 CI 断言。第 21 章讲 spec 与 CI 时覆盖的是运行时行为测试,这里补的是文档结构测试,两者共用同一套 lint 入口。
24.8.5 45.0 段落:三类变更与 backport
最新的 45.0 段(:17-258)能同时看到五类里的四类:
:19Removed:沙箱 preload 脚本不再有 Node 模块 shim 与Buffer/setImmediate/clearImmediate全局;require现在只加载electron系模块,process与global仍提供。文档还给了替代表(EventTarget、queueMicrotask、URL、Uint8Array)。这条对应第 12 章讲的沙箱 preload 环境。:44Behavior Changed:ipcRenderer、webFrame与 preload 的process改用 Electron 原生实现的EventEmitter,实例 API 不变,但只有require('events')才能拿到的静态辅助函数不再提供。:57-65、:67-75两条Behavior Changed:子帧创建的 Worker 与 preload 脚本的作用域收紧,均依赖nodeIntegrationInSubFrames;两条都写明「This change was also backported to Electron 44.3.0, 43.7.0 and 42.11.3」。:174Default Changed、:237Deprecated(safeStorage 三个同步方法,见 24.7.5)。
backport 那两行是 24.2.4「release branches are never merged back to main」的落地证据:一个行为修复要显式落到 44、43、42 三条旧线,各发一个 patch 版本。排查「同一个应用在不同 Electron minor 上行为不同」时,先查条目里有没有 backport 列表,比逐版本 diff 快得多。
24.8.6 一次破坏性变更的完整生命周期
把 24.7 与 24.8 合成六步,这是本章最可直接复用的一张流程:
| 步 | 落点 | 机器校验 |
|---|---|---|
| 1 | PR 标题带 BREAKING CHANGE:(或 feat: / fix:)决定 SemVer bump | electron-versioning.md:240-244、squash merge |
| 2 | docs/breaking-changes.md 对应 major 段新增条目,按五类标注 | 44 个版本段的结构 |
| 3 | 若属 Deprecated,同版本在 deprecate.ts 挂 warnOnce | spec/deprecate.spec.ts |
| 4 | docs/api/*.md 加 _Deprecated_ 与 YAML history 锚点 | lint:api-history 的 --check-placement |
| 5 | 需要时 backport 到旧线,在条目里列出版本号 | 人工,无自动校验 |
| 6 | 目标 major 真正移除,条目改为 Removed(safeStorage 明确写了 Electron 46,见 24.7.5) | 同上 |
第 2、4 步之间的锚点是唯一强约束;第 5 步没有自动校验,靠 PR 审查。这也解释了为什么 breaking-changes.md 里有些条目带 backport 列表、有些没有——本树没有机制保证 backport 一定被记录,读者不能把「没写 backport」等同于「没有 backport」。
24.8.7 与第 20 章 fuse 的分工
最后把两套兼容机制并列,避免混淆:
| 弃用 / 破坏性变更 | fuse | |
|---|---|---|
| 决策时点 | 源码期(Electron 发版时) | 打包期(应用开发者翻转二进制位) |
| 作用对象 | JS / C++ API 的形状 | 二进制里固定的能力开关 |
| 谁承担迁移 | 应用开发者改代码 | 应用开发者改发布流程 |
| 可撤销 | 兼容期内可继续用旧 API | 部分不可逆(cookieEncryption) |
| 本章位置 | 24.7、24.8 | 24.9 |
两者都是「不立刻切断旧行为」的手段,但一个靠告警与文档争取时间,一个靠二进制位在发布时做一次性选择。第 20 章讲过 fuse 的九个开关,本章 24.9 要补的是这套开关自己如何跨版本不失效——那是比「开关做什么」更靠近演进主题的一层。
24.9 Fuses 的向后兼容契约
第 20 章讲过 fuse 的九个开关分别做什么、以及 wire 在二进制里长什么样。本节补的是更靠近演进主题的一层:这套二进制位凭什么能从 v1 一直用到下一个 Chromium 大版本而不失效。答案是三条约束——构建期生成、顺序即索引、废弃位永不回收。
24.9.1 fuses.h / fuses.cc 不在源码树里
全树 Glob **/fuses.{h,cc} 零命中。它们是 GN action 的产物:
BUILD.gn:458-469
action("electron_fuses") {
script = "build/fuses/build.py"
inputs = [ "build/fuses/fuses.json5" ]
outputs = [
"$target_gen_dir/fuses.h",
"$target_gen_dir/fuses.cc",
]
args = rebase_path(outputs)
}
依赖点分布在 BUILD.gn:500(electron_lib)、:898(sources += get_target_outputs(":electron_fuses"))、:1590。C++ 侧一律 #include "electron/fuses.h",例如 electron_main_delegate.cc:34、node_main.cc:24、electron_renderer_client.cc:11——include 路径指向生成目录而非 shell/common/。
这个设计本身就是一个演进决定:fuse 列表是数据,不是代码。新增开关只需改 fuses.json5:2-11 一行,getter 由脚本生成;若把手写头文件放在 shell/common/,每次新增都要同步改两个文件并核对索引,正是最容易出错的地方。第 20 章说过 kFuseWire 是 const volatile char[],这里补上它为什么必须是 volatile 的生成侧理由:脚本把它写成一个静态数组,编译器不得把对它的读取优化成常量,否则打包期翻转的位就失效了。
24.9.2 九个开关与 _version: 1
fuses.json5:2-9 全文 14 行,是 wire 顺序的唯一权威:
{
"_comment": "Modifying the fuse schema in any breaking way should result in the _version prop being incremented. NEVER remove a fuse or change its meaning, instead mark it as removed with 'r'",
"_schema": "0 == off, 1 == on, r == removed fuse",
"_version": 1,
"run_as_node": "1",
"cookie_encryption": "0",
"node_options": "1",
"node_cli_inspect": "1",
"embedded_asar_integrity_validation": "0",
"only_load_app_from_asar": "0",
"load_browser_process_specific_v8_snapshot": "0",
"grant_file_protocol_extra_privileges": "1",
"wasm_trap_handlers": "1"
}
| # | 键 | 默认 | getter(由键名生成) | 文档位置 |
|---|---|---|---|---|
| 1 | run_as_node | 1 | IsRunAsNodeEnabled | fuses.md:26-36 |
| 2 | cookie_encryption | 0 | IsCookieEncryptionEnabled | :38-54 |
| 3 | node_options | 1 | IsNodeOptionsEnabled | :56-66 |
| 4 | node_cli_inspect | 1 | IsNodeCliInspectEnabled | :68-76 |
| 5 | embedded_asar_integrity_validation | 0 | IsEmbeddedAsarIntegrityValidationEnabled | :78-89 |
| 6 | only_load_app_from_asar | 0 | IsOnlyLoadAppFromAsarEnabled | :91-105 |
| 7 | load_browser_process_specific_v8_snapshot | 0 | IsLoadBrowserProcessSpecificV8SnapshotEnabled | :107-129 |
| 8 | grant_file_protocol_extra_privileges | 1 | IsGrantFileProtocolExtraPrivilegesEnabled | :131-149 |
| 9 | wasm_trap_handlers | 1 | IsWasmTrapHandlersEnabled | :151-178 |
getter 名不是手写的,build.py:71 一行生成:name = ''.join(word.title() for word in fuse.split('_'))。键名即公共 C++ 接口名,所以改键名会静默改变所有调用点的符号——这与 24.9.3 的索引约束合起来,构成「键名与位序都不可动」的双重冻结。
_version: 1 至今没有递增过,说明九个开关的语义自引入以来没被破坏性修改。build.py:59-60 还限制它不能超过一个字节:if fuse_version >= pow(2, 8): raise Exception("Fuse version can not exceed one byte in size")。同理 fuse_wire_length 也是单字节(:103 用 c_hex(len(fuses)) 写入),即最多 255 个 fuse——这是一个由 wire 格式决定的硬上限,而非策略选择。
24.9.3 索引算法:为什么只能追加到末尾
build.py:44,51-88 是整章最值得逐行推演的一段:
# :44(模板里的一行)
const volatile char kFuseWire[] = { /* sentinel */ {sentinel}, /* fuse_version */ {fuse_version}, /* fuse_wire_length */ {fuse_wire_length}, /* fuse_wire */ {initial_config}};
# :51-71
with open(os.path.join(dir_path, "fuses.json5"), 'r') as f:
fuse_defaults = json.loads(''.join(line for line in f.readlines() if not line.strip()[0] == "/"), object_pairs_hook=OrderedDict)
fuse_version = fuse_defaults['_version']
del fuse_defaults['_version']
del fuse_defaults['_schema']
del fuse_defaults['_comment']
fuses = fuse_defaults.keys()
initial_config = ""
index = len(SENTINEL) + 1
for fuse in fuses:
index += 1
initial_config += fuse_defaults[fuse]
name = ''.join(word.title() for word in fuse.split('_'))
getters_h += "FUSE_EXPORT bool Is{name}Enabled();\n".replace("{name}", name)
getters_cc += """
...
return kFuseWire[{index}] == '1';
""".replace("{index}", str(index))
关键在 object_pairs_hook=OrderedDict(:52):JSON5 的书写顺序被保留,:62 直接拿 keys() 当序列,:67-69 用递增的 index 为每个 getter 生成编译期固定的下标。哨兵 SENTINEL = "dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX"(:10)长 32 字节,于是 index 初值 33,循环内先加 1,第一个 fuse 落在 kFuseWire[34]——正好是 32 字节哨兵 + 1 字节 version + 1 字节 length 之后的第一位。这与第 20 章的 wire 图、第 23 章的 kFuseWire[34] == '1' 判据三者一致。
由此推出一条不能违反的规则:若在中间插入新 fuse,其后所有 getter 的下标整体后移。一个已经打包、第 3 位被翻转成 1 的旧二进制,用新生成的 fuses.cc 重新编译时,IsNodeOptionsEnabled() 会去读原本属于 node_cli_inspect 的位。更糟的是这种错配不会报错——它只是安静地返回了另一个开关的值。所以 fuses.json5:2 的 NEVER remove a fuse or change its meaning 不是风格建议,是索引算法的数学后果。
删除同样不行,会平移后续下标。于是第 3 行 _schema 给了第三种状态 'r':
<!-- docs/tutorial/fuses.md:224-240 -->
| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |
* `sentinel_bytes` is always this exact string: `dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX`
* `fuse_version` is a single byte whose unsigned integer value represents the version of the fuse schema
* `fuse_wire_length` is a single byte whose unsigned integer value represents the number of fuses ...
* `fuse_wire` is a sequence of N bytes, each byte represents a single fuse and its state.
* "0" (0x30) indicates the fuse is disabled
* "1" (0x31) indicates the fuse is enabled
* "r" (0x72) indicates the fuse has been removed and changing the byte to either 1 or 0 will have no effect.
'r' 是墓碑位:它永久占住那个下标,使后续位序不动,同时让翻转工具无法再改它。目前九个键里没有一个是 'r',也就是说这个机制是为将来预留的、尚未启用过的兼容手段。24.0 说的「展望只能写可验证的当下」,这就是最典型的一例:能验证的是机制已存在,不能验证的是「将来会废弃哪个开关」。
24.9.4 兼容契约的另一半在仓库外
必须如实记下边界:fuse_wire、kFuseWire、SENTINEL、fuse_wire_length 这些词在本树只命中三处——BUILD.gn、build.py:74-80、fuses.md:227-233。「按版本找到 sentinel、读出 length、判定未知位、翻转指定位」的运行时代码不在 Electron 仓库里,它属于外部 npm 包 @electron/fuses(fuses.md:184-205 给出 flipFuses(require('electron'), { version: FuseVersion.V1, [FuseV1Options.RunAsNode]: false }) 与 npx @electron/fuses read --app ... 的用法)。
于是 wire 兼容契约由两侧共同承担:仓库侧负责按固定顺序生成 getter 并把 version/length 写进二进制,外部工具负责读取这两个字节、据此定位 wire、只改已知位。任何一侧破坏顺序都会静默错配。这也解释了一个排查经验:升级 @electron/fuses 后翻转结果异常,先比对该工具支持的 FuseVersion 与 fuses.json5:2-4 的 _version,再怀疑二进制。
24.9.5 DCHECK 下的运行时覆盖
getters_cc 模板里还藏了一个调试通道(build.py:73-86):
bool Is{name}Enabled() {
#if DCHECK_IS_ON()
// RunAsNode is checked so early that base::CommandLine isn't yet
// initialized, so guard here to avoid a CHECK.
if (base::CommandLine::InitializedForCurrentProcess()) {
base::CommandLine* command_line = base::CommandLine::ForCurrentProcess();
if (command_line->HasSwitch("{switch_name}")) {
std::string switch_value = command_line->GetSwitchValueASCII("{switch_name}");
return switch_value == "1";
}
}
#endif
return kFuseWire[{index}] == '1';
}
{switch_name} 由 f"set-fuse-{fuse.lower()}" 生成,即每个 fuse 都有一个 --set-fuse-run_as_node=1 形式的开关,只在 DCHECK 构建里生效。注释点明 RunAsNode 检查得太早、命令行对象可能尚未初始化,所以要先判 InitializedForCurrentProcess() 避免 CHECK。这是调试版专用的旁路,正式包里 fuse 值仍只来自二进制位。第 20 章讲 fuse 时没提这条,因为它不影响生产行为,但在本地验证「某个 fuse 翻转后会怎样」时,比重新打包快得多。
24.9.6 读取点清单与一次新增动作
C++ 侧读取点(grep Is[A-Za-z]+Enabled):electron_library_main.mm:92、electron_main_linux.cc:55、electron_main_mac.cc:73、electron_main_win.cc:154 的 IsRunAsNodeEnabled;node_main.cc:130 的 IsNodeOptionsEnabled;electron_main_delegate.cc:128,401;electron_renderer_client.cc:307 的 IsWasmTrapHandlersEnabled;renderer_client_base.cc:327;node_service.cc:148;app_package.cc:92;asar_util.cc:54。第 22 章讲 asar integrity 时用到的正是最后这一处。
新增一个 fuse 的完整动作由此确定,五步缺一不可:
- 在
fuses.json5末尾追加键与默认值,不动任何已有行; - 若语义发生破坏性变化,先递增
_version(当前 1); - 在 C++ 里
#include "electron/fuses.h"并调用脚本生成的Is<Name>Enabled(); - 在
fuses.md增条目,说明是否单向(cookie_encryption在:47-49明确是 one-way transition,禁用后 cookie 存储会损坏); - 同步外部
@electron/fuses的FuseV1Options常量表。
第 1 步是 24.9.3 推出来的硬约束,第 5 步是 24.9.4 的仓库外依赖。把这两步写进检查单,比记住九个开关的名字更有长期价值。顺带对比 24.1.5 的 electron_vendor_version:那是编译期给 process.versions 加一个键,fuse 是打包期改二进制一个字节;两者都是「留一个下游可改的口子,而不让下游改源码」,只是作用层不同。
24.10 Mojom 接口扩展:条件编译代替版本协商
第 14 章把一次 ipcRenderer.invoke() 拆到 mojom 消息定义,第 23 章又遇到 RendererStartupData 通过 CreateNewWindowReply 预推。本节问的是:这些跨进程接口加方法时,怎么保证两端版本对得上。45.2.3 的答案不是 Mojo 的版本注解,而是 buildflag 条件编译。
24.10.1 全树只有五个 .mojom
| 文件 | 作用 |
|---|---|
api.mojom | Electron 自定义的 renderer / frame / IPC 接口 |
app_shim.mojom | macOS app shim 通信 |
plugin.mojom | 插件相关 |
web_contents_utility.mojom | WebContents 与 utility 进程 |
node_service.mojom | Node service(utility process 后端) |
两个阴性结果要说清:shell/common/api/electron_api.mojom 与 shell/browser/api/**/*.mojom 均不存在;Electron 的 mojom 定义集中在 shell/common/ 与 shell/services/node/public/mojom/,shell/browser/api/electron_api_* 是消费方而非定义方。这个布局和 24.9.1 的 fuse 生成一样,是「定义与实现分离」的又一处体现:接口定义放在 common,浏览器侧与渲染器侧各自实现。
24.10.2 api.mojom 的五个接口与顺序保证
api.mojom 全文 129 行,含 4 个结构体与 5 个接口:
| 接口 | 行号 | 方法 |
|---|---|---|
ElectronFrame | :52-78 | SetStartupData、ExecuteJavaScript、InsertCSS、RemoveInsertedCSS、InsertText、SetVisualZoomLevelLimits、ReceiveSharedTexture |
ElectronRenderer | :80-89 | Message、ReceivePostMessage、TakeHeapSnapshot |
ElectronAutofillAgent | :91-93 | AcceptDataListSuggestion |
ElectronAutofillDriver | :95-98 | ShowAutofillPopup、HideAutofillPopup |
ElectronApiIPC | :100-128 | Message、Invoke、ReceivePostMessage、[Sync] MessageSync、MessageHost |
第 24.0.2 的第三条纠偏在此落地:interface ElectronBrowser 在 shell/ 下零命中,全仓命中都在本书自己的稿子里(指 C++ 类 ElectronBrowserClient 等)。它已被拆成上表这几个按职责划分的接口。
最值得重读的是 :47-51 那段注释,它把第 23 章的「预推顺序保证」写在了接口定义里:
api.mojom:52
// Per-frame interface associated with content.mojom.Frame, so its messages and
// replies are ordered with navigation and the frame's other host messages:
// SetStartupData() arrives before the CommitNavigation that follows it, and a
// reply is seen after anything the frame told its host while handling the
// request.
interface ElectronFrame {
第 23 章说 RendererStartupData 的顺序保证不是 ack,而是 AssociatedRemote 与 content.mojom.Frame 共通道;这里给出了定义侧的原文:因为接口与 Frame 关联,消息与导航、与帧的其它 host 消息共享同一顺序。这是「演进」里少见的靠通道语义而非协议握手解决兼容的例子——不需要在消息里加版本号,只要绑定关系不变,先后关系就由 Mojo 保证。
24.10.3 不用 MinVersion / ordinal,用 [EnableIf]
在 shell/**/*.mojom 里检索 MinVersion 与 ordinal 均无命中;[EnableIf=...] 命中一处,[Sync] 命中 5 处(api.mojom:119、web_contents_utility.mojom:29,32,36、plugin.mojom:17)。唯一那处条件编译是 node_service.mojom:41-51:
[ServiceSandbox=sandbox.mojom.Sandbox.kNoSandbox]
interface NodeService {
Initialize(NodeServiceParams params,
pending_remote<NodeServiceClient> client_remote);
UpdateURLLoaderFactory(URLLoaderFactoryParams params);
[EnableIf=enable_prompt_api]
BindAIManager(BindAIManagerParams params,
pending_receiver<blink.mojom.AIManager> ai_manager);
};
BindAIManager 整个方法按 enable_prompt_api 这个 feature 开关存在或消失。也就是说,新增跨进程方法的兼容策略是「让两端在同一份构建配置下一起编译,而不是让运行时协商版本」。这与 Electron 的分发模型相符:主进程、渲染器、utility 进程都来自同一个二进制,不存在「新版渲染器配旧版主进程」的混合部署,因此 Mojo 的版本协商机制在这里没有用武之地。
这个判断有边界,不能外推:本结论只针对 Electron 自定义的这 5 个 .mojom;Chromium 自带的大量 mojom 仍使用自己的版本注解体系,本树不是它们的证据源。
24.10.4 ENABLE_PROMPT_API 的七处完整链
[EnableIf=enable_prompt_api] 不是孤立的注解,它对应一条贯穿 GN、mojom、C++ 的条件编译链:
| 层 | 文件:行号 | 内容 |
|---|---|---|
| 默认值 | buildflags.gni:15 | enable_prompt_api = true |
| 宏生成 | buildflags/BUILD.gn:15 | "ENABLE_PROMPT_API=$enable_prompt_api" |
| mojom 特性表 | shell/services/node/public/mojom/BUILD.gn:17-18 | enabled_features = [ "enable_prompt_api" ] |
| 接口注解 | node_service.mojom:48 | [EnableIf=enable_prompt_api] |
| 源文件清单 | BUILD.gn:677-686 | 条件加入 6 个 AI 相关 .cc/.h |
| C++ 条件编译 | node_service.h:25 | #if BUILDFLAG(ENABLE_PROMPT_API) |
| 浏览器侧实现 | electron_api_utility_process.cc:571-583 | UtilityProcessWrapper::BindAIManager |
七处必须同真同假,否则要么 mojom 生成了方法但 C++ 没实现,要么反过来。这条链正是 24.6.5 说的「有明确分叉开关」的实例,也是 24.12 要讲的 feature flag 契约的样本:electron-versioning.md:230-234 要求 feature flag「completely segments new and old code paths」,并且「eventually removed after the feature is released」。ENABLE_PROMPT_API 目前仍四处可见,说明它还处在「已实现但尚未摘掉开关」的阶段。
24.10.5 [Sync] 五处与第 14 章的代价
api.mojom:119-123 的 [Sync] MessageSync 是同步 IPC 的定义:
// Emits an event on |channel| from the ipcMain JavaScript object in the main
// process, and waits synchronously for a response.
[Sync]
MessageSync(
bool internal,
string channel,
SerializedValue arguments) => (SerializedValue result);
第 14 章讲过同步 IPC 会阻塞渲染器,第 23 章讲过 preload 旧方案正是因为同步 IPC 才被 RendererStartupData 预推取代。把 5 处 [Sync] 列出来看,可以判断这套机制在 45.2.3 的收窄程度:web_contents_utility.mojom 三处是 utility 进程侧的同步调用(不在渲染关键路径),plugin.mojom:17 是插件,api.mojom:119 是显式暴露给应用的 ipcRenderer.sendSync。它们都没有被删,只是不再被内部启动路径使用——这是演进里常见的一种保守:公共 API 保持兼容,内部实现绕开它。
24.10.6 两套兼容契约对照
把 24.9 与 24.10 并排,能看出 Electron 对「两端版本对齐」的两种解法:
| fuse wire | mojom 接口 | |
|---|---|---|
| 对齐对象 | 二进制 ↔ 外部翻转工具 | 主进程 ↔ 渲染器 / utility 进程 |
| 是否可能版本错配 | 会(工具版本可能落后) | 几乎不会(同一二进制内) |
| 兼容手段 | 固定位序 + 'r' 墓碑 + version/length 字节 | [EnableIf] 条件编译 + 共通道顺序语义 |
| 破坏时的表现 | 静默读到别的开关值 | 编译期直接失败 |
| 演进成本 | 只能追加,不能改 | 加方法但须同步七处开关链 |
分水岭在于是否存在混合部署。fuse 面对的是「旧工具改新二进制」,只能靠数据格式的自我描述(哨兵、version、length)防御;mojom 面对的是同一次构建产出的多个进程,交给编译器即可。第 23 章讲 RendererStartupData 的 AssociatedRemote 共通道顺序,属于后者的进一步简化——连握手都省了。
这也给 24.15 的升级检查单提供一条判据:遇到跨版本行为异常,先判断错配发生在「工具↔二进制」还是「进程↔进程」。前者的排查入口是 fuses.json5 与 @electron/fuses 版本,后者是 buildflags.gni 与 mojom 的 enabled_features。两者几乎不会同时出问题,混在一起查会浪费大量时间。
24.11 一个新 API 要改多少处
24.9、24.10 讲的是「已有机制怎么演进」,本节反过来问:加一个新 API 时,Electron 要在多少层同步落笔。拿 utilityProcess 做样本,它在第 16 章讲四类执行环境时出场过、第 10/11 章讲进程模型时也出现过,且证据链最全——同时覆盖 C++、mojom、JS、文档、测试五层。再拿 webUtils.getPathForFile 做对照,说明并非所有新 API 都需要跨进程接口。
24.11.1 utilityProcess 的五层
| 层 | 文件:行号 | 关键内容 |
|---|---|---|
| C++ 实现 | electron_api_utility_process.cc:226-230 | BindNewPipeAndPassReceiver() + content::ServiceProcessHost::Launch() |
| C++ 实现 | 同文件 :283、:369,378、:636-637、:728 | Initialize()、IsService<NodeService>()、NodeServiceParams::New()、导出绑定 |
| mojom 定义 | node_service.mojom:41-51 | NodeService 接口 |
| GN | shell/services/node/public/mojom/BUILD.gn:8-20 | mojom("mojom") 目标与 enabled_features |
| 服务实现 | node_service.cc:15,144-148 | utility 进程侧 |
| JS 包装 | utility-process.ts:1-13 | process._linkedBinding('electron_browser_utility_process') |
| 文档 | utility-process.md:1-11 | 模块说明与 fork() 签名 |
| 类型 | electron.d.ts | 由 24.11.4 的链路生成,不在树里 |
| 测试 | spec/api-utility-process.spec.ts:25-29,79-80 | 构造异常、生命周期事件 |
C++ 层最关键的是启动那几行:
electron_api_utility_process.cc:226-230
mojo::PendingReceiver<node::mojom::NodeService> receiver =
node_service_remote_.BindNewPipeAndPassReceiver();
content::ServiceProcessHost::Launch(
std::move(receiver),
utility-process.md:3-5 用一句话点明了它为何需要 mojom:「It provides the equivalent of child_process.fork API but instead uses Services API from Chromium to launch the child process.」——用 Chromium 的 Service API 起子进程,就必须定义 Mojo service 接口。这正是第 16 章讲「utility process 与 child_process.fork 的区别」时那层架构差异的代码落点。
JS 层只有一行桥接:utility-process.ts:5 的 _linkedBinding 拿到 C++ 侧 :728 Initialize() 导出的 _fork。之后所有 EventEmitter 语义、Duplex 流、MessagePort 转发都在 TS 里实现。这种「C++ 只负责起进程和 Mojo 管道,JS 负责 API 形状」的分工,在第 7 章讲 gin 绑定、第 8 章讲模块加载时都出现过,是 Electron 新增 API 的固定套路。
24.11.2 五层之间的两个断点
第一处在 mojom 与 C++ 实现之间:node_service.mojom:48 的 [EnableIf=enable_prompt_api] 让 BindAIManager 成为条件方法,而 electron_api_utility_process.cc:571-583 的 UtilityProcessWrapper::BindAIManager 实现必须同条件编译(24.10.4 七处链的最后一环)。新增一个条件方法要同时改四处:mojom 定义、mojom 的 GN enabled_features、C++ 源文件清单、C++ 实现里的 BUILDFLAG 卫语句。漏一处就是编译错误——比 fuse 位序错配友好得多,因为它不会静默。
第二处在文档与类型之间:electron.d.ts 在源码树里找不到(Glob **/electron.d.ts 零命中),它是生成产物。所以「加了 API 但忘了改类型定义」在这套体系里不会发生——类型定义从文档生成。下一节展开这条链。
24.11.3 对照:webUtils.getPathForFile 没有 mojom
同样五层,但形状完全不同:
| 层 | utilityProcess | webUtils.getPathForFile |
|---|---|---|
| C++ | electron_api_utility_process.cc | electron_api_web_utils.cc:18,35 |
| mojom | node_service.mojom:41-51 | 无 |
| JS 桥 | utility-process.ts:5 | web-utils.ts:3:export const getPathForFile = binding.getPathForFile; |
| 文档 | utility-process.md | web-utils.md:17,44 |
| 测试 | spec/api-utility-process.spec.ts | spec/api-web-utils.spec.ts:14,27,55 |
差别的原因是功能是否需要跨进程:getPathForFile 把渲染器里的 File 对象转成本地路径,全部工作在渲染进程内完成,直接用 _linkedBinding 暴露一个同步函数即可;utilityProcess.fork() 要起一个新进程并与之通信,必须有 Mojo 接口。第 14 章把 IPC 分成「同步本地绑定」「异步跨进程消息」两类,这里就是它们在 API 落地层面的镜像。
webUtils 的引入本身也是一次演进:docs/breaking-changes.md:1210 写明「beginning in Electron 32.0 it has been removed in favor of the webUtils.getPathForFile method」——被移除的是 File.path,理由与第 15 章讲的上下文隔离安全边界直接相关。所以这个 API 同时出现在 24.8 的破坏性变更记录与 24.11 的新 API 链路里:一次 Removed 与一次新增,在文档里是同一条目的两面。
24.11.4 文档到类型的生成链
package.json:10,14 声明两个开发依赖:"@electron/docs-parser": "^3.0.2"、"@electron/typescript-definitions": "^9.2.0";:67-69 是三个串联脚本:
"create-api-json": "node script/create-api-json.mjs",
"create-typescript-definitions": "npm run create-api-json && electron-typescript-definitions --api=electron-api.json && node spec/ts-smoke/runner.js",
"gn-typescript-definitions": "npm run create-typescript-definitions && node script/cp.mjs electron.d.ts",
script/create-api-json.mjs:1-20 全文只有一件事:
import { parseDocs } from '@electron/docs-parser';
parseDocs({
baseDirectory: resolve(import.meta.dirname, '..'),
packageMode: 'single',
useReadme: false,
moduleVersion: getElectronVersion()
})
.then((api) => {
return promises.writeFile(resolve(import.meta.dirname, '..', 'electron-api.json'), JSON.stringify(api, null, 2));
})
链路于是闭合:docs/api/*.md →(parseDocs)→ electron-api.json →(electron-typescript-definitions)→ electron.d.ts → runner.js 冒烟测试。BUILD.gn:199-214 把这一步挂进构建图:
# electron.d.ts is generated into the repo root (//electron/electron.d.ts) — a
# single shared path consumed via the /// <reference> in
# typings/internal-electron.d.ts — plus a per-toolchain gen-dir copy.
if (current_toolchain == default_toolchain) {
npm_action("build_electron_definitions") {
script = "gn-typescript-definitions"
args = [ rebase_path("$target_gen_dir/tsc/typings/electron.d.ts") ]
inputs = auto_filenames.api_docs + [ "yarn.lock" ]
outputs = [ "$target_gen_dir/tsc/typings/electron.d.ts" ]
}
inputs = auto_filenames.api_docs 说明文档是构建输入:改一篇 docs/api/*.md 会触发类型定义重生成。这与第 3 章讲的 filenames.auto.gni 自动生成机制同源,也解释了 24.8.4 为什么把 lint:docs 串在 CI 里——文档错了不只是文档错,会直接产出错的类型定义。release-assets.json:38-39 把 electron-api.json 与 electron.d.ts 列为发布产物,script/spec-runner.js:111-112 还有「Generating electron.d.ts as it is missing」的兜底。
一个容易踩的点:internal-electron.d.ts:1 用 /// <reference path="../electron.d.ts" /> 指向仓库根的生成文件,而 BUILD.gn:199-201 说它同时会往每个 toolchain 的 gen-dir 拷一份。所以本地直接跑 tsc 报「找不到 electron.d.ts」时,正确做法是先跑 npm run create-typescript-definitions,而不是手写声明文件。
24.11.5 docs/api/structures/ 的角色
docs/api/structures/ 放共享结构体文档:activation-arguments.md、base-window-options.md:46-58、browser-window-options.md、certificate.md、web-preferences.md:93-103 等。app.md:36,347 用相对链接引用它们([NotificationResponse](structures/notification-response.md)、[Certificate](structures/certificate.md))。两者同属 @electron/docs-parser 的输入(BUILD.gn:211),都会被解析进 electron-api.json;结构体文档里同样带 _Experimental_ / _Deprecated_ 标注(如 web-preferences.md:11),因此 24.8.3 的统计把 structures/ 计入了。
docs/api-history.schema.json:2 约束 YAML history 块,package.json:65 的 lint:api-history 执行校验。文档、类型、变更记录三者共用同一份结构化输入,这是 24.8 说「破坏性变更被做成机器可校验数据」的底层原因。
24.11.6 一条判据
把 24.11 压成一句可复用的判断:看到一个 45.2.3 里刚出现的新 API,先问它是否跨进程。跨进程则去 shell/services/node/public/mojom/ 或 shell/common/api/ 找接口定义,并核对 [EnableIf] 的开关链;不跨进程则去 lib/renderer/api/ 或 lib/browser/api/ 找 _linkedBinding,接口由 C++ 直接导出。两种形态的文档与测试层是一样的,差别只在中间两层。第 16 章列的四类「非主非渲染」执行环境,用这条判据能快速定位每类 API 的实现位置。
24.12 实验性、feature flag 与开发者待办的边界
「展望」最容易注水的地方,是把源码里任何看起来尚未定型的东西都算成「未来方向」。本节用四个层次把边界划清:编译期开关、feature flag 契约、文档里的公开实验性标记、以及纯工程待办注释。
24.12.1 四个 buildflag
buildflags.gni:5-27 全文 27 行,核心是 declare_args() 里的四个布尔:
declare_args() {
enable_pdf_viewer = true
# Enable Chrome extensions support.
enable_electron_extensions = true
# Enable Spellchecker support
enable_builtin_spellchecker = true
# Enable Prompt API support.
enable_prompt_api = true
# The version of Electron.
# Packagers and vendor builders should set this in gn args to avoid running
# the script that reads git tag.
override_electron_version = ""
# Define an extra item that will show in process.versions, the value must
# be in the format of "key:value".
# Packagers and vendor builders can set this in gn args to attach extra info
# about the build in the binary.
electron_vendor_version = ""
}
buildflags/BUILD.gn:8-28 把它们转成宏:
buildflag_header("buildflags") {
header = "buildflags.h"
flags = [
"ENABLE_PDF_VIEWER=$enable_pdf_viewer",
"ENABLE_ELECTRON_EXTENSIONS=$enable_electron_extensions",
"ENABLE_BUILTIN_SPELLCHECKER=$enable_builtin_spellchecker",
"ENABLE_PROMPT_API=$enable_prompt_api",
]
...
}
外加 :18-27 按 electron_vendor_version 条件生成 HAS_VENDOR_VERSION / VENDOR_VERSION_NAME / VENDOR_VERSION_VALUE(24.1.5 已讲)。BUILDFLAG(ENABLE_*) 的消费点:node_service.h:25,27,79,83,86,103、browser_exposed_renderer_interfaces.cc:15,20,34、electron_api_web_frame.cc:73,125,369,878、electron_content_utility_client.cc:29-151。
四个开关默认全为 true,说明它们是分发裁剪用的编译期选项,不是「默认关闭的实验功能」。定制构建可以关掉 PDF viewer、扩展、拼写检查或 Prompt API 来减小体积——第 22 章讲体积优化时提到的「按 buildflag 裁剪」就是这里。而 ENABLE_PROMPT_API 特殊在于它同时被 24.10.3 的 [EnableIf] 使用,于是「裁剪」与「接口演进」合用了同一个开关。
24.12.2 feature flag 的契约
electron-versioning.md:228-234 定义了什么叫合格的 feature flag:
## Feature flags
Feature flags are a common practice in Chromium... a feature flag or **soft branch** must have the following properties:
* it is enabled/disabled either at runtime, or build-time; ...
* it completely segments new and old code paths; refactoring old code to support a new feature _violates_ the feature-flag contract
* feature flags are eventually removed after the feature is released
第二条最硬:不允许为了支持新功能而重构旧代码路径,新旧必须彻底分段。第三条给了退出条件——特性发布后开关要被摘掉。把这条放回 ENABLE_PROMPT_API:它目前仍出现在 24.10.4 的七处链里,按契约属于「尚未走完全程」的 flag。因此本章能说的「展望」是:这条开关链按官方契约应当在未来某个版本被移除,届时七处会一起收敛;但仓库里没有给出时间、也没有给出目标版本,不能写成「下个版本会摘掉」。
顺带一提,第 24.2.1 说 8 周一个 major,而 feature flag 要求「发布后移除」,两者合起来解释了为什么 45.2.3 里同时存在多个年代的残留开关——移除本身要占一次 major 的 breaking change 预算。
24.12.3 66 处 _Experimental_,22 个文件
真正面向应用开发者的实验性声明是文档里的行内标记。docs/api/experimental-*.md 这类文件不存在;实验性用 _Experimental_ 表达,全树统计 66 处 / 22 个文件。分布:
| 文件 | 处数 | 文件 | 处数 |
|---|---|---|---|
language-model-utility.md | 9 | service-worker-main.md | 7 |
app-shim-host.md | 15 | shared-texture.md | 4 |
protocol.md | 2 | service-workers.md | 3 |
session.md | 3 | app.md | 4 |
image-view.md | 2 | web-contents.md | 1 |
base-window.md | 1 | browser-window.md | 1 |
context-bridge.md | 1 | environment-variables.md | 1 |
local-ai-handler.md | 1 | utility-process.md | 1 |
web-frame-main.md | 1 | print-to-pdf-options.md | 2 |
base-window-options.md | 2 | web-preferences.md | 3 |
trace-config.md | 1 | trace-categories-and-options.md | 1 |
整模块级声明见 app-shim-host.md:6:「App shims are experimental. This API may change in a future Electron」。具体 API 标注散在 app.md:156,172,1273,1292(app-shim-connected / app.startAppShimServer 等)、browser-window.md:1410,1786(win.setShape、TouchBar)、web-preferences.md:11-14(nodeIntegrationInSubFrames)。
数量最多的三块——app-shim-host.md 15 处、language-model-utility.md 9 处、service-worker-main.md 7 处——恰好对应 24.12.1 的 ENABLE_PROMPT_API、第 16 章的 Service Worker 主线程 API、以及 macOS app shim。这说明当前前沿集中在 AI 相关能力与 Service Worker / app shim 宿主,而不是全书前 20 章覆盖的窗口、菜单、打印等成熟子系统。这是「展望」能给出的最实的一条方向判断,且每个数字都能 grep 复核。
24.12.4 三种「实验性」严格区分
| 类别 | 例子 | 是否构成对外承诺 |
|---|---|---|
| 源码里带作者名的待办注释 | electron_renderer_client.cc:127、crash_keys.cc:114、electron_api_crash_reporter.cc:228、BUILD.gn:691 | 否,纯工程待办 |
| 底层开关 | node_bindings.cc:434-436,447,471,685 的 --experimental-network-inspection 等;options_switches.h:169 的 experimentalFeatures;command-line-switches.md:318,322,364,368,381,400 | 否,Node/V8 或 WebPreferences 开关 |
文档里的 _Experimental_ | 24.12.3 的 66 处 | 是,面向开发者的 API 变更风险声明 |
第一类的规模:shell/ 下带待办标记的注释约 90 个文件命中,全树检索带固定团队名的待办标记零命中,实际形态是带具体作者名的注释(如 electron_browser_main_parts_mac.mm:74 的「Remove when...」)。它们是工程排期信息,不出现在任何 API 文档里,因此不能当作路线图。把这类注释写成「Electron 未来会做 X」是典型的过度解读。
第二类的 --experimental-* 来自 Node/V8 命令行,由 node_bindings.cc 在启动参数里追加;experimentalFeatures 是 WebPreferences 的布尔(web_contents_preferences.h:52、.cc:103,128,164,417),security_warnings.cc:225-232 甚至把它列为第 8 条安全警告「Do not enable experimental features」。它们是能力开关,不是版本承诺。
只有第三类是「API 可能变」的公开声明,且受 24.8.4 的 lint 体系约束。这也是本章筛选「正在演进」素材时只认第三类的原因。
24.12.5 一条边界:实验性不等于将稳定
app-shim-host.md:6 的措辞是「may change in a future Electron」,不是「will be stabilized」。全树检索 security.md:590 关于未来默认值的承诺(future / plan / will be / deprecat / remove 等关键词)也没有命中——24.13.4 会展开这条。因此本章对实验性 API 的措辞保持克制:能确认的是它们被明确标为可变、且集中在少数几个模块;不能确认的是它们何时稳定、是否会被移除、或是否会翻成默认值。
另一类要单独排除:breaking-changes.md:237-241 的移除预告给的是删除时间点,不是稳定性承诺(见 24.7.5)。这条边界与 24.6.5 的口径一致:看得到引入痕迹、分叉开关、未稳定信号,就说「正在演进」;看不到退出时间,就不写时间。把 66 处标记列成表是证据,把它们排成路线图就是注水。
24.13 安全默认值的历史:三次翻转与一次收紧
全书反复出现的一条演进线是安全默认值。本书第 12、15 章讲沙箱与隔离世界时提到过「现在默认如何」,本节把这些默认值是哪一代变的、变更后留下什么耦合、以及 45.0 又收紧了什么一次说完。
24.13.1 三个版本号
security.md 有三行「自某版本起成为默认」的记录:
| 行号 | 原文要点 | 对应默认值 |
|---|---|---|
:161 | This recommendation is the default behavior in Electron since 5.0.0. | nodeIntegration: false、contextIsolation 相关推荐 |
:226 | Context Isolation is the default behavior in Electron since 12.0.0. | contextIsolation: true |
:252 | This recommendation is the default behavior in Electron since 20.0.0. | 渲染进程 sandbox 默认开启 |
context-isolation.md:9 与 sandbox.md:15-20 各自复述了一次:
<!-- docs/tutorial/sandbox.md:15-20 -->
Starting from Electron 20, the sandbox is enabled for renderer processes without any
further configuration.
Sandboxing is tied to Node.js integration. _Enabling Node.js integration_ for a
renderer process by setting `nodeIntegration: true` _disables the sandbox_ for the
process.
三次翻转相隔 7 个和 8 个 major,且都能在 docs/breaking-changes.md 找到对应段落(20.0 在 :2098 附近、12.0 在 :2470、5.0 在 :3181)。按 24.8.1 的分类,它们全部属于 Default Changed——应用代码一行不改就可能出问题,但把旧值显式写出来就能恢复。这正是「历史包袱」最标准的形态:不是某个废弃 API 还在,而是「旧行为仍可显式指定」这件事被永久保留下来。
24.13.2 三项设置互相牵制
security.md:241,257-258 把耦合写得很明确:
`nodeIntegration: true` _also disables process sandboxing_ for that process.
_Disabling context isolation_ (see above) _also disables process sandboxing_,
regardless of the default, `sandbox: false` or globally enabled sandboxing!
即 nodeIntegration 与 contextIsolation 都会反向影响 sandbox,且第二句强调「无论默认值、sandbox: false、还是全局启用过 sandbox」都一样。sandbox.md:98,139 复述了同一关系,:84-91 说明单个窗口可用 sandbox: false 关闭,:117-126 给出 app.enableSandbox() 全局强制,:132-135 说明 --no-sandbox 连 utility process 一起关掉。
所以第 15 章讲「隔离世界不是自动安全」时,security.md:55 那句「Just enabling contextIsolation and using contextBridge does not automatically mean that everything you do is safe」不是免责声明,而是这套耦合的直接推论:三个开关必须一起读,单看任何一个都会得到错误的结论。第 24.8.1 把 Default Changed 单列一类,正是因为这类变更的破坏面无法通过「API 是否还叫这个名字」判断。
24.13.3 45.0 的收紧与 backport
最新一次收紧在 docs/breaking-changes.md:19-75:沙箱 preload 移除 Node 模块 shim 与 Buffer / setImmediate / clearImmediate 全局;ipcRenderer 等改用原生 EventEmitter;子帧创建的 Worker 与 preload 作用域跟随 nodeIntegrationInSubFrames。第 24.8.5 已列过细节,这里补两点演进意义:
其一,nodeIntegrationInSubFrames 本身仍是实验性选项(web-preferences.md:11-14 标注 Experimental option),默认 false(guest-view-manager.ts:40,62、guest-window-manager.ts:128 三处写死)。45.0 的两条行为变更却都以它为条件——一个实验性开关被用作行为收紧的判据,这在第 12 章讲子帧 preload 时值得留意。
其二,两条都写明 backport 到 44.3.0 / 43.7.0 / 42.11.3(24.2.4 讲过 release 分支不合回 main,backport 靠显式 cherry-pick)。这意味着同一份应用代码在 42.x 的不同 patch 版本上可能表现不同,排查时不能只看 major。
24.13.4 一条必须如实写下的负面结论
全树对 security.md:283-285 检索 future、plan、will be、deprecat、remove、always 等关键词,没有命中任何「将来会把某默认值翻转」的承诺。文档只记录已发生的三次默认值变更与当前建议。最接近「现状可讨论」的是 security.md:283-285:
By default, Electron will automatically approve all permission requests unless
the developer has manually configured a custom handler. While a solid default,
security-conscious developers might want to assume the very opposite.
「might want to assume the very opposite」是给开发者的建议,不是 Electron 的路线图。因此本章不写「下一步会默认拒绝所有权限请求」这类推断。演进信息在 45.2.3 的分布是:已发生的写在 breaking-changes.md 与三份教程里,正在发生的写在 _Experimental_ 与 buildflag 链里,尚未发生的没有留下文字。
24.13.5 sandbox 不是 fuse
一个容易混淆的点:fuses.json5 的九个键里没有 sandbox,fuses.md:149 全文 240 行也无 sandbox fuse;对 build/fuses 目录检索 sandbox 零命中。sandbox 走的是 WebPreferences + 默认值演进(sandbox.md:15-20,84-91),fuse 走的是打包期二进制位翻转(24.9),两者是完全独立的两套机制。
把这点放在 24.13 末尾,是为了给第 20 章「fuse 是运行时能力开关」补一条边界:并非所有安全能力都做成了 fuse。判据是「应用开发者是否需要在不改代码的前提下、对已构建二进制做一次性选择」——需要才做成 fuse(如 run_as_node),不需要(如窗口级 sandbox)就用 WebPreferences。24.9.6 的 electron_vendor_version 与这里构成同一族设计选择。
24.14 十五条纠偏:旧版认知在 45.2.3 的失效点
把本章取证得到的阴性结果集中成一张表。每条都给出可复核的判据,供升级排查时直接查。这些不是「版本差异趣闻」,而是按旧路径去 grep 会一无所获、进而误判为源码缺失的具体位置。
| # | 常见印象 | 45.2.3 实际 | 判据 |
|---|---|---|---|
| 1 | ELECTRON_ENABLE_DEPRECATION_WARNINGS 控制告警 | 不存在,用 Node 标准三开关 | 全仓零命中;deprecate.ts:16,32,40,42 |
| 2 | deprecate 用 Set 缓存已告警项 | 每个 API 一个闭包布尔 | deprecate.ts:13-21;spec/deprecate.spec.ts:170-183 |
| 3 | 弃用告警转发到 app 事件 | setHandler 无生产调用者 | 全仓 setHandler 仅命中 spec 与同名本地函数 |
| 4 | deprecate.removeIn() 指定移除版本 | 不存在 | deprecate.ts 全文 11 个导出 |
| 5 | shell/common/fuses.h / fuses.cc 是源码 | 构建期生成 | Glob **/fuses.{h,cc} 零命中;BUILD.gn:458-469 |
| 6 | fuse 列表可重排或删除旧位 | 只能末尾追加,废弃位标 'r' | fuses.json5:2-3;build.py:52,62,67-88 |
| 7 | 'r' 位已被用过 | 九个键里零个 'r' | fuses.json5:5-13 |
| 8 | 翻转 wire 的代码在 Electron 仓库 | 属于外部 @electron/fuses | 全树 fuse_wire 仅 3 处命中;fuses.md:184-205 |
| 9 | sandbox 是一个 fuse | 不是,走 WebPreferences | build/fuses 内 sandbox 零命中 |
| 10 | interface ElectronBrowser 在 mojom 里 | shell/ 下零命中,已拆为 5 个接口 | api.mojom:52,80,91,95,100 |
| 11 | mojom 用 MinVersion / ordinal 做版本协商 | 用 [EnableIf] + buildflag | MinVersion / ordinal 零命中;node_service.mojom:48 |
| 12 | electron.d.ts 在源码树里 | 生成产物 | Glob **/electron.d.ts 零命中;package.json:67-69 |
| 13 | package.json 的 version 是 45.2.3 | 固定 0.0.0-development | package.json:3;electron-versioning.md:252 |
| 14 | DEPS 里有独立 v8_version | 没有,V8 随 Chromium | DEPS:3-17;all.gn:11,17 |
| 15 | docs/api/experimental-*.md 是实验性文档 | 不存在,用行内 _Experimental_ | Glob 零命中;66 处 / 22 文件 |
另有四条「脚本名想当然」的纠偏,合并记在这里:lint_patches.py 不存在(实际 script/lint.js --patches);script/release/get-version.py / version_utils.py / release.py 不存在(实际 script/get-git-version.py、get-version.js、script/generate-version-json.js);CHROME_VERSION_STRING 的定义不在本树(来自 Chromium chrome/VERSION);npm 的 dist-tag 发布脚本不在本树(dist-tag / npm publish / publishConfig 全仓零命中)。
最后一条方法论上的纠偏:security.md 里没有「未来默认值」承诺,docs/breaking-changes.md 里也没有独立的 Planned Breaking API Changes 段落(只剩 :5 的免责声明)。在 45.2.3 里找不到整体路线图;唯一明确到目标 major 的是 safeStorage 同步方法的 Electron 46 移除预告(24.7.5),其余「未来」都被表达成了 buildflag、实验性标记与补丁正文里的退出条件。24.6.5 与 24.12.5 给出的筛选口径,就是替代路线图的读法。
24.15 全书收束:一条因果链,与一张升级检查单
第 23 章末尾说这一章要「看哪些是历史包袱、哪些正在被上游吸收,以及哪些会在下一个 Chromium 大版本里消失」。读到这里应当把最后半句修正:仓库里没有成体系的「哪些会在下个版本消失」清单,只有一个明确到版本的例外(safeStorage 同步方法 → Electron 46,24.7.5)。能给出的是三样东西——一份可复核的补丁时间档案(24.3、24.5)、一套判断「补丁何时可删」的规则(24.4.1)、以及一批正在发生且带分叉开关的主线(24.6、24.10、24.12)。预测被替换成了判据,这比一份会过期的路线图更有用。
24.15.1 24 章的因果链
| 部分 | 章 | 回答的问题 | 通向下一部分的因果 |
|---|---|---|---|
| 一 · 基础架构 | 01–04 | 由哪些上游拼成、怎么构建、380 个补丁改了什么 | 缝合点决定了进程模型 |
| 二 · 启动与绑定 | 05–08 | 两套运行时如何共享一个进程、C++ 对象如何变成 JS 对象 | 有了绑定层才有窗口对象 |
| 三 · 窗口与视图 | 09–13 | 窗口的四个身体、preload、隔离世界、像素如何合成 | 多进程对象需要通信 |
| 四 · 通信 | 14–16 | mojom、invoke、contextBridge、四类执行环境 | 通信能力支撑子系统 |
| 五 · 子系统 | 17–20 | 网络、原生 UI、打印、更新与崩溃报告 | 功能齐备后要能测、能发、能测速 |
| 六 · 工程与运维 | 21–24 | 测试、打包、性能、演进机制 | 演进机制回过头解释第一批补丁为何存在 |
这条链在第 24 章合拢:24.3 的 380 个补丁正是第 01 章「缝合线」的物理形态,24.5 把它们按章节归位,24.6 说明新的缝合点仍在产生。架构不是一次画完的图,是每 8 周重放一遍的补丁序列。
24.15.2 拿到一份新源码,先读这六个文件
把全书方法压成可执行的升级检查单。换 Electron 版本、换 Chromium major、或拿到一份陌生 checkout 时,按此顺序读,能在半小时内确定「这一版与上一版的差异面」:
| 序 | 文件 | 读什么 | 对应章节 |
|---|---|---|---|
| 1 | DEPS:3-17,78-90 | Chromium / Node 版本、SHA 钉住的依赖 | 24.1 |
| 2 | config.json + 各目录 .patches 行数 | 补丁总数、集中在哪几个仓库、顺序变化 | 24.3 |
| 3 | fuses.json5:2-4 | _version 是否递增、末尾是否新增键、有无 'r' | 24.9 |
| 4 | buildflags.gni + shell/**/*.mojom | 新增/移除的 buildflag、[EnableIf] 方法 | 24.10、24.12 |
| 5 | docs/breaking-changes.md 最新 major 段 | 五类变更、backport 列表、Deprecated 条目 | 24.8 |
| 6 | package.json:45 的 scripts + build/bundle/ | bundler、类型生成链、lint 入口是否变化 | 24.6、24.11 |
六步之后再看具体 API 文档与 spec。这个顺序的原则是:先读「对齐契约」,再读「功能」。契约变了,所有功能的行为都可能变;契约没变,多数改动只是实现细节。第 24.10.6 那条判据(错配发生在工具↔二进制还是进程↔进程)在六步里对应第 3 与第 4 步,可据此缩小排查范围。
24.15.3 三句话收束本章
第一句:Electron 的演进成本不在写新功能,而在维持对齐契约。 DEPS 钉上游、.patches 钉顺序、fuses.json5 钉位序、api-history.schema.json 钉文档结构、enabled_features 钉接口条件编译。8 周一个 major、17 个上游仓库、380 个补丁,全部压在这几份「小而不可随意改」的数据文件上(24.2、24.3、24.9、24.10)。第 4 章按主题理解的补丁体系,在这里显出了它的另一面:一套高频重放的版本同步协议。
第二句:向后兼容被拆成了四种时间尺度。 弃用与破坏性变更在源码期争取至少一个 major(24.7、24.8);fuse 在打包期让应用方一次性翻转二进制位,且部分不可逆(24.9);buildflag 在编译期裁剪能力,按契约发布后要摘掉(24.12);_Experimental_ 在文档层声明「可能变」,不给时间(24.12.5)。四者互不替代,混用就会写出错误结论——比如把 cookieEncryption 的单向性当成弃用期的兼容承诺。
第三句:本章能写的「展望」只有当下,但判据是长期的。 rolldown 保住 lazy require、Node 快照重新启用、Perfetto 汇流留下 node_use_perfetto_sdk、ENABLE_PROMPT_API 的七处开关链、'r' 墓碑位尚未启用——这些都是可以指向行号的正在演进的机制(24.6、24.10、24.9)。它们共同印证 24.6.4 那句判断:上游每给出一个「独立运行时」能力,Electron 就要把它改造成「嵌入模式」。第 6 章的两个事件循环、第 23 章的单一 Perfetto 会话所有者,都是这句话在不同年代的实例;下一轮升级最先出问题的,仍会是这类「谁拥有一份」的接口。
24.15.4 全书结束
从「一个被缝合的浏览器」到「维持缝合的版本协议」,24 章走完了一圈。中间拆过 6184 行的 WebContents、七个 bundle、四个进程、五个 mojom 接口、九个 fuse、380 个补丁,也记下了一批「未找到」:没有主进程启动耗时打点、没有启用 UMA 上报、没有 sandbox fuse、没有 ElectronBrowser 接口、没有源码树内的 electron.d.ts、没有未来默认值的承诺。阴性结果与阳性证据同等重要——它们划出了这套架构的边界,也划出了「哪些结论必须由自己的应用在自己的机器上验证」。
这本书没有给出任何毫秒数、体积数或性能排行,因为那些数字属于具体的机器与具体的应用。给出的是更耐用的东西:每个结论落在哪个文件、哪一行,以及当上游换了版本时,该回到哪六个文件重新确认。