构建说明

请遵循以下指南来构建 Electron 本身，以创建自定义 Electron 二进制文件。 有关使用预构建的 Electron 二进制文件捆绑和分发应用代码的信息，请参阅应用程序分发指南。

平台先决条件

在继续之前，请检查您平台的构建先决条件

• macOS
• Linux
• Windows

构建工具

Electron 的构建工具 自动化了从源代码编译具有不同配置和构建目标的 Electron 的大部分设置。 如果您希望手动设置环境，请参阅以下说明。

Electron 使用 GN 进行项目生成，并使用 ninja 进行构建。 项目配置可以在 .gn 和 .gni 文件中找到。

GN 文件

以下 gn 文件包含构建 Electron 的主要规则

• BUILD.gn 定义了 Electron 本身的构建方式，并包含了与 Chromium 链接的默认配置。
• build/args/{testing,release,all}.gn 包含构建 Electron 的默认构建参数。

GN 先决条件

您需要安装 depot_tools，这是用于获取 Chromium 及其依赖项的工具集。

此外，在 Windows 上，您需要设置环境变量 DEPOT_TOOLS_WIN_TOOLCHAIN=0。 为此，打开 控制面板 → 系统和安全 → 系统 → 高级系统设置 并添加一个系统变量 DEPOT_TOOLS_WIN_TOOLCHAIN，值为 0。 这告诉 depot_tools 使用您本地安装的 Visual Studio 版本（默认情况下，depot_tools 将尝试下载 Google 内部版本，只有 Google 员工才能访问）。

设置 git 缓存

如果您计划多次检出 Electron（例如，拥有多个并行目录检出到不同的分支），使用 git 缓存将加快后续对 gclient 的调用。 为此，设置 GIT_CACHE_PATH 环境变量

$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# This will use about 16G.

获取代码

$ mkdir electron && cd electron
$ gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
$ gclient sync --with_branch_heads --with_tags
# This will take a while, go get a coffee.

除了 https://github.com/electron/electron，您也可以在此处使用您自己的 fork（例如 https://github.com/<username>/electron）。

关于拉取/推送的说明

如果您将来打算从官方 electron 仓库进行 git pull 或 git push，您现在需要更新相应文件夹的 origin URL。

$ cd src/electron
$ git remote remove origin
$ git remote add origin https://github.com/electron/electron
$ git checkout main
$ git branch --set-upstream-to=origin/main
$ cd -

📝 gclient 的工作原理是检查 src/electron 文件夹内名为 DEPS 的文件以查找依赖项（如 Chromium 或 Node.js）。 运行 gclient sync -f 可确保构建 Electron 所需的所有依赖项与该文件匹配。

因此，要拉取，您需要运行以下命令

$ cd src/electron
$ git pull
$ gclient sync -f

构建

设置 chromium 构建工具的环境变量

在 Linux 和 MacOS 上

$ cd src
$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools

在 Windows 上

# cmd
$ cd src
$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\buildtools

# PowerShell
$ cd src
$ $env:CHROMIUM_BUILDTOOLS_PATH = "$(Get-Location)\buildtools"

生成 Electron 的 Testing 构建配置

在 Linux 和 MacOS 上

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

在 Windows 上

# cmd
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"

# PowerShell
gn gen out/Testing --args="import(\`"//electron/build/args/testing.gn\`")"

生成 Electron 的 Release 构建配置

在 Linux 和 MacOS 上

$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"

在 Windows 上

# cmd
$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"

# PowerShell
$ gn gen out/Release --args="import(\`"//electron/build/args/release.gn\`")"

注意： 这将在 src/ 下生成 out/Testing 或 out/Release 构建目录，具体取决于上面传递的配置。 您可以将 Testing|Release 替换为其他名称，但它应该是 out 的子目录。

此外，您不应该再次运行 gn gen — 如果您想更改构建参数，可以运行 gn args out/Testing 以打开编辑器。 要查看可用构建配置选项的列表，请运行 gn args out/Testing --list。

要构建，请使用 electron 目标运行 ninja： 注意：这也会花费一段时间，并且可能会使您的膝盖发热。

对于 testing 配置

$ ninja -C out/Testing electron

对于 release 配置

$ ninja -C out/Release electron

这将构建以前的 'libchromiumcontent'（即 chromium 的 content/ 目录及其依赖项，包括 Blink 和 V8）的所有内容，因此这将花费一段时间。

构建的可执行文件将在 ./out/Testing 下

