Electron 在 Linux 源码构建指南：从依赖安装、GN 交叉编译到自定义二进制

本文围绕 Electron 官方仓库的 docs/development/build-instructions-linux.md 展开，系统讲解在 Linux 主机上从源码编译 Electron 本身（而非打包应用）的完整流程：前置依赖、install-deps.sh 用法、GN 参数配置、target_cpu 交叉编译、常见故障（libtinfo.so.5）以及编译器的高级定制。读完本文，你可以自己搭建 Linux 构建环境，产出面向 x64 / arm 等目标架构的自定义 Electron 二进制，并理解其背后的仓库实现依据。

明确边界：构建 Electron 本身 ≠ 分发你的应用

文档在开篇就划清了一条重要边界：本文所述的构建流程面向的是 Electron 二进制自身，目的是产出定制化的 Electron 可执行文件（例如打入自己补丁、裁剪模块或更换运行时的版本）。如果你只是想把自己写的应用代码与官方预编译的 Electron 二进制打包、分发，则不需要走完整套 Chromium 级构建，直接参考 应用分发指南 即可。

之所以要区分，是因为“从源码构建 Electron”本质上是“构建 Chromium + Node.js + Electron 胶水层”三者的巨型组合工程：本仓库 DEPS 中记录了当前版本对应的依赖基线，例如 chromium_version 为 155.0.8038.2、node_version 为 v24.20.0，这意味着一次全量同步与构建会拉取并编译数量庞大的第三方源码。

前置条件：依赖随时间变化，以官方最新为准

由于 Electron 依赖 Chromium，其构建前置条件并非一成不变，而是随上游持续演化。官方文档给出的策略是：

1. 参考 Chromium 的 Linux 构建文档作为基础（Debian/Ubuntu 等发行版上安装构建工具链与系统库的方法可直接复用）。
2. 叠加 Electron 自己的 Linux 依赖安装脚本 install-deps.sh（来自 electron/build-images 仓库），它负责补齐 Chromium 脚本之外 Electron 额外需要的依赖。

在克隆下来的源码树中，与 Linux 系统库相关的证据随处可见：

• 根级 BUILD.gn 中 if (is_linux) 分支通过 pkg_config 声明了运行时系统依赖，例如 gio-unix-2.0（用于文件选择等桌面集成）、glib-2.0 与 gdk-pixbuf-2.0（用于通知模块）；
• 同一区域还通过 generate_library_loader 生成 LibNotifyLoader（libnotify/notify.h 中的 notify_init、notify_notification_show 等函数），说明 Linux 构建环境需要具备 GTK 与 libnotify 相关的头文件与运行库；
• install_sysroot 相关的 gclient hooks（见 DEPS）会在同步阶段调用 src/build/linux/sysroot_scripts/install-sysroot.py，依据 script/sysroots.json 下载对应架构的 Debian sysroot（当前仓库记录有 bullseye_amd64、bullseye_arm64、bullseye_i386 以及 trixie_riscv64 等条目）。

因此，如果你的发行版较新（如刚发布的大版本），务必先查阅 Chromium 上游文档确认工具链与库要求是否变化，再决定是否修改依赖安装脚本或 sysroot 配置。

交叉编译时的额外依赖

如果目标平台不是当前主机的 CPU 架构（典型场景是在 x64 开发机上构建 arm 目标），需要让依赖安装脚本为 arm 架构额外准备依赖：

$ sudo install-deps.sh --arm

这里的 install-deps.sh 指 Electron 的 Linux 依赖安装脚本；若还需要 arm64 目标，可参考脚本支持的架构参数。随后在 GN 生成构建目录时，通过 target_cpu 指定目标 CPU 架构：

$ gn gen out/Testing --args='import("//electron/build/args/testing.gn") target_cpu="arm"'

说明：命令中的 //electron/build/args/testing.gn 是 gclient 检出结构下的 GN 路径——Electron 仓库被同步到 ${root}/src/electron，因此 //electron 前缀对应的就是本仓库根目录，build/args/testing.gn 即仓库内的 build/args/testing.gn。

构建入口：先看 GN 通用构建说明

文档在 “Building” 一节并未重复细节，而是直接指向 Build Instructions: GN。该文档给出了两条主流路径，均适用于 Linux：

