《Electron 45.2.3 内核解剖》第 3 章 构建系统:GN、Ninja 与 380 个补丁
本章解决的问题:为什么编译一个 Electron 需要几百 GB 磁盘、为什么改一行 TypeScript 会触发 C++ 重编译、
BUILD.gn那 2,234 行到底在编排什么、380 个补丁分别属于哪几类、以及"我能不能只改一个小地方"这个问题的真实答案。
3.0 先破除三个误解
在进入细节之前,必须先拆掉三个几乎人人都有的误解。它们不拆掉,后面所有内容都会读歪。
误解一:构建系统是"打包工具"
不是。构建系统解决的是依赖图问题,不是"把文件塞进压缩包"。
一个 Electron 可执行文件里,有多少个编译单元?把 filenames.gni 里所有 shell/ 开头的路径加起来是 881 条,其中大部分是 .cc/.h/.mm 成对出现,粗略折算约 450 个编译单元。这 450 个单元又依赖 Chromium 的几万个目标。
"哪个文件变了要重编哪些东西"——这个问题在 450 个单元、上万个目标的图上,人脑是算不出来的。GN + Ninja 的存在意义就是算这个图。
打包是 dist_zip 目标,是图的最末端。它占整个构建系统的重要性不到 5%。
误解二:BUILD.gn 是"配置文件"
不是。GN 是一门语言,有变量、作用域、条件、循环、模板、导入。BUILD.gn:1735-1736 是程序。
看这一段真实代码:
BUILD.gn:433-441
foreach(locale, platform_pak_locales) {
data += [ "$root_out_dir/locales/$locale.pak" ]
}
这是循环。再看这一段:
BUILD.gn:41-52
declare_args() {
electron_generate_js2c_code_cache = host_os == target_os
}
这是条件表达式驱动的默认值。再看 filenames.gni:1 里的 filenames = { ... }——那是一个字典字面量,GN 从 2018 年起支持字典。
把 BUILD.gn 当 JSON 读,你永远读不懂它为什么这么写。
误解三:Electron 是"一个项目"
Electron 是一个仓库 + 17 个被补丁修改的上游仓库。
config.json:2-6 里列得清清楚楚:
[
{ "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" },
...
]
十七个条目,十七个仓库。你的构建产物里,Chromium 的代码有 241 个补丁的修改,V8 有 35 个,Node 有 58 个。
所以"Electron 的源码"严格来说不存在。 存在的是"Electron 仓库"加上"打完了补丁的 Chromium 检出"。你读到的 shell/ 只是冰山露出水面的一角。
3.1 三层目录:为什么你的磁盘会爆
第一次 e init 之后,目录长这样:
~/electron/
├── src/ ← Chromium 检出(gclient 同步)
│ ├── chrome/ ← 上游 Chrome 浏览器层
│ ├── content/ ← 多进程内容层
│ ├── third_party/
│ │ ├── blink/ ← 渲染引擎
│ │ ├── electron_node/ ← Node.js(打了 58 个补丁)
│ │ └── ...
│ ├── v8/ ← JS 引擎(打了 35 个补丁)
│ ├── ui/ ← 视图系统
│ ├── electron/ ← ★ Electron 仓库被放在这里
│ │ ├── BUILD.gn
│ │ ├── shell/
│ │ ├── lib/
│ │ └── patches/
│ └── out/
│ ├── Testing/ ← 一个构建目录
│ └── Release/
└── .gclient
关键事实:Electron 仓库不在根目录,它在 src/electron/。
这不是风格问题,是硬约束。Chromium 的 GN 用 // 表示 src/ 根。Electron 的 BUILD.gn 里满篇的 //base、//content/public/browser、//third_party/blink/public:blink,// 必须解析到 Chromium 的根。如果 Electron 不在 src/electron/ 下,// 的语义就对不上。
于是 Electron 自己的引用要写成 //electron/...,而 gn gen 的根必须是 src/:
cd src
gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"
gn gen 的工作目录是 src/,不是 src/electron/。 这是新手第一个卡点:在 src/electron/ 里跑 gn gen 会报"找不到 //build/config/BUILDCONFIG.gn"。
3.1.1 磁盘的账
一次完整检出 + 构建,实测占用:
| 项 | 大小 | 说明 |
|---|---|---|
| 源码检出(含 .git) | 45–60 GB | Chromium 全量历史非常重 |
out/Testing(symbol_level=1) | 25–35 GB | 目标文件 + 中间产物 |
out/Release(official + 符号) | 40–60 GB | ThinLTO 的中间表示很占地方 |
node_modules | 0.5–1 GB | rolldown、typescript 等 |
| 合计 | 70–120 GB | 官方文档建议预留 200 GB |
这解释了为什么绝大多数人不从源码编译 Electron。 但"不编译"不等于"不用懂"——你调试崩溃要看符号,你要 patch 一个行为要知道补丁怎么打,你要判断一个 issue 是 Electron 的锅还是上游的锅,都得靠这一章的知识。
3.1.2 out/ 目录里到底是什么
out/Testing/
├── args.gn ← 你传的 --args,纯文本,可直接改
├── build.ninja ← 由 GN 生成,几十万行
├── toolchain.ninja ← 工具链定义
├── obj/ ← 所有 .o 文件,按目标分目录
├── gen/ ← 所有生成的文件(js2c、buildflags、mojo 绑定)
├── electron ← 最终可执行文件(Linux)
├── resources.pak
├── locales/
└── ...
args.gn 是最该先看的文件。它记录了这次构建的全部参数:
debugging.md:45-46
import("//electron/build/args/testing.gn")
is_debug = false
改构建配置的正确姿势是改 args.gn 再跑 ninja,而不是重新 gn gen——Ninja 会检测到 args.gn 变了,自动重新生成。
3.2 GN 的五个概念
GN 的全部语法可以压缩成五个概念。理解了这五个,BUILD.gn 就没有神秘感了。
3.2.1 target:构建图上的节点
一个 target 是一个"可构建的东西"。类型有:
| 类型 | 产物 | Electron 里用在哪 |
|---|---|---|
source_set | 一组 .o,不链接 | electron_lib(核心) |
static_library | .a / .lib | chromium_src:chrome |
shared_library | .so / .dylib / .dll | ffmpeg |
executable | 可执行文件 | electron_app、electron_xcache |
action | 跑一个脚本,产出文件 | electron_js2c、electron_fuses |
copy | 复制文件 | electron_license |
group | 只聚合依赖,不产出 | electron、testing_build |
bundle_data(mac) | 塞进 .app 的资源 | electron_framework_resources |
source_set 与 static_library 的区别经常被搞混:
static_library真的产出一个归档文件,链接器后处理;source_set不产出归档,它的.o直接进入最终链接。
Chromium 内部大量用 source_set,因为:省一次归档、省一次链接、增量编译更快。代价是目标边界变"软",gn check 更难查。
electron_lib 就是 source_set(BUILD.gn:488)。也就是说,shell/ 下几百个文件编译出的 .o,最终是直接参与 electron_app 的链接的,中间没有 .a。
3.2.2 deps / public_deps:两种依赖
deps = [ ":electron_js2c", "//gin" ]
public_deps = [ "//base", "//content/public/app" ]
区别在于传播性:
deps:只我自己需要,不传给我的使用者;public_deps:我的头文件里#include了它,所以我的使用者也需要它的 include 路径。
选错的后果:
- 该用
public_deps用了deps:使用者编译时报"找不到头文件"; - 该用
deps用了public_deps:依赖图膨胀,gn check会警告(因为它发现使用者其实没用到)。
Electron 的 electron_lib 里,public_deps 只有四个:
BUILD.gn:607-612
public_deps = [
"//base",
"//base:i18n",
"//build/config/compiler:compiler_buildflags",
"//content/public/app",
"//ui/base/unowned_user_data",
]
为什么是这五个? 因为 electron_lib 的公开头文件(browser.h 之类)里 #include 了它们。其余近百个 deps 都是实现细节。
3.2.3 config:编译选项的集合
BUILD.gn:176-178
config("electron_lib_config") {
include_dirs = [ "." , "$target_gen_dir" ]
defines = [ "BLINK_MOJO_IMPL=1", "V8_DEPRECATION_WARNINGS" ]
}
config 可以被 configs += [...] 加到 target 上。它和 cflags、defines 的区别是:config 可以被打包、被 all_dependent_configs 传播、被 remove_configs 移除。
Electron 里有一处非常典型的 config 操作:
# BUILD.gn:1707-1712(electron_app)
configs -= [ "//build/config/compiler:thinlto_optimize_default" ]
configs += [ "//build/config/compiler:thinlto_optimize_max" ]
先减再加。 这是 GN 里覆盖默认配置的唯一方式——同名 config 不会互相覆盖,会冲突。注释解释了为什么:
Perform full ThinLTO optimization in the link step for the main binary, matching what Chrome does for its main executable. The default
thinlto_optimize_defaultconfig links with--lto-O0, which skips link-time optimization entirely and gives up most of the benefit of ThinLTO and PGO.
--lto-O0 意味着"链接期优化全部跳过"。 也就是说,如果你不改这一行,你构建出的 Release 版会比官方版慢——因为你拿到了 ThinLTO 的全部编译开销,却没拿到它的优化收益。
这是一个只能从构建脚本里发现的性能事实。
3.2.4 toolchain:编译器的"身份"
GN 的 target 是 (label, toolchain) 二元组。默认 toolchain 是 //build/toolchain/<os>:<cpu>。
Electron 里有两类特殊 toolchain:
v8_snapshot_toolchain:用于构建 mksnapshot 这类"跑在构建机上、但要针对目标架构生成代码"的工具。注释写得很清楚:
BUILD.gn:30-36
# Cross-arch is supported: the generator is built in v8_snapshot_toolchain
# (V8_TARGET_ARCH set to the target) and reads the target's snapshot blob,
# so the cache it emits is keyed to the target's read-only checksum -- the
# same mechanism that makes V8's mksnapshot cross-arch correct.
"V8_TARGET_ARCH set to the target"——工具跑在 x64 构建机上,但编译时 V8_TARGET_ARCH 设成 arm64。这样它生成的快照,其只读堆的校验和与 arm64 目标一致。这是交叉编译 mksnapshot 的正确做法。
electron_js2c_toolchain:专门给 node_js2c 用。为什么需要单独的 toolchain?因为 node_js2c 是 Node 仓库的目标,它的构建参数(node_module_version 等)由 Electron 的 gni 决定,必须在一个"能读到 Electron 变量"的 toolchain 里构建。
3.2.5 template:GN 的"函数"
bundle.gni:9-11
template("electron_bundle") {
assert(defined(invoker.bundle), "Need the name of the bundle to build")
npm_action(target_name) {
...
}
}
template 定义一个可复用的 target 工厂。invoker 是调用时传进来的参数包。
bundle.gni 全文只有 56 行,但它定义了七个 bundle 的构建方式。这就是 template 的价值。
Electron 里自定义的 template:
| template | 文件 | 用途 |
|---|---|---|
electron_bundle | bundle.gni:9 | 用 rolldown 打一个 bundle |
npm_action | build/npm.gni:1 | 跑一个 package.json script |
typescript_build | build/tsc.gni:3 | 用 tsc 编译到 JS |
node_action | build/asar.gni | 用 node 跑一个脚本 |
asar | build/asar.gni | 打 asar 包 |
dist_zip | build/zip.gni(间接) | 打发布 zip |
strip_binary | strip_binary.gni | 抽符号 + strip |
读 Electron 构建系统的正确顺序是:先读 template,再读使用点。 因为 template 定义了"这类东西怎么建",使用点只是填参数。
3.3 BUILD.gn 的 2,234 行在编排什么
把 BUILD.gn 按行号切开,结构一目了然:
| 行号区间 | 内容 | 类型 |
|---|---|---|
| 1–30 | 30 个 import | 引入上游 gni |
| 33–52 | declare_args():electron_generate_js2c_code_cache | 参数 |
| 54–120 | macOS 平台:assert 版本、assert 上游特性存在 | 平台检查 |
| 85–230 | Linux 平台:pkg_config、generate_library_loader、generate_stubs | 平台检查 |
| 283–316 | action("electron_js2c") | 生成 |
| 318–336 | action("generate_config_gypi") | 生成 |
| 337–456 | default_app 相关 copy | 资源 |
| 458–470 | action("electron_fuses") | 生成 |
| 471–487 | action("electron_generate_node_defines") | 生成 |
| 488–905 | source_set("electron_lib") | 主体 |
| 906–926 | executable("electron_xcache") | 工具 |
| 928–1097 | 五个 flavor 的 code cache 生成 | 生成 |
| 1099–1210 | 资源 allowlist、pak 打包 | 资源 |
| 1212–1700 | macOS:framework、helper、app shim | 平台 |
| 1703–1900 | executable("electron_app") | 产物 |
| 1901–1960 | 许可证、dist zip | 打包 |
| 1960–2075 | chromedriver、mksnapshot、node_headers | 分发 |
| 2075–2080 | group("electron") | 入口 |
| 2082–2200 | strip 目标 | 符号 |
| 2200–2234 | 尾部 | 杂项 |
2,234 行里,真正的"编译逻辑"只有 electron_lib 那 418 行。 其余全是:平台分叉、生成步骤、打包、符号处理。
这个比例说明一件事:构建系统的复杂度不在"编译",在"跨平台"和"生成"。
3.3.1 那两个 assert 值得单独说
BUILD.gn:56-60
assert(
mac_deployment_target == "13.0",
"Chromium has updated the mac_deployment_target, please update this assert and flag this as a breaking change (docs/breaking-changes.md)")
这是一个会主动失败的检查。Chromium 升级了 macOS 最低版本,Electron 的构建会直接失败,并告诉你"这是一个 breaking change,需要写进 docs/breaking-changes.md"。
为什么用 assert 而不是注释? 因为注释会被忽略,assert 不会。这是一个把"流程要求"编码进构建系统的例子。
第二个 assert 更精细:
BUILD.gn:64-71
assert(
filter_include(
read_file(
"//content/browser/renderer_host/render_widget_host_view_mac.mm",
"list lines"),
[ "BASE_FEATURE(kThrottleResizeIpc,*" ]) != [],
"kThrottleResizeIpc is gone from render_widget_host_view_mac.mm; update shell/browser/feature_list_mac.mm")
它读上游源文件的内容,检查某个特性是否还存在。如果 Chromium 删掉了 kThrottleResizeIpc,构建立即失败。
这是"跨仓库契约检查"的最高形式:不是检查接口,是检查源码文本。
为什么需要它?因为 feature_list_mac.mm 用字符串名字启用这个未导出的特性:
// 大意
base::FeatureList::IsEnabled 通过名字查找特性
如果上游删了,运行时不会报错——只是窗口 resize 变慢。这种"静默退化"是最难查的 bug。构建期 assert 把它变成编译错误。
3.4 electron_lib:一个 source_set 装下整个 Electron
BUILD.gn:488 到 905,418 行,定义了一个叫 electron_lib 的 source_set。
它是全书出现频率最高的名字。你在第 1、2 章看到的每一个 C++ 文件,几乎都在这 418 行里被列出。
3.4.1 源码是怎么拼起来的
BUILD.gn:645-661
sources = filenames.lib_sources
if (is_win) {
sources += filenames.lib_sources_win
}
if (is_mac) {
sources += filenames.lib_sources_mac
}
if (is_posix) {
sources += filenames.lib_sources_posix
}
if (is_linux) {
sources += filenames.lib_sources_linux
}
if (!is_mac) {
sources += filenames.lib_sources_views
}
六次 +=。这是一个按平台累加的模式。
filenames.gni 里的 12 个列表:
| 列表 | 条目数(约) | 内容 |
|---|---|---|
lib_sources | 约 420 | 跨平台核心 |
lib_sources_win | 约 70 | Windows 专属 |
lib_sources_mac | 约 45 | macOS 专属 |
lib_sources_posix | 约 8 | POSIX 通用 |
lib_sources_linux | 约 30 | Linux 专属 |
lib_sources_views | 约 25 | 非 mac 的 views |
lib_sources_extensions | 约 40 | 扩展支持 |
framework_sources | 2 | mac framework 入口 |
login_helper_sources | 1 | mac 登录助手 |
default_app_* | 3+4+6 | 默认应用 |
加起来 filenames.gni 里有 881 条 shell/ 路径。
注意 is_posix 和 is_linux 同时为真——Linux 会执行五次 +=。顺序有意义吗? 对编译器没有(它只关心集合),对 gn desc 的输出有(影响可读性)。
3.4.2 为什么 lib_sources_views 要判 !is_mac
因为 macOS 不用 Chromium 的 views 框架,用原生 Cocoa。shell/browser/ui/views/ 下的文件在 macOS 上不参与编译。
反过来说,shell/browser/ui/cocoa/ 只出现在 lib_sources_mac 里。
这个分叉是 Electron 平台差异的第一现场。 第 9 章讲 NativeWindow 时会看到:NativeWindowViews 与 NativeWindowMac 是完全两套实现,共享的只有抽象基类。
3.4.3 一百多个 deps
electron_lib 的 deps 列表有 一百多项。挑几个最能说明问题的:
"//content/public/browser", ← 浏览器进程 API
"//content/public/renderer", ← 渲染进程 API
"//third_party/blink/public:blink" ← Blink 公开接口
"//gin", ← V8 绑定层
"//third_party/electron_node:libnode", ← Node
"//third_party/electron_node:node_snapshot", ← Node 启动快照
"//ui/views", ← 视图框架
"//chrome:strings", ← Chrome 的字符串资源
//chrome:strings 这一行很容易被忽略,但它意味着 Electron 依赖 Chrome 的资源包。 这就是为什么 Electron 的 resources.pak 里有 Chrome 的字符串——比如"另存为"、"打印预览"这些对话框文案。
再看这一行及其注释:
# Provides the strong SnapshotBuilder::GetEmbeddedSnapshotData() (the
# embedded Node startup snapshot) that overrides libnode's weak no-snapshot
# stub. Lets the browser process boot Node from a snapshot.
"//third_party/electron_node:node_snapshot",
"strong ... overrides libnode's weak ... stub"——这是 C++ 链接期的符号覆盖技巧。libnode 里有一个弱符号的空实现,node_snapshot 提供一个强符号的实实现。链接器优先选强符号。
这个技巧让同一个 libnode 可以被两种构建方式使用:有快照的(正式版)和无快照的(某些测试工具)。不需要编译两份 libnode。
代价是:符号覆盖是隐式的。你在代码里看不到任何 #ifdef,但行为完全不同。这类"链接期多态"是 Chromium 代码库的常见手法,读代码时必须配合 BUILD.gn:677-681 才能看懂。
3.4.4 五处条件编译的"功能开关"
electron_lib 里有几处按 buildflag 加源码:
BUILD.gn:671-679
if (enable_prompt_api) {
sources += [
"shell/browser/ai/proxying_ai_manager.cc",
"shell/browser/ai/proxying_ai_manager.h",
"shell/utility/ai/utility_ai_language_model.cc",
...
]
}
# BUILD.gn:893-899(PDF viewer)
if (enable_pdf_viewer) {
sources += [
"shell/browser/electron_pdf_document_helper_client.cc",
...
]
}
这些开关来自 buildflags.gni:5-11:
declare_args() {
enable_pdf_viewer = true
enable_electron_extensions = true
enable_builtin_spellchecker = true
enable_prompt_api = true
override_electron_version = ""
electron_vendor_version = ""
}
四个默认全为 true 的开关。 把它们设成 false 会怎样?
enable_pdf_viewer = false:webPreferences.plugins里的 PDF 查看器没了,<embed type="application/pdf">不工作;enable_electron_extensions = false:整个shell/browser/extensions/不编译,session.loadExtension不存在;enable_builtin_spellchecker = false:拼写检查 API 消失;enable_prompt_api = false:第 2 章提到的BindAIManager那条路没了。
这是"裁剪版 Electron"的官方入口。 如果你的应用不需要 PDF 和扩展,关掉能省几 MB 和若干攻击面。但注意:关掉之后 ABI 变了,你的原生模块可能链接失败(如果它用了被裁掉的符号)。
3.4.5 electron_fuses 的源码是生成出来的
BUILD.gn:895
sources += get_target_outputs(":electron_fuses")
get_target_outputs 拿到另一个 target 的产物路径。electron_fuses 这个 action 产出:
BUILD.gn:458-468
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)
}
从 fuses.json5 生成一对 .h/.cc。 这意味着 fuse 的定义是数据驱动的——加一个 fuse 只需改 json5,不用改 C++。
fuses 本身(在二进制里烧开关,让打包后的应用无法被改)是第 20 章的主题,这里只记住一件事:它的代码不在仓库里,在 gen/ 目录里。
# 想看生成结果
cat out/Testing/gen/electron/build/fuses/fuses.h
3.5 为什么不能用 glob:filenames.gni 存在的理由
这是新手最常问的问题:"为什么要把 881 个文件路径手写进 filenames.gni?用 glob 自动收集不行吗?"
GN 确实有 glob 能力(通过 exec_script 或 GNI 的扩展),但 Electron 明确不用。三个理由,一个比一个硬。
3.5.1 理由一:增量编译的正确性
Ninja 的增量依赖一个前提:构建图在两次构建之间是稳定的。
如果 sources 由 glob 决定,那么"新增一个文件"会改变构建图。GN 检测不到这个变化——它不知道目录内容变了。
后果:
# 你新建了 shell/browser/my_feature.cc
touch shell/browser/my_feature.cc
ninja -C out/Testing electron
# → 什么都没编译,因为 build.ninja 里没有这个文件
你必须手动 gn gen 一次。而 gn gen 在 Chromium 这种规模下要跑 20–60 秒。
显式列表把"图变了"这个事件变成了"文件变了"——filenames.gni 的 mtime 变了,GN 就会重新生成。这是可靠的。
3.5.2 理由二:gn check 需要精确的边界
gn check 是一个依赖合法性检查器:它编译每个文件,看 #include 的头文件是否来自已声明的 deps。
如果有 glob,一个目录里的文件可能属于不同的 target,gn check 就无法判断"这个 include 该不该被允许"。
Electron 把这个检查接进了 CI:
script/gn-check.js:23-30
const gnCheckDirs = [
'//electron:electron_lib',
'//electron:electron_app',
'//electron/shell/common:mojo',
'//electron/shell/common:plugin',
'//electron:testing_build',
'//electron:release_build'
];
for (const dir of gnCheckDirs) {
const args = ['check', `../out/${OUT_DIR}`, dir];
const result = cp.spawnSync('gn', args, { env, stdio: 'inherit' });
if (result.status !== 0) process.exit(result.status);
}
六个 target,逐个 check,任一失败就退出。 所以你的 PR 如果漏了一个 dep,CI 会挂。
3.5.3 理由三:有些文件必须明确"不编译"
filenames.gni 的显式列表还有一个隐性作用:它能表达"这个文件存在但不参与构建"。
比如 shell/browser/ui/views/ 下的文件在 macOS 上被排除(if (!is_mac))。如果靠 glob,你得写排除规则;排除规则比白名单更容易出错——新加的文件会被意外包含。
白名单的失效模式是"漏了",会立刻报错;黑名单的失效模式是"多了",可能悄悄编进去。 前者远好于后者。
3.5.4 filenames.auto.gni:能自动的才自动
与 filenames.gni 相对,还有 filenames.auto.gni(833 行),头部写着:
# THIS FILE IS AUTO-GENERATED, PLEASE DO NOT EDIT BY HAND
auto_filenames = {
api_docs = [ ... ]
node_header_sources = [ ... ]
lib_typecheck_sources = [ ... ]
webview_bundle_deps = [ ... ]
isolated_bundle_deps = [ ... ]
browser_bundle_deps = [ ... ]
renderer_bundle_deps = [ ... ]
worker_bundle_deps = [ ... ]
node_bundle_deps = [ ... ]
utility_bundle_deps = [ ... ]
}
注意它自动化的内容与手写的内容的区别:
| 自动生成 | 手写 |
|---|---|
文档清单(docs/api/*.md) | C++ 源文件清单 |
| Node 头文件清单 | 平台分叉 |
| TS 类型检查输入 | deps |
| bundle 的依赖闭包 | 编译选项 |
规律:能从"内容"推导出来的,自动生成;需要"意图"的,手写。
bundle 的依赖闭包为什么能自动?因为它是 rolldown 算出来的——真正的模块图。这个图不能靠人写,写错就是漏打包。
生成脚本是 script/gen-filenames.mts:72-73,核心是这一段:
const child = cp.spawn('node', ['./build/bundle/bundle.mjs', '--target', bundleTarget.target, '--print-graph'], {
cwd: rootPath
});
它真的跑了一遍 rolldown,只为了拿 --print-graph 的输出。 这是 3.6 节要讲的机制。
而校验是:
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,不一致就失败,提示你重新生成。
这是"生成文件必须提交"模式的标准做法:生成物进仓库(这样构建不需要先跑生成器),但 CI 验证它没漂移。
3.5.5 一个反面教材
filenames.libcxx.gni 有 1,692 行,filenames.hunspell.gni 64 行。这些也是列表,但它们是上游文件的镜像——libc++ 的头文件清单,hunspell 的词典清单。
这类列表没法手写维护(上游一变就不同步),也不适合放进 filenames.auto.gni(它们不是从本仓库推导的)。
它们由 script/gen-libc++-filenames.js 和 script/gen-hunspell-filenames.js 生成。每个生成器对应一种"外部真相源"。
3.6 七次 rolldown:从 lib/*.ts 到七个 bundle
Electron 的 lib/ 目录有 94 个 TypeScript 文件、10,147 行。它们不会以源码形式进二进制,而是被七次独立打包成七个 bundle。
3.6.1 七个 target 的清单
targets.mjs:23-30 全文只有一个导出:
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
}
};
七个 key,对应七个 bundle 文件。 与 electron_js2c 的 sources 完全对应:
BUILD.gn:294-302
sources = [
"$root_gen_dir/internal/electron/js2c/browser_init.js",
"$root_gen_dir/internal/electron/js2c/isolated_bundle.js",
"$root_gen_dir/internal/electron/js2c/node_init.js",
"$root_gen_dir/internal/electron/js2c/renderer_init.js",
"$root_gen_dir/internal/electron/js2c/utility_init.js",
"$root_gen_dir/internal/electron/js2c/webview_bundle.js",
"$root_gen_dir/internal/electron/js2c/worker_init.js",
]
七对一。每个文件对应一种"JS 运行环境"。
注意命名的不一致:browser → browser_init.js,isolated_renderer → isolated_bundle.js,webview → webview_bundle.js。这个不一致是历史遗留(*_init 是老名字,*_bundle 是新名字),别指望它有规律——路径在 GN 里硬编码着。
3.6.2 四个开关各自解决什么问题
targets.mjs 的注释把四个开关讲得很清楚,但需要展开。
alwaysHasNode
The bundle runs inside a Node.js environment and is called with Node's
processand internalrequire(seejs2c_bundle_ids.h:41-44), so Node.js built-in andinternal/*modules are left as runtimerequire()calls. Bundles without it must be fully self-contained; they get a minimalprocessshim (process.ts:6-16) and a native EventEmitter in place ofevents(node-events.ts:5).
翻译:有 Node 的 bundle 可以 require('fs'),没 Node 的 bundle 一个 require 都不能有。
这条约束是硬性检查,不是君子协定:
bundle.mjs:262-268
if (!target.alwaysHasNode && chunk.imports.length + chunk.dynamicImports.length) {
throw new Error(
`The ${args.target} bundle has no require() at runtime but imports ${[...chunk.imports, ...chunk.dynamicImports].join(', ')}`
);
}
打包完成后检查残留 import,有一个就抛错。 这保证了 webview 和 isolated_renderer 两个 bundle 是真正自包含的——它们要跑在没有 require 的环境里。
哪些 bundle 没有 Node?
webview:<webview>标签注入 guest 页面的脚本。guest 可能完全没有 Node(nodeIntegration: false)。isolated_renderer:隔离世界的 preload。它天然不能有 Node。
这就是为什么 process.ts:6-16 存在——一个假的 process 对象,只有 platform、versions 之类的只读字段。看它的注入:
bundle.mjs:137-139
if (!target.alwaysHasNode) {
inject.process = ['@electron/internal/webview/process', 'default'];
}
inject 是 rolldown 的"自动导入"机制,类似 webpack 的 ProvidePlugin:源码里裸写 process,打包时自动变成 import process from '.../webview/process'。
loadElectronFromAlternateTarget
Resolve
require('electron')tolib/<alternate>/api/exports/electron.tsinstead of the target's own module list.
worker、webview 都用 'renderer'。为什么?
因为 Worker 里的 require('electron') 应该拿到渲染进程的 API 集合,而不是一个"worker 专属"的集合(后者不存在)。<webview> 的 guest 也是渲染进程语义。
代码:
bundle.mjs:95-99
const electronAPIFile = path.resolve(
lib,
target.loadElectronFromAlternateTarget ?? args.target,
'api',
'exports',
'electron.ts'
);
bundle.mjs:103-112
const exactAliases = new Map(
['electron', 'electron/main', 'electron/renderer', 'electron/common', 'electron/utility'].map((id) => [
id,
electronAPIFile
])
);
五个模块 id 全部指向同一个文件。 这意味着在打包后的 bundle 里,require('electron')、require('electron/main')、require('electron/renderer') 是同一个模块实例。
这是必要的:否则 require('electron').ipcRenderer 和 require('electron/renderer').ipcRenderer 会是两个不同的对象,=== 比较失败,事件监听器注册到不同实例上。
targetDeletesNodeGlobals
process,globalandBuffermay be deleted from the global scope before bundle code runs later on, so free references to them are rewritten to the copies captured bynode-globals.ts:1-14.
这条最微妙。为什么全局的 process 会被删?
因为渲染进程的 init.ts 会重写 Module.wrapper(第 1 章提过)。在这个重写里,它把 process、global、Buffer 从全局作用域里"摘"出来,改成参数注入——为了让用户代码里的 process 指向正确的实例。
具体做法:
bundle.mjs:130-135
if (target.targetDeletesNodeGlobals) {
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 引用改写成 import { process } from 'node-globals'。
这样即使运行时 globalThis.process 被替换或删除,bundle 内部用的还是打包时捕获的那个引用。
这是一个"防御性打包"的例子:不是为了防止 bug,是为了防止用户代码的副作用影响框架。
wrapInitWithProfilingTimeout 与 wrapInitWithTryCatch
bundle.mjs:238-256
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__();
}
`;
}
if (target.wrapInitWithTryCatch) {
code = `try {
${code}
} catch (err) {
console.error('Electron ${outputFilename} script failed to run');
console.error(err);
}
`;
}
两个包装,两个目的:
--profile-electron-init:把初始化推迟一个 tick,这样它出现在 Performance 面板的独立任务里,可以单独测量。这是给性能工程师用的钩子。try/catch:bundle 求值失败时打印错误而不是抛出。这是给最终用户的——渲染进程初始化失败时,用户至少能在 console 里看到原因,而不是一片空白。
注意只有 renderer 同时有两个包装,worker、webview、isolated_renderer 只有 try/catch,browser、node、utility 一个都没有。
为什么主进程不包 try/catch?因为主进程初始化失败就应该崩——静默失败比崩溃更难查。
3.6.3 打包配置的五个非默认选择
bundle.mjs:216-232
const {
output: [chunk, ...rest]
} = await bundle.generate({
format: 'cjs',
exports: 'none',
codeSplitting: false,
keepNames: true,
minify,
strict: false
});
逐个解释。
format: 'cjs'
注释说:
The bundles are compiled as function bodies (see
util::CompileBundle), the Node.js ones with arequireparameter that external imports are left as calls to. Nothing providesmoduleorexports.
bundle 不是一个模块,是一个函数体。 它被 util::CompileAndCall 编译成一个 JS 函数,参数是 (process, require)。所以在 bundle 里不能出现 module.exports、export default 之类的东西。
用 CJS 格式而不是 ESM,是因为 rolldown 生成 CJS 时不会插入 "use strict" 之外的模块系统代码,最接近"裸函数体"。
exports: 'none'
强制不生成任何导出语句。如果 lib/browser/init.ts 里有 export,打包会报错。这是编译期强制"入口文件不能导出"。
codeSplitting: false
不分包。七个 bundle 各自单文件——因为它们要被 js2c 编成 C++ 字符串,多文件没法处理。
keepNames: true
注释:
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 里可见(用户会读),如果被压缩成 t,instanceof 判断和 constructor.name 判断全乱。
同时 minify 配置里也有 keepNames:
bundle.mjs:201-205
const minify =
args.mode === 'production'
? {
compress: { keepNames: { function: true, class: true } },
mangle: { toplevel: true, keepNames: true }
}
: false;
mangle.toplevel: true 会重命名顶层变量,keepNames: true 保护函数和类名。这个组合的目的:变量名尽量短(省体积),但 API 可见的名字保留。
strict: false
因为 "use strict" 是外面手动加的:
bundle.mjs:272
code = `'use strict';\n${code}`;
为什么手动加?因为 rolldown 的 strict: false 会把 directive 放在 IIFE 内部,而 Electron 需要它在最外层——这样整个 bundle(包括 IIFE 外部)都是严格模式。
3.6.4 那个 IIFE 为什么必须存在
bundle.mjs:270-276
let code = `(() => {
${chunk.code}
})();
`;
注释解释:
The bundle is compiled as a function body (by Electron with the parameters in
js2c_bundle_ids.h, and bynode_mksnapshotwith Node's built-in module parameters: exports, require, module, process, internalBinding, primordials), so keep the hoisted top-level declarations oflib/in their own scope rather than let one of them redeclare a parameter.
关键:bundle 是函数体,它的参数名是 process、require。
如果 lib/ 里有一个顶层声明叫 const process = ...,在函数体里就会与参数冲突——SyntaxError: Identifier 'process' has already been declared。
包一层 IIFE,所有顶层声明就进了 IIFE 的作用域,不会与外部参数冲突。
这个细节只有在你真的往 lib/ 里加一个叫 process 的顶层变量时才会暴露。 但它是一个真实的坑。
3.6.5 node externals:为什么需要一个 15 行的 shim
这是整个 bundle.mjs:152-159 里最精巧的一段:
bundle.mjs:149-176
const nodeModules = new Set(builtinModules);
const nodeShimPrefix = '\0electron-node-external:';
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`);
}
if (kind === 'require-call') return { id, external: true };
return { id: `${nodeShimPrefix}${id}`, moduleSideEffects: false };
}
},
load: {
filter: { id: new RegExp(`^${nodeShimPrefix}`) },
handler(id) {
return `module.exports = require(${JSON.stringify(id.slice(nodeShimPrefix.length))});`;
}
}
};
它要解决的问题:ESM import 会被提升到文件顶部。
考虑 lib/common/foo.ts:
import { readFile } from 'fs';
如果直接把 fs 标成 external,rolldown 会生成:
const fs = require('fs'); // ← 在文件最顶部
问题是:bundle 的最顶部就等于"进程启动的最早时刻"。 而 Node 的内置模块加载有副作用(分配内存、注册 handler、初始化 binding)。如果这些发生在 Electron 的初始化还没准备好的时候,就会出问题。
webpack 时代的做法是保留 CJS 的 require 调用(不提升),所以加载是懒的。为了保持这个行为,Electron 做了一件事:
把 import 改写成"通过一个中间模块 require"。
// 生成的 shim 模块内容
module.exports = require("fs");
而 import 这个 shim 模块,是 ES 语义(提升到顶部),但 shim 内部只有一句 module.exports = require(...)——这句 require 是在 shim 模块被求值时才执行的,而 shim 模块的求值也是懒的(因为 CJS 的 require 有缓存,且只有真正用到时才触发)。
等等,这里需要更精确:import 会被提升,所以 shim 模块的 require 也会在顶部执行。那不就白搭了?
不是。 关键在 moduleSideEffects: false。这告诉 rolldown:这个模块没有副作用,可以安全地摇树。 如果 shim 导出的绑定在某个代码路径里没被用到,rolldown 就会把这整个 import 删掉;如果被用到,它会被内联到实际使用的位置(在 tree-shaking 之后,模块边界已经被打散)。
所以最终效果是:只有在真正用到 fs 的代码路径上,才有 require('fs')。 这正是 webpack 时代的行为。
3.6.6 BUILDFLAG 的折叠
lib/ 里的 TypeScript 可以写:
if (BUILDFLAG(ENABLE_PDF_VIEWER)) {
// ...
}
BUILDFLAG 不是 TypeScript 语法,它是一个编译期常量替换,由 plugin 完成:
bundle.mjs:79-95
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)})`;
});
}
}
};
替换成 (true) 或 (false)。
然后 rolldown 的压缩器会把 if ((false)) { ... } 整块删掉。这就是为什么关掉一个 buildflag 能真的减小 bundle 体积,而不是只留一个死分支。
buildflags 值从哪来?从生成的头文件:
bundle.mjs:72-78
if (args.buildflags) {
const flagFile = fs.readFileSync(args.buildflags, 'utf8');
for (const [, name, value] of flagFile.matchAll(/#define BUILDFLAG_INTERNAL_(.+?)\(\) \(([01])\)/g)) {
buildflags.set(name, value === '1');
}
}
正则匹配 #define BUILDFLAG_INTERNAL_NAME() (1)。这是 Chromium buildflag_header 模板的固定格式。
所以 TS 侧的 BUILDFLAG 与 C++ 侧的 BUILDFLAG 读的是同一个头文件、同一个值。 这是"单一真相源"的实现。
如果 BUILDFLAG 用了一个不存在的名字,this.error(...) 直接让构建失败——不是警告,是错误。 因为一个未定义的名字替换成 undefined 会产生静默的行为错误。
注意这个 if:
bundle.mjs:80
if (!args.buildflags) return null;
--print-graph 时不传 buildflags,此时 plugin 不工作,BUILDFLAG 保持原样。为什么这样可以?因为 --print-graph 只关心模块图,不关心代码内容。注释说:
Without a buildflags.h (
--print-graph, or a plain compile check) the call is left for the BUILDFLAG declaration intypings/to satisfy.
typings/ 里有 BUILDFLAG 的类型声明,所以即使不替换也能通过 TS 类型检查。
3.6.7 类型检查:为什么不在 bundle 里做
bundle.mjs 的第 8 行注释:
// Type checking is not done here; see typecheck.mjs.
typecheck.mjs:23-27 只有 37 行,核心是:
const tsc = path.resolve(import.meta.dirname, '..', '..', 'node_modules', 'typescript', 'bin', 'tsc');
const { status, error } = spawnSync(
process.execPath,
[tsc, '--project', path.resolve(args.project), '--noEmit', '--pretty'],
{ stdio: 'inherit' }
);
--noEmit:只检查,不产出。
为什么分开?因为 rolldown 只做"类型擦除",不做类型检查(它用 oxc 的 transform,速度极快但不验证类型)。类型检查是 O(整个项目),打包是 O(单个入口的闭包)。 混在一起会让每次打包都变成全项目检查。
而 GN 里,这一步是依赖而不是步骤:
bundle.gni:44-48
deps += [
# rolldown only strips types; refuse to bundle code that does not check.
"//electron:electron_lib_typecheck",
"//electron/buildflags",
]
七个 bundle 全部依赖同一个 typecheck 目标。 所以类型检查只跑一次,七个 bundle 共享结果。
注意 typecheck 的 stamp 逻辑:
typecheck.mjs:32-37
if (args.stamp && !fs.existsSync(args.stamp)) {
fs.mkdirSync(path.dirname(args.stamp), { recursive: true });
fs.writeFileSync(args.stamp, '');
}
注释:
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.
只在 stamp 不存在时创建,不更新已有 stamp 的 mtime。
这是 restat 的关键:Ninja 看到 action 的输出现有文件的 mtime 没变,就认为"什么都没变",下游不用重建。如果每次都 touch stamp,七次打包会被无谓触发。
这个细节决定了"改一行不影响类型的代码"时不会重跑七次打包。
3.7 两级转换:bundle → js2c → electron_natives.cc
打包完成,gen/internal/electron/js2c/ 下有七个 .js 文件。下一步是把它们变成 C++ 能读的东西。
3.7.1 build/js2c.py:3-10 只有 15 行
#!/usr/bin/env python3
import os
import subprocess
import 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())
它自己什么都不做。 全部逻辑都在 node_js2c 里——那个可执行文件来自 Node 仓库:
BUILD.gn:285-292
deps = [
":electron_browser_bundle",
...
"//third_party/electron_node:node_js2c($electron_js2c_toolchain)",
]
node_js2c 是 Node 自己的构建工具(Node 也把自己的 lib/*.js 编进二进制),Electron 直接复用它。
为什么要写这层 Python 包装?因为 GN 的 action 需要一个 script,而 node_js2c 是构建产物(在 out/ 里),不是脚本。包装层负责:
- 把参数顺序转成
node_js2c期望的顺序; - 加
--only-js标志(只要 JS,不要 Node 的其他 hack); - 用
subprocess.check_call让失败传播出去。
check_call vs call:前者在返回码非零时抛 CalledProcessError,进程退出码非零,Ninja 认为失败。用 call 会让失败被吞掉——这是一个非常常见的构建脚本 bug。
3.7.2 --root 参数决定了模块 id
args 里传的是 rebase_path("$root_gen_dir"):
BUILD.gn:311-315
args = [
rebase_path("$out_dir/node_js2c"),
rebase_path("$root_gen_dir"),
] + rebase_path(outputs, root_gen_dir) +
rebase_path(sources, root_gen_dir)
sources 被 rebase_path(sources, root_gen_dir) 转成相对于 gen/ 的路径,得到:
internal/electron/js2c/browser_init.js
internal/electron/js2c/renderer_init.js
...
这些相对路径就是模块 id。 加上 --root 指向 gen/,node_js2c 在生成代码时把每个文件注册成 internal/electron/js2c/<name>。
这与 js2c_bundle_ids.h:29-35 里的字符串必须完全一致:
inline constexpr char kBrowserInitId[] = "internal/electron/js2c/browser_init";
inline constexpr char kRendererInitId[] = "internal/electron/js2c/renderer_init";
inline constexpr char kUtilityInitId[] = "internal/electron/js2c/utility_init";
inline constexpr char kWorkerInitId[] = "internal/electron/js2c/worker_init";
inline constexpr char kNodeInitId[] = "internal/electron/js2c/node_init";
inline constexpr char kWebViewBundleId[] = "internal/electron/js2c/webview_bundle";
inline constexpr char kIsolatedBundleId[] = "internal/electron/js2c/isolated_bundle";
七个 id,七个文件,字符串字面量对得上。 对不上的话,运行时 LookupAndCompileFunction 会找不到模块,抛 Cannot find module。
这类"两处硬编码同一字符串"的设计是脆弱的。Electron 用测试兜住了它(3.8 节)。
3.7.3 electron_natives.cc 长什么样
生成结果是单个 C++ 文件。它的结构(简化):
// gen/electron_natives.cc(结构示意)
#include "shell/common/node_includes.h"
namespace electron {
namespace internal {
// 每个 bundle 一个数组,内容是 UTF-8 源码的字节
static const uint8_t browser_init_raw[] = { 0x27, 0x75, 0x73, ... };
static const uint8_t renderer_init_raw[] = { ... };
// ... 共七个
} // namespace internal
} // namespace electron
外加一个注册函数,把这些数组挂到 Node 的 BuiltinLoader 上。
这个文件的体积很可观。 七个 bundle 的源码总和(未压缩)约 1.5–2 MB,转成 uint8_t 数组后是每字节 6 个字符(0x41, ),所以 .cc 文件可能有 10 MB 左右。
这就是为什么改一行 TS 会触发一次很重的 C++ 编译:electron_natives.cc 变了,它属于 electron_lib 这个 source_set,而 source_set 没有归档边界——但编译器仍要重新编译这一个巨大的翻译单元。
一个 10MB 的 .cc(几百万个整数字面量)编译起来要 10–40 秒,而且内存占用以 GB 计(clang 要为每个字面量建 AST 节点)。
3.7.4 为什么先 bundle 再 js2c,而不是直接 js2c
因为 node_js2c 只做"文件 → 字节数组",不理解模块系统。
如果直接把 94 个 .ts 文件丢给 js2c,运行时 require('./foo') 会失败——因为运行时没有文件系统,只有模块注册表。
所以必须先用 rolldown 把所有 import 内联成一个文件,让"模块解析"发生在构建期。这是"打包"的本质。
两级转换的分工:
| 阶段 | 工具 | 输入 | 输出 | 解决的问题 |
|---|---|---|---|---|
| 1 | rolldown | 94 个 .ts | 7 个 .js | 模块解析、类型擦除、tree-shaking |
| 2 | node_js2c | 7 个 .js | 1 个 .cc | 嵌入二进制 |
3.7.5 为什么需要 electron_js2c_toolchain
"//third_party/electron_node:node_js2c($electron_js2c_toolchain)"
注意那个 ($electron_js2c_toolchain) 后缀——它指定了这个目标在哪个 toolchain 里构建。
默认 toolchain 构建的是"目标平台的 Electron"。但 node_js2c 是跑在构建机上的工具,应该用主机 toolchain。
更复杂的是:node_js2c 需要读 Node 的构建配置(node_module_version 等),这些配置在 Electron 的 gni 里定义,所以需要一个"能用 Electron 变量、但按主机编译"的 toolchain。
build/js2c_toolchain.gni 定义了这个 toolchain。这是交叉编译的标准做法:工具用主机 toolchain,产物用目标 toolchain。
3.8 代码缓存:五个 flavor 是怎么来的
这是 Electron 45 构建系统里最复杂、也最容易被忽略的一块。BUILD.gn:906-1097,192 行,只为生成五个 .cc 文件。
3.8.1 问题:为什么需要预编译代码缓存
V8 执行 JS 有两种方式:
- 从源码编译:解析 → 生成字节码 → 执行。慢(对大文件而言);
- 从代码缓存反序列化:直接加载已编译的字节码。快得多。
V8 的代码缓存有一个键(key),包含:
- 源码本身的哈希;
- 编译参数(
params)的哈希; - V8 flag 集合的哈希(
FlagList::Hash()); - 只读堆的校验和(read-only checksum)。
只要键匹配,缓存可用;否则退化成源码编译。
Electron 的七个 bundle 在每个进程启动时都要执行。 如果每次都从源码编译,主进程启动要多花 30–50ms,渲染进程多花 10–20ms。这在第 2 章讲的启动时间构成里是实实在在的一块。
所以 Electron 在构建期就把这些 bundle 编译一遍,把代码缓存烧进二进制。
3.8.2 键里的"只读堆校验和"是最麻烦的部分
前三个键(源码、params、flags)都是构建期可控的。第四个不是:
只读堆的校验和取决于进程是用哪个快照启动的。
V8 有一个"启动快照"(startup snapshot),包含初始化后的堆。Electron 有两个来源:
snapshot_blob.bin:V8 的默认快照(v8_context_snapshot);- Node 的内嵌启动快照:
node_snapshot,由node_mksnapshot生成,包含 Node 的整个初始化状态。
主进程用后者(这样 Node 不用从零初始化),渲染进程用前者。
两个快照的只读堆校验和不同 → 代码缓存不能通用。
这就是为什么需要"每个 flavor 一份缓存"。
3.8.3 _js2c_cc_flavors:四个显式定义 + 一个特殊处理
BUILD.gn:986-1014
_js2c_cc_flavors = [
{
name = "sandbox" # sandboxed renderer (no Node env)
flags = "--enable-sharedarraybuffer-per-context"
node_builtins = false
},
{
name = "renderer"
flags = "--enable-sharedarraybuffer-per-context --rehash-snapshot " +
"--no-freeze-flags-after-init"
node_builtins = true
},
{
name = "utility"
flags = "--rehash-snapshot --no-freeze-flags-after-init"
node_builtins = !node_use_node_snapshot
},
{
name = "worker"
flags = "--rehash-snapshot --no-freeze-flags-after-init"
node_builtins = false
},
]
四个 flavor,字段是 flags 和 node_builtins。
flags 里的每一项都不是随便写的。 注释说:
The flag deltas below were captured from live processes.
"从运行中的进程里抓下来的"。 意思是:维护者启动了 Electron,读了每个进程的实际 V8 flag 集合,然后把"与默认值的差异"写进这里。
为什么必须精确?因为 FlagList::Hash() 是对非默认 flag 求哈希。多一个少一个,哈希就变,缓存就失效。
逐个看这些 flag 的来历:
--enable-sharedarraybuffer-per-context:渲染进程和 sandbox 有,主进程和 utility 没有。因为SharedArrayBuffer在渲染进程里需要跨 context 隔离(Spectre 缓解),这是 Blink 的默认行为。--rehash-snapshot:反序列化快照后重新计算字符串哈希。渲染进程启动时会改字符串表,必须 rehash。--no-freeze-flags-after-init:允许初始化后改 flag。渲染进程需要(因为webPreferences可能动态改配置)。
注意 sandbox 只有第一个 flag。 因为 sandbox renderer 没有 Node 环境,不涉及快照反序列化,所以不需要 --rehash-snapshot。
3.8.4 node_builtins:那个"6.5 MB per flavor"的注释
# `node_builtins`: whether the flavor also carries a cache for Node's own
# builtins, i.e. whether its processes bootstrap their Node.js environment
# from scratch on this build instead of deserializing it from the embedded
# Node startup snapshot (~6.5 MB per flavor, so only where it is consumed).
每个带 Node builtins 缓存的 flavor 要多占约 6.5 MB。
所以这个开关的原则是"只在真的用到时才开":
| flavor | node_builtins | 理由 |
|---|---|---|
sandbox | false | 没有 Node 环境 |
renderer | true | 渲染进程的 Node 是从零 bootstrap 的 |
utility | !node_use_node_snapshot | 有快照时从快照反序列化,不需要 |
worker | false | Worker 环境不 bootstrap Node builtins |
browser | true(无快照时) | 主进程 bootstrap Node |
这里有一个反直觉的事实:渲染进程的 Node 是"从零 bootstrap"的。
为什么?因为渲染进程不能反序列化主进程的 Node 快照——快照里的堆包含主进程特有的对象(BrowserWindow 之类),渲染进程用不了。所以渲染进程必须重新初始化 Node。
这就是渲染进程比主进程启动慢的一部分原因。 也是 nodeIntegrationInWorker 打开后 Worker 创建变慢的原因。
3.8.5 主进程的特殊处理
BUILD.gn:1016-1020
# The browser flavor is special-cased below when a Node startup snapshot is
# embedded: its isolate (and so its code-cache read-only checksum) comes from
# that snapshot, not the v8 context snapshot. Without a snapshot it boots from
# the v8 context snapshot like the rest, and bootstraps Node from scratch.
if (!node_use_node_snapshot) {
_js2c_cc_flavors += [
{
name = "browser"
flags = "--rehash-snapshot --no-freeze-flags-after-init"
node_builtins = true
},
]
}
有 Node 快照时,浏览器 flavor 不进这个列表——因为它走的是另一个 action:
BUILD.gn:1058-1062
if (node_use_node_snapshot) {
action("run_electron_natives_codecache_browser") {
deps = [
":electron_natives_codecache_snapshot($v8_snapshot_toolchain)",
"//v8:run_mksnapshot_default",
]
...
注意 electron_natives_codecache_snapshot 与 electron_natives_codecache 的区别:
| 工具 | 链接的 Node 目标 | 用途 |
|---|---|---|
electron_natives_codecache | node_snapshot_stub | 对着 v8_context_snapshot 生成 |
electron_natives_codecache_snapshot | node_snapshot | 对着内嵌 Node 快照生成 |
注释解释了这个分叉的必要性:
The browser process boots from the embedded Node startup snapshot, whose read-only heap (and thus the code-cache read-only checksum) is owned uniquely by the SnapshotCreator-produced blob -- matching no standalone snapshot file.
"matching no standalone snapshot file"——内嵌 Node 快照的只读堆是 SnapshotCreator 现场产出的,磁盘上没有对应的文件。所以你不能"给它一个 blob 路径",必须链接真正的 node_snapshot,让工具自己调 GetEmbeddedSnapshotData() 拿到。
这就是那个 node_snapshot_stub vs node_snapshot 的符号覆盖技巧在这里的第二次应用。
3.8.6 生成工具的实现要点
electron_natives_codecache_main.cc:40-42,头部注释说明了核心约束:
compiling each bundle through the same BuiltinLoader path its runtime consumer uses so the source/params hash matches by construction.
"by construction"——不是"我们小心地让两边一致",而是"让两边走同一条代码路径,所以必然一致"。
electron_natives_codecache_main.cc:37-42
// Each bundle is compiled the way util::CompileAndCall compiles it at runtime:
// LookupAndCompileFunction with explicit `params`.
struct Bundle {
const char* id;
std::span<const std::string_view> params;
};
electron_natives_codecache_main.cc:47-59
std::vector<Bundle> BundlesForFlavor(std::string_view flavor,
bool from_node_snapshot) {
const Bundle kWebView{js2c::kWebViewBundleId, js2c::kWebViewBundleParams};
const Bundle kIsolated{js2c::kIsolatedBundleId, js2c::kIsolatedBundleParams};
const Bundle kNodeInit{js2c::kNodeInitId, js2c::kInitBundleParams};
const Bundle kBrowserInit{js2c::kBrowserInitId, js2c::kInitBundleParams};
const Bundle kRendererInit{js2c::kRendererInitId, js2c::kInitBundleParams};
const Bundle kUtilityInit{js2c::kUtilityInitId, js2c::kInitBundleParams};
const Bundle kWorkerInit{js2c::kWorkerInitId, js2c::kInitBundleParams};
if (flavor == "sandbox")
return {kWebView, kIsolated};
BundlesForFlavor 决定了每个 flavor 生成哪些 bundle 的缓存。 sandbox 只要两个(webview、isolated),因为沙箱渲染进程只跑这两个。
主进程呢?browser flavor 需要 browser_init、node_init、webview_bundle、isolated_bundle……因为主进程也可能创建 <webview> 的 guest。
3.8.7 js2c_bundle_ids.h:那个"两边必须同步"的头
js2c_bundle_ids.h:17-20
// The internal/electron/js2c/* framework bundle ids and the parameter names
// each bundle's wrapper function is compiled with. 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.
三句话,三个关键信息:
- id 和 params 都进代码缓存的键;
- 生成器和运行时必须用同一个 params,这个头文件是唯一的真相源;
- 有一个 spec 测试断言"每个 bundle 的缓存都被消费了"。
第三点是最重要的。"缓存被消费"是可以测的:
// spec/api-js2c-code-cache.spec.ts(大意)
// 启动每个进程类型,检查 V8 的 code cache 命中统计
如果某个 bundle 的缓存没被用上(因为参数不匹配),测试会失败。这让"参数漂移"从"性能悄悄退化"变成"CI 红灯"。
3.8.8 五个生成文件的代价
五个 .cc,每个包含若干 bundle 的序列化代码缓存(二进制 blob)。总量估算:
| flavor | 大约体积 |
|---|---|
| browser | 2–4 MB |
| renderer | 3–5 MB(含 Node builtins 的 6.5MB 压缩后) |
| sandbox | 1–2 MB |
| utility | 1–2 MB |
| worker | 1–2 MB |
这些是纯数据,编译起来比 electron_natives.cc 快得多(数组字面量,没有 AST 复杂度)。
但它们是二进制进二进制:electron_natives_code_cache_*.cc 里的字节数组最终变成 .rodata 段的一部分。所以 Electron 可执行文件的体积里,有 10 MB 左右是"预先编译好的 JS 字节码"。
这是"用体积换启动速度"的典型交易。 关掉它(electron_generate_js2c_code_cache = false):
BUILD.gn:36-37
declare_args() {
# Emit a build-time V8 code cache for the internal/electron/js2c/* bundles.
# When false an empty stub is compiled and bundles compile from source.
electron_generate_js2c_code_cache = host_os == target_os
}
关掉之后:
} else {
sources += [ "shell/common/node_natives_code_cache_stub.cc" ]
}
一个空 stub 顶替五个文件。体积省 10MB,启动慢 30–50ms。
注意默认值是 host_os == target_os。 交叉编译(比如在 Linux 上构建 Windows 版)时默认关闭,因为注释说 "Cross-OS is untested and stays off"。
3.9 buildflags:四个开关,一个头文件,两侧同步
buildflags/BUILD.gn:8-11 只有 32 行,但它定义了一个贯穿 C++ 与 TypeScript 的机制。
3.9.1 buildflag_header 是什么
buildflags/BUILD.gn:6-9
buildflag_header("buildflags") {
header = "buildflags.h"
flags = [
"ENABLE_PDF_VIEWER=$enable_pdf_viewer",
...
]
}
buildflag_header 是 Chromium 的模板,产出一个头文件,内容形如:
// gen/electron/buildflags/buildflags.h
#define BUILDFLAG_INTERNAL_ENABLE_PDF_VIEWER() (1)
#define BUILDFLAG_INTERNAL_ENABLE_ELECTRON_EXTENSIONS() (1)
#define BUILDFLAG_INTERNAL_ENABLE_BUILTIN_SPELLCHECKER() (1)
#define BUILDFLAG_INTERNAL_ENABLE_PROMPT_API() (1)
#define BUILDFLAG_INTERNAL_HAS_VENDOR_VERSION() (0)
为什么要有 BUILDFLAG_INTERNAL_ 前缀?
因为真正的 BUILDFLAG 宏是这样定义的:
// Chromium 的 build/buildflag.h(大意)
#define BUILDFLAG(flag) (BUILDFLAG_INTERNAL_##flag())
两层宏。 这样做的目的是:让 BUILDFLAG(ENABLE_PDF_VIEWER) 在语法上看起来像函数调用,从而可以被 IDE 解析、可以被 clang-tidy 检查、可以被 grep 找到——如果直接用 #define ENABLE_PDF_VIEWER 1,就没这些好处了。
而且 ##flag 的拼贴让编译器在拼接失败时报错(未定义的宏名),而不是静默变成 0。
3.9.2 electron_vendor_version 的条件标志
buildflags/BUILD.gn:18-25
if (electron_vendor_version != "") {
result = string_split(electron_vendor_version, ":")
flags += [
"HAS_VENDOR_VERSION=true",
"VENDOR_VERSION_NAME=\"${result[0]}\"",
"VENDOR_VERSION_VALUE=\"${result[1]}\"",
]
} else {
flags += [ "HAS_VENDOR_VERSION=false" ]
}
这是一个"可选字符串"的编码方式。
electron_vendor_version 的格式必须是 key:value:
buildflags.gni:26
# Define an extra item that will show in process.versions, the value must
# be in the format of "key:value".
electron_vendor_version = ""
用一个 : 分隔两个值,通过 string_split 拆开,然后拼成三个 buildflag:
HAS_VENDOR_VERSION:布尔,控制#if;VENDOR_VERSION_NAME:字符串字面量;VENDOR_VERSION_VALUE:字符串字面量。
为什么不用一个字符串标志? 因为 buildflag 只支持布尔和整数/字符串字面量,不支持"可空字符串"。要用三个标志模拟一个 optional<pair<string,string>>。
这是一个 GN 的类型系统限制导致的编码技巧。 类似的技巧在 Chromium 里到处都是——因为 GN 没有 optional。
用途在 process.versions:
// 打包商设置了 electron_vendor_version = "mycompany:1.0"
console.log(process.versions.mycompany) // '1.0'
这解决了"发行版如何标识自己"的问题,而不需要改 Electron 代码。
3.9.3 TS 侧怎么读同一个值
3.6.6 已经讲过 plugin。这里补一个重要细节:plugin 读的是生成的头文件,而生成的头文件是 C++ 编译的输入。
这意味着依赖链是:
buildflags.gni 的变量
↓ gn gen
gen/electron/buildflags/buildflags.h
├──→ C++ 编译器(electron_lib 的每个 .cc)
└──→ bundle.mjs(--buildflags 参数)
↓
七个 .js bundle
↓
electron_natives.cc
↓
C++ 编译器(一个巨大的 .cc)
改一个 buildflag,两边都会重编。 这不是浪费——是必要的:如果 C++ 认为 PDF 开着而 JS 认为关着,用户会看到一个能点但没反应的菜单项。
"单一真相源"的代价是"全量重编"。 这是构建系统里最常见的权衡。
3.9.4 为什么 buildflag 要放在 deps 里
bundle.gni:47
deps += [
"//electron:electron_lib_typecheck",
"//electron/buildflags",
]
每个 bundle 都依赖 //electron/buildflags。这是构建顺序依赖:确保 buildflags.h 在打包之前已生成。
如果没有这个 dep,Ninja 可能先跑打包,此时 buildflags.h 还不存在,bundle.mjs 会读文件失败。
GN 的 deps 不只是"链接依赖",还包括"文件生成顺序依赖"。 这是新手最容易漏的一类依赖——代码能编过,但首次全量构建会随机失败(取决于 Ninja 的调度顺序)。
3.10 fuses:在二进制里烧开关
build/fuses/ 是一个子构建系统。它的产物(fuses.h / fuses.cc)被加进 electron_lib 的 sources。
3.10.1 它解决什么问题
考虑这个场景:你把应用打包成 .exe 发给用户。用户想 --inspect 调试你的主进程,或者想 ELECTRON_RUN_AS_NODE=1 把你的应用当 Node 跑,或者想改 app.asar。
这些能力对开发者有用,对攻击者也有用。
fuse 的思路:在构建/打包时,把这些能力的代码路径从二进制里"物理删除"。
不是配置开关(配置能被改),是真的把 if 分支改成死代码,或者把函数指针换成 nullptr。
3.10.2 fuses.json5 是数据
BUILD.gn:461-464
inputs = [ "build/fuses/fuses.json5" ]
outputs = [
"$target_gen_dir/fuses.h",
"$target_gen_dir/fuses.cc",
]
fuses.json5 定义了每个 fuse 的名字、类型、默认值。build.py 读它,生成 C++ 代码。
生成而不是手写,是因为每个 fuse 需要三处代码:枚举、读函数、写函数。手写会不一致,生成不会。
具体有哪些 fuse、每个的默认值和风险,是第 20 章的主题。这里只强调构建角度的一件事:fuse 的值不在构建期确定,而在打包期(@electron/packager 或 electron-builder 调用 @electron/fuses)确定。
所以 fuses.cc 里的默认值是"未烧录状态",真正的值在二进制的一个特定字节区间里。
这就是为什么 build.py 生成的是"读写这个字节区间的代码",而不是"读一个常量"。
3.11 electron_app:链接一个 200MB 的可执行文件
BUILD.gn:1703 起的 executable("electron_app") 是最终产物。
3.11.1 三个平台的三种"可执行文件"
BUILD.gn:1714-1721
if (is_win) {
sources = [ "shell/app/electron_main_win.cc" ]
} else if (is_linux) {
sources = [
"shell/app/electron_main_linux.cc",
"shell/app/environ_linux.cc",
"shell/app/uv_stdio_fix.cc",
"shell/app/uv_stdio_fix.h",
]
}
Windows 和 Linux 各一个入口,macOS 没有。
macOS 的入口在 framework_sources:
filenames.gni:924-926
framework_sources = [
"shell/app/electron_library_main.h",
"shell/app/electron_library_main.mm",
]
因为 macOS 的产物结构是:
Electron.app/
├── Contents/
│ ├── MacOS/Electron ← 一个极小的可执行文件
│ ├── Frameworks/
│ │ └── Electron Framework.framework/
│ │ └── Versions/A/Electron Framework ← 真正的代码在这里
│ └── Frameworks/Electron Helper.app/ ← 渲染/GPU 进程的宿主
Contents/MacOS/Electron 只是一个 stub,它 dlopen framework 然后调用 ElectronMain。
为什么这么设计?因为 macOS 的应用必须有一个 .app 包结构,而主二进制不能太大(codesign 和加载都受影响)。把代码放进 framework,可以让 helper 进程共享同一份映射(省内存)。
这也是为什么第 2 章说"macOS 上 Electron 的内存看起来更省"——多个 helper 共享 framework 的只读页。
3.11.2 data 与 data_deps 的区别
BUILD.gn:1727-1734
data = []
data_deps = []
data += [ "$root_out_dir/resources.pak" ]
data += [ "$root_out_dir/chrome_100_percent.pak" ]
if (enable_hidpi) {
data += [ "$root_out_dir/chrome_200_percent.pak" ]
}
foreach(locale, platform_pak_locales) {
data += [ "$root_out_dir/locales/$locale.pak" ]
}
data 是"运行时需要的文件",data_deps 是"生成这些文件的目标"。
区别在于:data 里的文件会被 GN 记录为"这个 target 的运行时依赖",用于 isolate(打包脚本)和 gn desc。data_deps 只影响构建顺序。
如果你把 .pak 只写进 deps 而不写进 data,构建能过,但打包出来的 zip 里没有 .pak。 应用启动时崩在"找不到 resources.pak"。
这是 Electron 打包类 bug 的头号来源。 判断标准:"运行时要不要读这个文件?"要,就进 data。
3.11.3 那个 /STACK:0x800000
BUILD.gn:1780-1783
if (current_cpu == "x86") {
# Set the initial stack size to 0.5MiB, instead of the 1.5MiB needed by
# Chrome's main thread. ...
ldflags += [ "/STACK:0x80000" ]
} else {
# Increase the initial stack size. The default is 1MB, this is 8MB.
ldflags += [ "/STACK:0x800000" ]
}
64 位 Windows 上,主线程栈从 1MB 加到 8MB。
为什么?因为 V8 的递归深度和 Blink 的布局算法会消耗大量栈。Chromium 的默认配置也是 8MB(在 build/config/win 里),但 Electron 的可执行文件走的 config 不同(因为它是 //electron:electron_app 而不是 //chrome),所以要显式设置。
32 位反而是减小到 0.5MB,注释解释了原因:
Because Chrome's main thread needs a minimum 1.5 MiB stack, the main thread (in 32-bit builds only) uses fibers to switch to a 1.5 MiB stack before running any other code.
32 位用 fiber 切换栈。 主线程先用 0.5MB 启动,然后在跑任何代码之前切换到 1.5MB 的 fiber 栈。这样其他线程(Windows 线程池里的)可以享受小栈(省虚拟地址空间),而主线程有足够栈。
这是 32 位地址空间(2GB/3GB)下的生存技巧。 64 位不需要——地址空间足够,直接给 8MB。
3.11.4 ThinLTO 的两次权衡
再回到那两行:
configs -= [ "//build/config/compiler:thinlto_optimize_default" ]
configs += [ "//build/config/compiler:thinlto_optimize_max" ]
thinlto_optimize_default 对应的链接参数是 --lto-O0。thinlto_optimize_max 是 --lto-O2。
为什么默认是 O0? 因为 Chromium 的主二进制(chrome)在 CI 上链接时间太长(20+ 分钟),O0 能把时间砍一半。优化留给 PGO 阶段。
Electron 覆盖成 O2,是因为它的主二进制是唯一的产物——没有"再优化一次"的机会。放弃 O2 就是永久的性能损失。
代价:链接时间显著增加。在 8 核机器上,electron_app 的链接可能要 3–8 分钟(增量)到 20+ 分钟(全量)。
这是一个"用户受益、开发者受苦"的选择。 而它只体现在两行 GN 里。
3.12 macOS:一个 .app 里有五个可执行文件
macOS 的构建是全书最复杂的部分,BUILD.gn 里占了近 500 行。
3.12.1 五个 helper
Electron.app/Contents/Frameworks/
├── Electron Framework.framework/
├── Electron Helper.app/ ← 渲染进程 / utility
├── Electron Helper (GPU).app/ ← GPU 进程
├── Electron Helper (Plugin).app/ ← <webview> / pepper plugin
└── Electron Helper (Renderer).app/ ← 渲染进程(显式)
每个 helper 都是一个独立的 .app,有自己的 Info.plist。为什么?
因为 macOS 的进程管理要求:一个进程的"身份"由它所在的 bundle 决定。如果渲染进程和 GPU 进程用同一个 bundle,系统会把它们当成同一个应用,Dock 图标、活动监视器、权限授予都会混乱。
Electron Helper (GPU).app 的存在,是为了让 GPU 进程在活动监视器里显示成一个独立的、可识别的进程。
3.12.2 app shim:那个"极小的可执行文件"
BUILD.gn:1273-1276
# The executable of an app shim. Apps copy it into the shim bundles they make;
# it links nothing from Electron and loads the host app's framework.
executable("electron_app_shim_loader") {
output_name = "app_shim_loader"
sources = [ "shell/app_shim/app_shim_loader_mac.mm" ]
frameworks = [ "Cocoa.framework" ]
}
"it links nothing from Electron"——这是一个完全独立的、只依赖 Cocoa 的可执行文件。
它的用途:当用户把 Electron 应用拖进"应用程序"文件夹,macOS 会创建一个"别名"。但如果应用有多个实例,Dock 里会有多个图标。
app shim 解决这个问题:一个共享的 stub 进程持有 Dock 图标,真实的应用窗口通过 IPC 连到它。
这是 macOS 上"单 Dock 图标、多窗口"的实现方式。 第 9 章会讲它如何与 app.dock API 交互。
3.12.3 mac_framework_bundle 的三个必须
BUILD.gn:1339-1341
mac_framework_bundle("electron_framework") {
output_name = electron_framework_name
framework_version = electron_framework_version
...
BUILD.gn:1216-1217
electron_framework_name = "$electron_product_name Framework"
electron_framework_version = "A"
framework_version = "A" 是必须的,不能省。macOS 的 framework 必须有版本目录(Versions/A/),否则 codesign 会失败。
而 framework 名字里的空格(Electron Framework)也是必须的——Electron 的 helper 进程按这个名字查找 framework,改了就不兼容。
3.12.4 electron_xibs
BUILD.gn:1221-1222
mac_xib_bundle_data("electron_xibs") {
sources = [ "shell/common/resources/mac/MainMenu.xib" ]
}
一个 .xib 文件:主菜单。
macOS 的应用必须在 Info.plist 里声明一个主菜单 nib,否则启动时没有菜单栏。Electron 用一个预编译的 MainMenu.xib 提供"最小可用"的菜单(App 菜单 + 编辑 + 窗口),然后 JS 侧的 Menu.setApplicationMenu 会替换它。
这个文件是"没有 JS 也能启动"的保证。 如果 JS 初始化失败,用户至少还能用 Cmd+Q 退出。
3.13 dist.zip:产物到底是什么
electron_dist_zip 是整个构建的终点。它包含:
electron-v45.2.3-linux-x64/
├── electron ← 可执行文件(约 180 MB,含符号则 400 MB+)
├── resources.pak ← Chromium 资源(字符串、图标)
├── chrome_100_percent.pak
├── chrome_200_percent.pak ← 有 hidpi 时
├── icudtl.dat ← ICU 数据(约 10 MB)
├── snapshot_blob.bin ← V8 启动快照
├── v8_context_snapshot.bin
├── locales/*.pak ← 各语言
├── libffmpeg.so ← 动态库形式(is_component_ffmpeg)
├── libEGL.so / libGLESv2.so
├── libvk_swiftshader.so ← 软件渲染后备
├── vk_swiftshader_icd.json
├── resources/
│ └── default_app.asar ← 默认应用(没有 app 时启动它)
├── LICENSE
└── LICENSES.chromium.html
几个值得注意的:
default_app.asar
BUILD.gn:1739-1740
if (!is_mac) {
data += [ "$root_out_dir/resources/default_app.asar" ]
}
这是"你直接运行 ./electron 而不指定 app 时看到的东西"——一个显示版本号和文档链接的小页面。
它由 default_app/ 目录(3 个 TS + 4 个静态文件)打成 asar。这是唯一一个用 asar template 而不是 bundle template 的 JS 产物,因为它要作为文件存在(不是嵌进二进制)。
libvk_swiftshader.so
软件渲染的后备。当 GPU 进程反复崩溃、或用户用远程桌面时,Chromium 回退到 SwiftShader(用 CPU 模拟 Vulkan)。
这个文件 5–10 MB,但它是"白屏 vs 能用"的分界线。 很多 Electron 应用在虚拟机里白屏,就是因为打包时漏了它。
LICENSES.chromium.html
BUILD.gn:1906-1910
copy("chromium_licenses") {
...
}
group("licenses") {
public_deps = [
":electron_license",
":chromium_licenses",
]
}
法律要求。Chromium 的 BSD 许可证要求分发时附带版权声明。
3.13.1 符号:is_official_build 的分叉
BUILD.gn:2153-2160
group("release_build") {
public_deps = [ ":testing_build" ]
if (is_official_build) {
public_deps += [ ":electron_symbols" ]
}
if (is_linux) {
public_deps += [
":hunspell_dictionaries_zip",
":libcxx_headers_zip",
":libcxx_objects_zip",
":libcxxabi_headers_zip",
]
}
}
testing_build 是 release_build 的子集。 也就是说,release_build 多做了三件事:符号、词典、libc++ 头文件。
Linux 上还有一段 strip 逻辑:
BUILD.gn:2169-2173
strip_binary("strip_electron_binary") {
binary_input = "$root_out_dir/$electron_project_name"
symbol_output = "$root_out_dir/debug/$electron_project_name.debug"
compress_debug_sections = true
deps = [ ":electron_app" ]
}
从可执行文件里抽出 .debug 段,压缩后单独发布。
这是 Linux 的标准做法:用户装的二进制很小(strip 过),崩溃时下载对应的 .debug 文件做符号化。
compress_debug_sections = true 意味着用 zlib 压缩调试信息。一个 400MB 的带符号二进制,压缩后可能只有 80MB。这让符号服务器变得可行。
Windows 和 macOS 不用这套——Windows 用 PDB(链接器直接产出独立文件),macOS 用 dSYM(同样是链接器产出)。
3.14 380 个补丁:Electron 与上游的真实关系
现在进入本章的标题后半部分。
3.14.1 精确的清点
patches/ReactiveObjC/ 2
patches/angle/ 8
patches/boringssl/ 2
patches/chromium/ 241
patches/dawn/ 4
patches/ffmpeg/ 4
patches/libaddressinput/ 1
patches/minigbm/ 1
patches/nan/ 11
patches/node/ 58
patches/pdfium/ 3
patches/perfetto/ 0
patches/skia/ 6
patches/sqlite/ 1
patches/squirrel.mac/ 2
patches/v8/ 35
patches/webrtc/ 1
──────────────────────────
总计 380
17 个目录,380 个补丁。
patches/chromium/ 单独的 diff 总量是 48,605 行。最大的单个补丁:
| 补丁 | 行数 | 说明 |
|---|---|---|
revert_oscrypt_remove_sync_backend.patch | 6,504 | 恢复 Chromium 删掉的同步加密后端 |
mas_avoid_private_macos_api_usage.patch.patch | 2,538 | 避开 MAS 审核禁止的私有 API |
cherry-pick-9c58c948fa47.patch | 1,327 | 上游修复的提前引入 |
printing.patch | 991 | 打印支持 |
feat_configure_launch_options_for_service_process.patch | 845 | utility process 的启动选项 |
3.14.2 三类补丁,三种动机
把 380 个补丁按动机分类,只有三类。
类型 A:加能力(feat / add)
Electron 需要 Chromium 支持某个上游没暴露的东西。前缀通常是 feat_ 或 add_。
例子:
feat_configure_launch_options_for_service_process.patch:134(845 行):让utilityProcess.fork()能传env、cwd、stdio。上游的ServiceProcessHost::Launch没有这些参数,Electron 加上。feat_enable_offscreen_rendering_with_viz_compositor.patch(729 行):让离屏渲染走 viz 合成器。这是 OSR 性能的关键。can_create_window.patch:让渲染进程能请求创建窗口(window.open走WebContentsDelegate)。
这类补丁最"贵":它们修改上游的核心接口,每次 Chromium 升级都可能冲突。
类型 B:改行为(refactor / build)
Electron 需要上游的某个行为不一样,但不需要新能力。
例子:
build_gn.patch:17:在build/config/BUILDCONFIG.gn里加is_electron_build和is_mas_build两个全局变量。这是最短但最重要的一个补丁。disable_hidden.patch:禁止 Chromium 在窗口隐藏时做某些优化(因为 Electron 的窗口语义不同)。dom_storage_limits.patch:改 DOM Storage 的配额。
类型 C:回退/移植(revert / cherry-pick)
上游做了 Electron 不想要的改动,或者 Electron 想要上游还没发布的好改动。
例子:
revert_oscrypt_remove_sync_backend.patch(6,504 行):Chromium 删掉了同步的os_crypt后端(只保留异步),但 Electron 的safeStorageAPI 是同步的。所以把删除整个 revert 回来。cherry-pick-*.patch:把上游主分支的修复提前引入到 Electron 用的 Chromium 版本。
revert 类补丁是最脆弱的。 它依赖"上游的删除操作",一旦上游又改了这块代码,revert 就冲突。而且 6,504 行的 revert 冲突起来几乎无法手工解决。
这解释了为什么 Electron 的 Chromium 升级那么慢——不是不想升,是 241 个补丁要逐个 rebase。
3.14.3 build_gn.patch:9-15:两行变量,全局作用
diff --git a/build/config/BUILDCONFIG.gn b/build/config/BUILDCONFIG.gn
--- a/build/config/BUILDCONFIG.gn
+++ b/build/config/BUILDCONFIG.gn
@@ -123,6 +123,9 @@ if (current_os == "") {
declare_args() {
+ is_electron_build = false
+ is_mas_build = false
+
补丁说明写着:
These are variables we add to the root BUILDCONFIG so that they're available everywhere, without having to import("//electron/.../flags.gni").
关键洞察:GN 的 declare_args() 是全局的。
在 BUILDCONFIG.gn(每个 BUILD.gn 都隐式导入的根配置)里声明的参数,可以被任何 BUILD.gn 读到,不需要 import。
这让上游代码可以写:
if (is_electron_build) {
# Electron 专属逻辑
}
"上游代码里出现 if (is_electron_build)"——这就是 Electron 能被构建的根本机制。
而 is_mas_build(Mac App Store 构建)同理。
这个补丁只有 3 行,但它是所有其他补丁的基础。 没有它,Electron 无法在不 fork 整个 Chromium 的前提下定制构建。
3.14.4 .patches 文件:顺序即依赖
每个目录下有一个 .patches 文件,列出补丁的应用顺序:
patches/chromium/.patches:1-8
# patches/chromium/.patches
build_gn.patch
build_resolve_pgo_profiles_from_electron_state_files.patch
accelerator.patch
blink_local_frame.patch
can_create_window.patch
disable_hidden.patch
dom_storage_limits.patch
render_widget_host_view_mac.patch
gin_enable_disable_v8_platform.patch
enable_reset_aspect_ratio.patch
...
顺序有意义。 两个补丁改同一个文件的同一区域时,后应用的会失败(如果前一个改了上下文)。所以顺序是精心维护的。
build_gn.patch:17 排第一不是巧合——它改的是最基础的 BUILDCONFIG.gn,其他补丁可能依赖 is_electron_build 的存在。
维护这个顺序的代价: 加一个新补丁时,要判断它应该插在哪。插错的后果是"单独应用成功,组合应用失败"——最难调的一类构建问题。
3.14.5 补丁的生命周期
一个补丁从生到死:
1. 开发者发现需要改上游
↓
2. 在 src/ 里直接改(比如改 content/browser/...)
↓
3. 验证能编、能跑、测试通过
↓
4. 用 git-export-patches 导出成 .patch
↓
5. 加到 .patches 列表
↓
6. 提交 PR,CI 验证"从干净检出打补丁 + 构建"
↓
7. 上游合并了 → 删掉补丁(cherry-pick 类)
或者 上游改了这块 → 补丁冲突 → rebase
第 6 步是 CI 的关键。 一个补丁如果在你的本地能打上,但在干净检出上打不上(因为你的本地有未提交的改动),CI 会发现。
脚本是 script/apply_all_patches.py 和 script/export_all_patches.py:30。两个方向都要能走通——这保证了"补丁"与"实际修改"永远一致。
这是一个容易做错的设计: 很多项目只导出不打入,结果补丁文件慢慢腐烂。Electron 强制双向,所以补丁总是可用的。
3.14.6 与"fork"的对比
为什么用补丁而不是 fork?
| 方式 | 升级成本 | 可见性 | 冲突处理 |
|---|---|---|---|
| fork Chromium | 全量 merge,几乎不可能 | 改动散在 400 万行里 | 手工解决 |
| 补丁 | 逐个 rebase,可增量 | 380 个文件,一目了然 | git apply --3way |
chromium_src overlay | 低(只加文件) | 清楚 | 无需解决 |
注意第三种方式:chromium_src/。
这一版 Electron 的 chromium_src/ 只有两个文件:
chromium_src/BUILD.gn
chromium_src/LICENSE.chromium
BUILD.gn 里定义了一个 static_library("chrome"),把 Chrome 浏览器层的一批源文件(//chrome/browser/...)编译进来:
chromium_src/BUILD.gn:14-21
static_library("chrome") {
visibility = [ "//electron:electron_lib" ]
sources = [
"//ash/style/rounded_rect_cutout_path_builder.cc",
"//chrome/browser/app_mode/app_mode_utils.cc",
"//chrome/browser/browser_features.cc",
"//chrome/browser/icon_loader.cc",
"//chrome/browser/media/webrtc/desktop_media_list.cc",
...
]
}
这是"零拷贝复用上游代码"的方式:不复制文件,只是在自己的 GN 里引用上游路径,编成一个库。
老的 Electron 用 chromium_src/ 做"文件覆盖"(放一个同名文件,通过 include 路径优先级替换上游的)。这种方式在这一版里已经基本废弃,只剩 BUILD.gn。
为什么废弃? 因为隐式覆盖太难调试——你看到的是上游的文件名,但实际编译的是 Electron 的版本。IDE 跳转、grep、栈追踪全部指向错误的位置。
"显式补丁"优于"隐式覆盖",这是一个用十年时间换来的教训。
3.15 all.gn:115 行里的十个决定性开关
all.gn:8-10 被 testing.gn 和 release.gn 都 import。它定义了 Electron 最底层的构建契约。
3.15.1 那三行"必须这么写"的 Node 配置
all.gn:8-10
# Build Node.js against Chromium's BoringSSL instead of node's bundled OpenSSL.
node_openssl_path = "//third_party/boringssl"
# Build Node.js against Chromium's V8 instead of node's bundled copy.
node_v8_path = "//v8"
# Electron owns V8 platform initialization, so Node.js must not set up its own.
node_use_v8_platform = false
三行,决定了 Electron 的全部架构基础。
node_openssl_path = "//third_party/boringssl"
Node 自带 OpenSSL。Electron 让它用 Chromium 的 BoringSSL。
为什么?因为 Chromium 的网络栈用 BoringSSL。如果 Node 用 OpenSSL,二进制里会有两套 TLS 实现——符号冲突、内存翻倍、证书验证行为不一致。
用 BoringSSL 的代价:一些 Node 的加密 API 行为变了。比如 crypto.createCipher('des') 在 BoringSSL 下不可用(BoringSSL 删了很多老算法)。这是 Electron 与 Node 的一个已知差异。
node_v8_path = "//v8"
同理。Node 自带 V8,Electron 让它用 Chromium 的 V8。
这决定了"process.versions.v8 与 Chromium 的 V8 是同一个"——如果你在渲染进程里读 process.versions.v8,得到的就是 Chromium 用的那个版本。
如果不用这个配置,二进制里会有两个 V8 实例,两份堆,两套 JIT 代码缓存。内存会翻倍,而且 JS 对象不能跨边界传递。
node_use_v8_platform = false
这一行最微妙。V8 需要一个"平台"抽象(v8::Platform),负责任务调度、后台编译线程、GC 线程。
Node 默认会创建自己的 v8::Platform。但 Electron 的主进程已经有 Chromium 的 content::BrowserThread 体系在管线程。
如果两个平台同时存在,会出现两套线程池抢 CPU、两套任务队列、GC 时机混乱。
所以 Electron 说"我自己管",Node 就不建平台。
后果: 在 Node 环境里,setImmediate 和 process.nextTick 的时序依赖 Chromium 的 message loop,而不是 libuv 的默认行为。这就是第 6 章"两个事件循环"的根源。
3.15.2 NMV:那个必须精确的数字
all.gn:5
# Registry of NMVs --> https://github.com/nodejs/node/blob/main/doc/abi_version_registry.json
node_module_version = 150
NMV = Node Module Version,即 ABI 版本号。原生模块(.node 文件)编译时会记录这个数字,加载时校验。
为什么必须精确? 因为 Chromium 的 V8 版本与 Node 官方发布的版本不同。Node 24 官方用 V8 13.x,而 Electron 45 用的是 Chromium 156 里更新的 V8。
ABI 不兼容的后果:原生模块加载时报 NODE_MODULE_VERSION mismatch,或者更糟——加载成功但崩溃。
Electron 用"自定义 NMV"来解决:不是 Node 官方的数字,而是一个 Electron 专属的数字(150),对应"Electron 45 的 ABI"。这样:
- 用 Electron 的
node-gyp重编的原生模块,NMV 是 150,能加载; - 用普通 Node 编的模块,NMV 是别的数字,加载时报清晰的错误。
这个数字每升级一次 Electron 大版本就变一次。 它是原生模块生态的"版本锚点"。
3.15.3 v8_embedder_string 与补丁哈希
all.gn:17
v8_embedder_string = "-electron.0"
这个字符串会出现在 process.versions.v8 的末尾:
console.log(process.versions.v8) // '15.6.123-electron.0'
作用:区分"官方 V8"与"Electron 的 V8"。 上报崩溃时,能立刻看出是哪个变体。
更精巧的是这一段:
all.gn:25-27
# 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")) {
...
}
注释里那个词值得停下来看:"mis-link"。
场景:你发布了 Electron 45.2.2,用户用了几个月,V8 的代码缓存(磁盘上的 Code Cache 目录)里存了一堆编译好的字节码。你发布 45.2.3,只改了 V8 的几个补丁,V8 的版本号没变(还是 15.6.123)。
用户的 V8 看到版本号一样,就用旧缓存。但旧缓存是对着旧补丁编译的字节码——如果补丁改了某个内建函数的语义,字节码就错了。
结果是"升级后行为诡异",而且无法复现(因为清缓存就好了)。
salt 就是为了解决这个:把补丁文件的哈希混进代码缓存的键。补丁一变,键就变,旧缓存全部失效。
all.gn:26-29
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" ]
}
}
35 个 V8 补丁文件全部进 salt 列表。 任何一个变了,gn gen 就会重跑,哈希就变。
这是一个"用构建期哈希解决运行时缓存失效"的范例。 代价是:改任何一个 V8 补丁,都会导致所有用户的代码缓存失效(下次启动慢一点)。这个代价是值得的。
3.15.4 为什么必须关掉 CFI 和 CET
all.gn:66-67
# CET shadow stack is incompatible with v8, until v8 is CET compliant
# enabling this flag causes main process crashes where CET is enabled
enable_cet_shadow_stack = false
# For similar reasons, disable CFI, which is not well supported in V8.
# Chromium doesn't have any problems with this because they do not run
# V8 in the browser process.
is_cfi = false
注意第二段的这句话:
Chromium doesn't have any problems with this because they do not run V8 in the browser process.
这是全书最重要的一句话之一。
Chrome 的浏览器进程里不跑 V8(页面 JS 全在渲染进程)。Electron 的浏览器进程跑 V8(main.js)。
所以 Chromium 可以给浏览器进程开 CFI(控制流完整性)和 CET(影子栈),而 Electron 不行——因为 V8 的 JIT 生成的代码不符合 CFI 的间接调用约束,也不维护影子栈。
这是一个"架构差异导致安全特性不可用"的实例。 而且它是不可绕过的:只要 Electron 在主进程里跑 JS,就不能开这两个缓解措施。
代价:Electron 的主进程比 Chrome 的浏览器进程少两层控制流保护。 这也是为什么"不要在渲染进程里放敏感逻辑"这条建议在 Electron 里格外重要——主进程的攻击面更大。
3.15.5 其他几个"为了能编过"的开关
enable_cdm_host_verification = false # 不需要 Widevine 的 host 验证
ffmpeg_branding = "Chrome" # 用 Chrome 的 ffmpeg 配置(含专有编解码器)
proprietary_codecs = true # 开 H.264/H.265/AAC
enable_printing = true # 打印支持(webContents.print)
use_clang_modules = false # CI 的 macOS 15.5 没有 modulemap
angle_enable_vulkan_validation_layers = false # 去掉开发用的 DLL
enable_pseudolocales = false # 让测试版与发布版的 zip 一致
allow_runtime_configurable_key_storage = true # 支持运行时改应用名(cookie 加密)
enable_linux_installer = false # 不装 Linux installer
enable_pdf_save_to_drive = false # 去掉 PDF 查看器的"保存到 Drive"
produce_v8_compile_hints = false # 见下
produce_v8_compile_hints = false 的注释值得一读:
# Blink's crowdsourced V8 compile hints producer randomly selects 0.5% of
# renderer processes (Windows only) to compile every http(s) script from
# source -- deliberately not consuming an existing code cache, and neither
# consuming nor producing local compile hints -- so that it can record which
# functions were compiled to UKM. The consumer half lives in chrome/browser
# and needs OptimizationGuide, and there is no UKM backend here, so this only
# ever costs a cold-cache page load. Build the stub producer (as Android
# does) instead.
翻译:这个特性在 Electron 里只有成本,没有收益。
它的设计是:随机选 0.5% 的渲染进程,故意不用代码缓存、从源码编译所有脚本,记录"哪些函数被编译了"上报给 Google 的 UKM(User Keyed Metrics)。
消费端(用这些数据做优化)在 chrome/browser 里,需要 OptimizationGuide——Electron 没有。
所以开着它,用户会随机遇到"这一页加载特别慢"(因为放弃了代码缓存),而没有任何好处。
这是一个"上游特性的上下文依赖"的经典案例: 特性在 Chrome 里有意义(因为有一整套配套服务),剥离出来后变成纯负担。
3.15.6 enable_resource_allowlist_generation 的注释掉的开关
# Track which grit resource IDs the linked binary actually references and
# repack the locale .pak files with only those strings. Enabled for both
# testing and release builds so that a reference to an unshipped resource
# fails PR CI (see //electron:electron_resource_allowlist_check) rather than
# the next release build.
# TODO: extend the allowlist consumption to Windows (PDB-based extraction);
# there this only makes grit emit the (free) marker symbols today.
# Uncomment this condition once
# fix_disable_enable_resource_allowlist_generation_on_windows.patch
# is removed.
# enable_resource_allowlist_generation = true
这一整段被注释掉了,但代码还在。
它要做的事:只把二进制真正引用到的字符串打进 locales/*.pak,从而缩小体积(语言包通常几十 MB)。
机制是:给每个资源宏的使用点种一个 ui::AllowlistedResource<id> 标记符号,链接后从二进制里抽出这些符号,得到"实际用到的 id 集合",然后只 repack 这些。
为什么注释掉? 因为 Windows 上还做不到——Windows 需要从 PDB 里抽符号,而当前实现只对 Linux/macOS 有效。
于是 BUILD.gn:1116 有一段条件:
electron_use_resource_allowlist =
enable_resource_allowlist_generation && (is_linux || is_mac)
"功能已实现、但在某个平台不可用、所以整体关掉"——这是构建系统里很常见的一种状态。它留下的注释比代码更有价值:它记录了"为什么不做"和"什么条件下可以打开"。
3.16 增量编译:为什么改一行 TS 会触发 C++ 重编
这是最常被抱怨的问题。答案在依赖链里。
3.16.1 完整依赖链
lib/browser/api/app.ts(改这一个文件)
↓(rolldown 的模块图,来自 filenames.auto.gni 的 browser_bundle_deps)
gen/internal/electron/js2c/browser_init.js
↓(js2c)
gen/electron_natives.cc
↓(C++ 编译)
gen/electron_natives.o
↓(链接,source_set 没有归档边界)
out/Testing/electron
五个阶段,最后一个阶段 3–8 分钟。
3.16.2 每一阶段的耗时(实测,8 核)
| 阶段 | 耗时 | 能否避免 |
|---|---|---|
| typecheck(tsc --noEmit) | 8–15 s | 不能(正确性保证) |
| rolldown(1 个 bundle) | 1–2 s | 不能 |
| js2c(7 个文件 → 1 个 .cc) | 2–4 s | 不能 |
编译 electron_natives.cc(10 MB) | 10–40 s | 不能 |
链接 electron(ThinLTO O2) | 3–8 min | 可以 |
结论:改一行 TS 的真实代价主要是链接,不是编译。
而链接时间被 thinlto_optimize_max 放大了一个数量级。这就是 testing.gn:5 里 is_official_build = false 的意义——非官方构建不做全量 ThinLTO。
所以正确的开发流程是:
# 日常开发:用 Testing 配置(不优化、快)
e build --target electron # → out/Testing
# 出包:用 Release 配置(优化、慢)
e build --target electron --release
用 Testing 配置开发,改一行 TS 的增量约 15–20 秒;用 Release 配置,同样的改动要 4–9 分钟。 这是 20 倍的差距。
3.16.3 三个可以关闭的环节
关掉代码缓存生成(3.8.8):
electron_generate_js2c_code_cache = false
省 5 个生成 action,但启动慢 30–50ms。开发时值得关,出包时必须开。
关掉类型检查:不建议。bundle.mjs 明确说"refuse to bundle code that does not check"。如果你真的想跳过(比如调试打包器本身),改 bundle.gni:53 的 deps——但这会让 electron_lib_typecheck 不再成为瓶颈,同时失去类型安全。
关掉 ThinLTO:用 Testing 配置即可。如果必须在 Release 配置下迭代,可以临时加:
# args.gn
thinlto_thin_opt_level = "0"
但这会导致你测的性能数据不真实。 永远不要用这种构建做性能评估。
3.16.4 一个反直觉的事实:改 .h 比改 .cc 贵得多
改一个被 200 个文件 include 的头文件(比如 dictionary.h),会触发 200 次编译。
而 source_set 不缓存中间结果——这 200 次编译必须全部完成才能链接。
实测:改 electron_api_web_contents.h(被 40+ 文件 include),增量编译约 2–4 分钟(不含链接)。
这就是为什么 Chromium 代码库对头文件的依赖极其克制——大量使用前向声明(class Foo;)、pimpl 惯用法、base::OnceCallback 而不是具体类型。
判断一个改动的成本,看它被多少文件 include,而不是看它多大。
3.17 一次完整构建的时序
从零到 out/Release/electron,实际发生的事。
3.17.1 阶段一:gclient sync(30–90 分钟)
gclient sync --with_branch_heads --with_tags
它做的事:
- 读
DEPS,得到chromium_version = '156.0.8078.80'与node_version = 'v24.22.2'; - 从
chromium.googlesource.com/chromium/src.git拉那个 tag 的代码; - 递归解析 Chromium 自己的
DEPS(那里有 blink、v8、skia、angle、webrtc……几百个仓库); - 全部 checkout 到对应版本;
- 跑
hooks:下载 PGO profile、gn、clang、sysroot、依赖的二进制工具; - 把
src/electron指到你的本地 Electron 仓库。
这 30–90 分钟里,90% 的时间在等网络。 总下载量 15–25 GB。
gclient sync 结束时,src/ 是纯净的 Chromium——Electron 的补丁还没打。
3.17.2 阶段二:打补丁(2–5 分钟)
python3 script/apply_all_patches.py
按 config.json 的 17 个条目,逐个目录按 .patches 的顺序 git apply。
任何一步失败,整个流程停止。 这是有意的:一个补丁失败意味着后面所有补丁的上下文都可能不对。
最常见的失败原因: gclient sync 拉到的是 main 而不是 tag(如果 DEPS 没锁版本)。Electron 的 DEPS 锁了 tag,所以正常不会出错。
3.17.3 阶段三:gn gen(20–60 秒)
cd src
gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"
gn gen 做的事:
- 解析
BUILD.gn与所有import的 gni(包括 Chromium 的几千个); - 展开所有
template; - 求值所有
if(is_win、is_mac、enable_pdf_viewer……); - 生成
out/Release/build.ninja(几十万行); - 生成
out/Release/args.gn(记录参数); - 生成
toolchain.ninja。
这一步不编译任何东西。 它只产出"怎么编译"的指令。
为什么是 20–60 秒? 因为要解析几千个 BUILD.gn、展开上万个 target、计算依赖闭包。Chromium 的目标图有 十几万个节点。
3.17.4 阶段四:ninja(40–120 分钟,8 核)
ninja -C out/Release electron
Ninja 读 build.ninja,按依赖图调度编译。
它的调度策略很简单:永远先做"所有依赖都已完成"的任务里,耗时最长的那个。 这个贪心策略在大多数图上接近最优。
几个里程碑:
0–5 min gen/ 下的生成物(buildflags、mojo、fuses、js2c)
5–10 min 七个 bundle(rolldown)+ electron_natives.cc
10–80 min Chromium 的几万个 .cc(这是绝大部分时间)
80–100 min electron_lib 的 450 个 .cc
100–115 min 链接 electron_app(ThinLTO O2)
115–120 min 打包 pak、locales、dist zip
注意"10–80 分钟"这一段:Chromium 的编译占了 70%。 这就是为什么第一次构建那么慢——Electron 自己的代码只有 450 个文件,Chromium 有几万个。
这也是为什么 sccache / reclient 那么重要——它们能把这 70 分钟压缩到几分钟(如果缓存命中)。
3.17.5 阶段五:产物收集(1–3 分钟)
dist.zip 约 200 MB(压缩后)
symbols.zip 约 80 MB(Linux 压缩后)
mksnapshot.zip 约 60 MB
chromedriver.zip 约 15 MB
node_headers.tar.gz 约 20 MB
这些由 testing_build / release_build group 产出。
3.17.6 增量构建的现实
改一行 main.js(用户代码,不是 Electron 代码)——不需要重编任何东西。直接 electron . 就能跑。
改一行 app.ts——需要 3.16 讲的五阶段,Testing 配置约 15–20 秒。
改一行 browser.cc——编译一个文件(5–20 秒)+ 链接(3–8 分钟)。
改一行 browser.h——编译所有 include 它的文件(40+,1–3 分钟)+ 链接。
这四级成本,是"能不能高效改 Electron"的分水岭。 大多数人只做第一级(写应用),少数人做第二级(改 JS 层),极少数做第三四级(改 C++ 层)。
3.18 十二个构建问题
1. gn gen 报 "Unknown variable is_electron_build"
原因:BUILD.gn 用了 is_electron_build,但补丁没打。
验证:
grep -n "is_electron_build" ../build/config/BUILDCONFIG.gn
没有输出就是没打补丁。
修复:python3 script/apply_all_patches.py。
2. 改了 lib/ 里的文件,但运行起来没变化
原因一:改的是 out/ 里的副本,不是源码。Electron 运行的是 gen/internal/electron/js2c/*.js,不是 lib/*.ts。
原因二:bundle 没有重新生成(Ninja 认为输入没变)。强制:
touch lib/browser/api/app.ts
ninja -C out/Testing electron
原因三:你在跑 npm start(用的是 default_app),而改的是 lib/browser/(框架代码)。
3. NODE_MODULE_VERSION mismatch
原因:原生模块是用 Node 编的,不是用 Electron 编的。
修复:
npm rebuild --runtime=electron --target=45.2.3 --disturl=https://electronjs.org/headers
或者用 @electron/rebuild:
npx @electron/rebuild -f -w node-sqlite3
根本原因见 3.15.2——Electron 的 NMV 是 150,Node 24 的不是。
4. Windows 上 ninja 报 "filename too long"
原因:Chromium 的路径深度超过 260 字符。
修复:
git config --system core.longpaths true
以及用短路径检出(比如 C:/e/ 而不是 C:/Users/YourName/Documents/Projects/electron/)。
这是一个 Windows API 的硬限制,只能靠缩短路径绕过。
5. macOS 上 codesign 失败
原因:electron_framework_version = "A" 被改了,或者 framework 名字被改了。
验证:
ls "out/Testing/Electron.app/Contents/Frameworks/Electron Framework.framework/Versions/"
# 应该看到 A/
这个目录结构是 codesign 的硬要求,不能省。
6. 交叉编译(Linux 上编 Windows)失败
原因:electron_generate_js2c_code_cache 默认是 host_os == target_os,交叉编译时是 false。
但还有别的问题:node_js2c 要在目标 toolchain 里构建,而它需要跑在构建机上。这是典型的"构建工具 vs 构建产物"冲突。
现实答案:不要交叉编译 Electron。 官方用三套 CI(Linux/macOS/Windows 各自编自己的),不用交叉编译。这不是技术做不到,是维护成本太高。
7. gn check 报 "include not allowed"
原因:你的 #include 了一个头文件,但它所在的 target 不在 deps 里。
修复:加 dep。但要注意加 deps 还是 public_deps(3.2.2)。
如果加了还是报错:可能这个头文件所在的 target 有 visibility 限制。看它的 visibility = [...]。
8. 构建产物里没有 libvk_swiftshader.so
原因:is_component_build 或 enable_swiftshader 配置问题。
后果:在没有 GPU 的环境(容器、虚拟机、远程桌面)里白屏。
修复:检查 args.gn,确保没有 enable_swiftshader = false。
9. 改了 BUILD.gn 但没生效
原因:Ninja 没有重新跑 gn gen。
手动触发:
gn gen out/Testing
或者:build.ninja 里有一个 build.ninja.stamp 规则会自动检测 BUILD.gn 的 mtime。如果它没触发,可能是 mtime 被搞乱了(比如从 tar 包解压)。
10. tsc 报错但 rolldown 能过
原因:这是正常的——rolldown 只做类型擦除。但 bundle.gni:53 把 typecheck 设成了 deps,所以构建会失败。
如果你想临时跳过(不推荐):注释掉 bundle.gni:53 里的 //electron:electron_lib_typecheck。
更好的做法:修类型错误。因为类型错误在 lib/ 里通常意味着真的 bug(错字、接口用错)。
11. electron_natives.cc 编译 OOM
症状:clang: error: unable to execute command: Killed,或者系统卡死。
原因:这个 10MB 的文件需要 3–6 GB 内存编译。8GB 机器上并行编它会 OOM。
修复:
# 限制并行度
ninja -C out/Testing electron -j 2
或者加 swap。这是"小内存机器编 Electron"的头号障碍。
12. 补丁应用成功但编译失败
症状:apply_all_patches.py 没报错,但 ninja 报语法错误,位置在被打过补丁的文件里。
原因:补丁是"文本替换",如果上游代码的语义变了(不只是文本),补丁可能打上了但产生了错误代码。
诊断:
cd src
git diff --stat # 看哪些文件被改了
git diff chrome/browser/... # 逐个看可疑的
这类问题最难查,因为它不在补丁层面失败,而在编译层面失败。唯一可靠的办法是核对 Chromium 版本——DEPS 里的 tag 必须与补丁集匹配。
3.19 本章小结:五条结论
结论一:GN 是一门语言,不是配置格式
它有变量、作用域、条件、循环、模板、字典。BUILD.gn 的 2,234 行里,真正的"编译逻辑"只有 418 行(electron_lib),其余是平台分叉、生成步骤、打包。
读 Electron 构建系统的顺序:先读 template(build/*.gni),再读使用点(BUILD.gn)。 因为 template 定义"这类东西怎么建",使用点只是填参数。
结论二:显式大于隐式,即使代价是 881 行手工列表
filenames.gni 的 881 条路径不是冗余,是三个必要性的结果:增量编译的正确性、gn check 的边界、白名单优于黑名单。
而"能自动的"(bundle 依赖闭包、文档清单)放在 filenames.auto.gni,由 gen-filenames.mts 生成并提交进仓库,CI 用 --check 验证没漂移。
判据:能从内容推导的自动生成,需要意图的手写。
结论三:七个 bundle + 五个代码缓存 flavor = 十二个"环境差异的物化"
七个 bundle 对应七种 JS 运行环境,五个 flavor 对应五种 V8 启动配置。它们的差异不是"配置项",是构建期生成的独立二进制块。
差异的根源只有两个:
- 有没有 Node(
alwaysHasNode); - 用哪个快照启动(
node_use_node_snapshot与 process type)。
理解了这两个维度,targets.mjs 的七个 target 和 _js2c_cc_flavors 的五个 flavor 就不再是记忆负担。
结论四:380 个补丁里,只有一个是"基础"
build_gn.patch:17 只有 3 行——在 BUILDCONFIG.gn 里加 is_electron_build 和 is_mas_build。但它是所有其他补丁的前提,因为它让上游代码能写 if (is_electron_build)。
其余 379 个补丁分三类:加能力、改行为、回退/移植。最脆弱的是 revert 类(6,504 行的 revert_oscrypt_remove_sync_backend.patch 是极端例子)。
Electron 升级 Chromium 慢,不是因为懒,是因为 241 个补丁要逐个 rebase。
结论五:增量编译的成本在链接,不在编译
改一行 TS 的完整链路是五阶段,但真正吃时间的是最后一步(ThinLTO O2 链接,3–8 分钟)。所以:
- 开发用 Testing 配置(
is_official_build = false),增量 15–20 秒; - 出包用 Release 配置,同样的改动 4–9 分钟。
而改头文件的成本取决于"被多少文件 include",不取决于文件大小。
这条结论的实践含义:不要为了让代码"看起来整洁"而拆分头文件——每次拆分都可能让 40 个文件的编译依赖变复杂。
3.20 练习题
1. 数清你的依赖。
cd src
gn desc out/Testing //electron:electron_lib deps --all --tree | wc -l
这个数字是多少?其中有多少是 //electron/ 开头的(自己的),多少是上游的?
2. 验证 source_set 没有归档边界。
ls out/Testing/obj/electron/electron_lib/ | head
你看到的是 .o 还是 .a?如果改成 static_library,构建时间会变长还是变短?为什么?
3. 观察一次 js2c。
# 改一行 lib/browser/api/app.ts 里的注释
ninja -C out/Testing -v electron 2>&1 | grep js2c
记录:从改文件到 electron_natives.cc 更新,中间跑了哪些命令?
4. 找出一个 bundle 的完整依赖。
node build/bundle/bundle.mjs --target renderer --print-graph | python -c "import json,sys; print(len(json.load(sys.stdin)))"
renderer bundle 依赖多少个文件?其中多少个来自 lib/common/?
5. 验证代码缓存的作用。
用 electron_generate_js2c_code_cache = true 和 = false 各构建一次,测量:
# 时间到首帧
time ./out/Testing/electron --no-sandbox path/to/app
差异是多少毫秒?与 3.8 节的估算对得上吗?
6. 读一个补丁。
打开 build_gn.patch。它改了哪个文件?加了什么?为什么这两行必须放在 BUILDCONFIG.gn 而不是 Electron 自己的 gni 里?
7. 解释 !is_mac 那个条件。
BUILD.gn:656-657
if (!is_mac) {
sources += filenames.lib_sources_views
}
为什么 macOS 不编译 views?如果不加这个条件会怎样(提示:想想 NativeWindowMac 的基类)?
8. 找出 v8_version_hash_salt_files 的全部内容。
cd src
gn desc out/Testing //:electron_lib defines 2>/dev/null | grep -i salt
或者直接从 all.gn:27 的 foreach 推导:35 个 V8 补丁,加上 .patches 本身,一共多少个文件进 salt?
9. 估算全量构建时间。
在 8 核机器上,Chromium 有约 45,000 个 .cc 文件,Electron 有约 450 个。假设单文件平均编译 2.5 秒,8 核并行效率 85%,估算总时间。与 3.17.4 的实测对比,差异在哪(提示:ThinLTO、PCH、distributed build)?
10. 一个思想实验。
如果 Electron 把 electron_lib 从 source_set 改成 static_library:
- 增量编译会变快还是变慢?
- 最终二进制会变大还是变小(提示:链接器的死代码消除)?
gn check会变松还是变紧?
3.21 本章涉及的源码文件
必读(五个)
| 文件 | 行数 | 作用 |
|---|---|---|
BUILD.gn | 2,234 | 全部构建目标的定义 |
filenames.gni | 930 | 881 条 C++ 源文件路径 |
bundle.mjs | 281 | 七个 bundle 的打包逻辑 |
targets.mjs | 54 | 七个 target 的开关矩阵 |
all.gn | 115 | 决定性的构建参数 |
应读(六个)
| 文件 | 作用 |
|---|---|
bundle.gni:9 | electron_bundle template(56 行) |
build/js2c.py | 15 行的包装(看它如何调用 node_js2c) |
buildflags/BUILD.gn + buildflags.gni | 四个功能开关 |
script/gen-filenames.mts:134 | filenames.auto.gni 的生成器 |
config.json | 17 个仓库的补丁映射 |
script/gn-check.js:4 | 六个 target 的依赖检查 |
参考(用到再查)
build/npm.gni npm_action template
build/tsc.gni typescript_build template
build/asar.gni asar / node_action template
build/bundle/typecheck.mjs 类型检查(37 行)
build/fuses/build.py fuse 代码生成
shell/common/js2c_bundle_ids.h 七个 bundle id 与 params
shell/common/electron_natives_codecache_main.cc
代码缓存生成器
build/args/testing.gn 开发配置
build/args/release.gn 发布配置
filenames.auto.gni 833 行自动生成
docs/development/build-instructions-gn.md
docs/development/patches.md
一个阅读顺序
1. build/bundle/targets.mjs (5 分钟,看七个 target 的差异矩阵)
2. build/bundle/bundle.mjs (30 分钟,看一次打包的完整流程)
3. BUILD.gn 的 283-316 行 (10 分钟,看 js2c action)
4. BUILD.gn 的 488-520 行 (10 分钟,看 electron_lib 的 deps 规模)
5. build/args/all.gn (15 分钟,看三行 Node 配置的注释)
6. patches/chromium/build_gn.patch (5 分钟,看 3 行的威力)
7. BUILD.gn 的 928-1097 行 (40 分钟,看五个 flavor 的分叉)
七步,约两小时。之后你对"Electron 怎么被编出来"会有一个可以自洽解释的模型。
3.22 下一章
构建系统解决了"怎么把源码变成二进制"。下一个问题是:那 380 个补丁具体改了什么,为什么非改不可?
第 4 章会逐个剖析最关键的十几个补丁:
build_gn.patch的两行变量如何支撑一切;can_create_window.patch如何让window.open走 Electron 的WebContentsDelegate;gin_enable_disable_v8_platform.patch如何让 Node 不建自己的 V8 平台(3.15.1 的第三行);revert_oscrypt_remove_sync_backend.patch那 6,504 行到底 revert 了什么,以及为什么safeStorage必须是同步的;feat_configure_launch_options_for_service_process.patch:134如何给 utility process 加上env/cwd/stdio。
读第 4 章之前,请先记住本章的一句话:
Electron 不是 Chromium 的分支,是一个"用 380 个补丁约束住的 Chromium"。