$ ./out/Testing/Electron.app/Contents/MacOS/Electron
# or, on Windows
$ ./out/Testing/electron.exe
# or, on Linux
$ ./out/Testing/electron

打包

在 Linux 上，首先去除调试和符号信息

$ electron/script/strip-binaries.py -d out/Release

要将 electron 构建打包为可分发的 zip 文件

$ ninja -C out/Release electron:electron_dist_zip

交叉编译

要为与您正在构建的平台不同的平台进行编译，请设置 target_cpu 和 target_os GN 参数。 例如，要从 x64 主机编译 x86 目标，请在 gn args 中指定 target_cpu = \"x86\"。

$ gn gen out/Testing-x86 --args='... target_cpu = "x86"'

并非 Chromium 支持所有源和目标 CPU/OS 的组合。

主机	目标	状态
Windows x64	Windows arm64	实验性
Windows x64	Windows x86	自动测试
Linux x64	Linux x86	自动测试

如果您测试了其他组合并发现它们可以工作，请更新本文档 :)

请参阅 GN 参考文档，了解 target_os 和 target_cpu 的允许值。

Windows on Arm (实验性)

要为 Windows on Arm 进行交叉编译，请按照 Chromium 的指南获取必要的依赖项、SDK 和库，然后在运行 gclient sync 之前，在您的环境中以 ELECTRON_BUILDING_WOA=1 进行构建。

set ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags

或者（如果使用 PowerShell）

$env:ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags

接下来，使用 target_cpu=\"arm64\" 运行如上的 gn gen。

测试

要运行测试，您首先需要针对与构建过程中构建的 Node.js 版本相同的版本构建测试模块。 要为模块生成要编译的构建头文件，请在 src/ 目录下运行以下命令。

$ ninja -C out/Testing electron:node_headers

您现在可以运行测试。

如果您正在调试某些内容，将一些额外的标志传递给 Electron 二进制文件可能会很有帮助

$ npm run test -- \
  --enable-logging -g 'BrowserWindow module'

在多台机器之间共享 git 缓存

可以通过在 Linux 上将其导出为 SMB 共享来与其他机器共享 gclient git 缓存，但一次只能有一个进程/机器使用缓存。 git-cache 脚本创建的锁将尝试阻止这种情况，但它在网络中可能无法完美工作。

在 Windows 上，SMBv2 具有目录缓存，这将导致 git 缓存脚本出现问题，因此有必要通过设置注册表项来禁用它

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Lanmanworkstation\Parameters\DirectoryCacheLifetime

为 0。 更多信息：https://stackoverflow.com/a/9935126

这可以在 powershell 中快速设置（以管理员身份运行）

New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Services\Lanmanworkstation\Parameters" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force

故障排除

gclient sync 抱怨 rebase

如果 gclient sync 中断，git 树可能会处于错误状态，从而在将来运行 gclient sync 时导致出现神秘消息

2> Conflict while rebasing this branch.
2> Fix the conflict and run gclient again.
2> See man git-rebase for details.

如果在 src/electron 中没有 git 冲突或 rebase，您可能需要在 src 中中止 git am

$ cd ../
$ git am --abort
$ cd electron
$ gclient sync -f

如果您在 electron/src/ 或其他一些依赖项的仓库中检出了分支（而不是分离的 HEAD），也可能发生这种情况。 如果是这种情况，在相应的仓库中运行 git checkout --detach HEAD 应该可以解决问题。

我被要求提供 chromium-internal.googlesource.com 的用户名/密码

如果您在 Windows 上运行 gclient sync 时看到 Username for 'https://chrome-internal.googlesource.com': 的提示，则可能是因为 DEPOT_TOOLS_WIN_TOOLCHAIN 环境变量未设置为 0。 打开 控制面板 → 系统和安全 → 系统 → 高级系统设置 并添加一个系统变量 DEPOT_TOOLS_WIN_TOOLCHAIN，值为 0。 这告诉 depot_tools 使用您本地安装的 Visual Studio 版本（默认情况下，depot_tools 将尝试下载 Google 内部版本，只有 Google 员工才能访问）。

e 模块未找到

如果运行 npm i -g @electron/build-tools 后仍然无法识别 e，例如

Error: Cannot find module '/Users/<user>/.electron_build_tools/src/e'

我们建议通过 nvm 安装 Node。 这可以更轻松地管理 Node 版本，并且通常可以修复缺少 e 模块的问题。

RBE 身份验证随机失败，并显示“令牌无效”

这可能是由于机器上的本地时钟时间略有偏差引起的。 使用 time.is 进行检查。