• 推荐路径：安装 @electron/build-tools（npm 全局安装），用 e init --root=~/electron --bootstrap testing 一步完成源码同步（e sync）与编译（e build）。
• 手动高级路径：用 gclient 拉取 Chromium 依赖树，再执行 gn gen out/Testing --args='import("//electron/build/args/testing.gn")' 与 ninja -C out/Testing electron。

其中默认构建参数文件就来自仓库内的 build/args/testing.gn，它最终会再 import build/args/all.gn，后者集中定义了 Electron 构建的关键开关：

• is_electron_build = true 与 root_extra_deps = [ "//electron" ]，声明这是在为 Electron 而不是纯 Chromium 构建；
• node_module_version = 150，用于对齐 Node.js ABI 版本号，保证原生模块能被正确加载；
• node_openssl_path = "//third_party/boringssl"，让 Node.js 直接复用 Chromium 的 BoringSSL；
• v8_embedder_string = "-electron.0"，在 V8 版本串中打上 Electron 标识；
• ffmpeg_branding = "Chrome" 与 proprietary_codecs = true，默认启用专利编解码器支持。

如果你需要的是接近发布质量的构建，则改用 build/args/release.gn（is_official_build = true），它会走 PGO 优化，并在 build/pgo_profiles/ 中记录 x64 / arm64 等各平台可用的 PGO profile（当前仓库内含 linux-x64.pgo.txt 与 linux-arm64.pgo.txt）。

构建产物在哪儿

ninja -C out/Testing electron 执行完毕后，Linux 下可直接执行测试二进制：

$ ./out/Testing/electron

根级 BUILD.gn 中 group("electron") 聚合了主程序 electron_app 等目标；如需生成可分发的压缩包，可构建 electron_dist_zip（定义于 BUILD.gn 附近的 dist_zip("electron_dist_zip")）：

$ ninja -C out/Release electron:electron_dist_zip

深入交叉编译：架构、sysroot 与支持矩阵

除了文档示例中的 arm，target_cpu 还支持 x86、arm64、mips、mips64、riscv64 等取值。从仓库的 gclient hooks 可以确认 Electron 为多种 Linux 架构准备了同步机制：

• DEPS 中按架构（arm、arm64、x86、mips、mips64、x64）分别注册了 sysroot 安装 hook，条件组合如 install_sysroot and checkout_linux and checkout_arm64；
• script/sysroots.json 则列出了当前 Electron 版本为各架构下载的 Debian sysroot 及其校验和（Sha256Sum），其中 riscv64 使用的是 trixie_riscv64 sysroot。

从通用构建文档已知的主机→目标支持状态（Linux 相关部分）为：

主机	目标	状态
Linux x64	Linux x86	自动化测试覆盖

其余组合（例如 x64 主机构建 arm/arm64 目标）在 Electron 依赖树中有对应 sysroot 支撑，可按需尝试；Chromium 本身并不保证所有主机/目标组合都可用，建议以实际构建结果为准。

需要注意：交叉编译时 gn gen 的构建目录应单独命名（例如 out/Testing-arm、out/Testing-x64），避免与主机架构产物混淆。若同时指定 target_os，理论上还可实现跨操作系统构建，但 Linux→其他 OS 的组合并不被 Chromium 官方支持，实践中应避免。

故障排查：libtinfo.so.5 加载失败

这是 Linux 上编译 Electron（实为编译/链接 Chromium 工具链）时最经典的报错之一：

error while loading shared libraries: libtinfo.so.5

原因：Chromium 提供的预编译 clang 在运行时依赖 libtinfo.so.5（ncurses 的终端信息库，clang 用它做终端交互）。而较新的发行版通常只带 libtinfo.so.6（对应 ncurses6），或以多架构路径存放（如 /usr/lib/x86_64-linux-gnu/），因此链接器找不到 .so.5。

解法：按主机架构把系统中合适的 ncurses 库软链成 libtinfo.so.5。文档给出的典型命令是：

$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5

在实际使用中需要根据发行版与架构调整路径。例如在 Debian/Ubuntu 的多架构布局下，x64 主机常见做法是：

$ sudo ln -s /usr/lib/x86_64-linux-gnu/libncurses.so.5 /usr/lib/x86_64-linux-gnu/libtinfo.so.5

若系统只有 ncurses6（libtinfo.so.6）而没有 ncurses5 兼容包，通常需先安装 ncurses5/libtinfo5 兼容包，再建立上述符号链接；不同发行版的包名与库路径各有差异，请以实际环境为准。

高级主题：替换编译器与限制

使用系统 clang 替代下载的 clang

默认情况下，Electron（继承 Chromium）使用 Chromium 项目提供的预编译 clang 二进制，这样能保证工具链版本与源码期望一致。文档指出：如果确有原因需要使用系统中安装的 clang，可以通过 GN 参数 clang_base_path 指定 clang 的安装位置。

例如 clang 安装在 /usr/local/bin/clang 时，clang_base_path 应指向其上一级目录 /usr/local（即不含 bin 子目录的父路径）：

$ gn gen out/Testing --args='import("//electron/build/args/testing.gn") clang_base_path = "/usr/local/bin"'

注意：clang_base_path 应指向 clang 工具链的父目录，通常该目录下直接存在 bin/clang。传入后应删除原 out/ 构建目录重新 gn gen，因为编译器路径属于会改变整个工具链决策的关键参数。

为什么不支持 clang 以外的编译器

文档明确声明：使用 clang 以外的编译器（如 GCC）构建 Electron 是不被支持的。从仓库工程文件也能看出这一点——Chromium/Electron 的构建系统（GN 描述、众多的 patches/chromium 补丁、ABI 约定、sanitizer 支持等）均围绕 clang/LLVM 设计，换用其他编译器会遇到大量头文件、链接选项与内建函数层面的不兼容，无法保证正确性与稳定性。因此在 Linux 上构建时，要么使用随 Chromium 下载的预编译 clang（默认，推荐），要么使用兼容的本地 clang；不要尝试 GCC 路线。

结合源码理解 Linux 构建的完整性

一份成功的 Linux 构建需要仓库多处代码协同，写作本文所依据的官方文档之外，可以从本仓库观察到如下印证：

• 构建定义：根级 BUILD.gn 通过大量 import 组装出完整目标图；Linux 分支（BUILD.gn）负责 GTK 桩代码生成（electron_gtk_stubs）与 libnotify 动态加载封装，体现桌面集成的系统库依赖。
• 依赖锁定：DEPS 精确锁定 Chromium / Node.js / 各第三方依赖的版本或 commit，保证 gclient 同步出的源码树彼此兼容。
• 参数组合：build/args/all.gn、build/args/testing.gn、build/args/release.gn 三件套构成了 import(...) 全部默认参数的内容来源——这也是文档命令行里 import("//electron/build/args/testing.gn") 语句所指向的真实文件。
• 架构支撑：script/sysroots.json 与 DEPS 的 sysroot hooks 共同支撑了 Linux 上的多架构（含交叉编译）产出。
• 补丁体系：patches/chromium 目录中包含大量面向 Linux 上游的补丁（如 Wayland 窗口状态、Linux tray、fix_linux_tray_id.patch 等），这些补丁在 gclient sync/e sync 阶段被应用到 src/ 下 Chromium 源码中，是“从源码构建 Electron”不可或缺的一环。

总结

在 Linux 上从源码构建 Electron 的要点可归纳为：

1. 依赖先行：跟随 Chromium 官方 Linux 构建文档，并叠加 Electron 的 install-deps.sh；交叉编译 arm 目标时加 --arm 参数。
2. 统一走 GN：构建命令一律收敛到 gn gen + ninja，参数默认值来自仓库 build/args/*.gn（对应 GN 路径 //electron/build/args/...）；推荐用 @electron/build-tools 的 e 命令简化同步与编译。
3. 区分架构目录：交叉编译通过 target_cpu 实现，不同架构使用独立 out/ 目录，并依赖 DEPS hooks 安装对应 sysroot。
4. 遇错先查工具链：libtinfo.so.5 这类报错是系统库与 Chromium 预编译 clang 的版本落差所致，通过符号链接即可解决。
5. 编译器几乎无选择：默认使用 Chromium 预编译 clang；clang_base_path 允许切到本地 clang，但 clang 之外的其他编译器不受支持。

对于任何希望在 Chromium 同步节奏之外控制构建细节的团队或个人，上述流程都是产出定制 Linux Electron 二进制的可靠起点。进一步的命令细节、产物布局与测试方法，可继续阅读 Build Instructions: GN 与 Source Code Directory Structure。