构建说明

请遵循以下指南来构建 Electron 本身，以便创建自定义 Electron 二进制文件。对于将您的应用程序代码与预构建的 Electron 二进制文件捆绑和分发，请参阅应用程序分发指南。

平台先决条件

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

设置 `@electron/build-tools`（推荐）

Electron Build Tools 可以自动执行许多从源代码编译 Electron 的设置，并支持不同的配置和构建目标。大多数手动设置指令都可以通过更简单的 Build Tools 命令来代替。

提示

Build Tools 还为您提供了访问远程执行和构建操作缓存的权限，这将大大提高构建速度。

Electron Build Tools 可以从 npm 全局安装

npm install -g @electron/build-tools

安装完成后，e 命令应在您的命令行中全局可用。e init 命令会引导本地检出 Electron

# The 'Hello, World!' of build-tools: get and build `main`
# Choose the directory where Electron's source and build files will reside.
# You can specify any path you like; this command defaults to `$PWD/electron`.
# If you're going to use multiple branches, you may want something like:
# `--root=~/electron/branch` (e.g. `~/electron-gn/main`)
e init --root=~/electron --bootstrap testing

--bootstrap 标志还会运行 e sync（使用 gclient 同步来自 DEPS 的源代码分支）和 e build（将 Electron 二进制文件编译到 ${root}/src/out 文件夹中）。

信息

在初始 e sync 阶段之后，您将被要求运行 e d rbe login 以进行远程构建执行身份验证并继续构建。这可能需要大约 20-30 分钟！

构建编译完成后，您可以通过运行 e start（或将其加载到 Electron Fiddle）来测试它。

导航项目

一些关于在设置好检出后进行构建的快速提示

目录结构： 在项目中，Chromium 代码同步到 ${root}/src/，而 Electron 的代码（即 https://github.com/electron/electron 中的代码）位于 ${root}/src/electron/ 中。请注意，这两个目录都有自己的 git 仓库。
更新您的检出： 从 ${root}/src/electron 运行 git 命令，例如 git checkout <branch> 和 git pull。每当您更新 commit HEAD 时，请确保在 e build 之前 e sync 以同步依赖项，例如 Chromium 和 Node.js。这一点尤其重要，因为 DEPS 中的 Chromium 版本经常更改。
重建： 在本地分支中对 ${root}/src/electron/ 中的代码进行更改时，您只需要重新运行 e build。
添加补丁： 在 ${root}/src/ 之外（但在 ${root}/src/electron/ 之外）贡献更改时，您需要通过 Electron 的补丁系统来进行。当您的代码更改准备好后，e patches 命令可以将所有相关补丁导出到 ${root}/src/electron/patches/。

信息

除非您正在应用上游补丁，否则您应该将 ${root}/src/ 视为只读文件夹，并将大部分开发时间花在 ${root}/src/electron/ 中。您不需要对 ${root}/src/ 进行任何更改或运行 git 命令。

提示

有关所有可用 e 命令的详细文档，请参阅仓库的 README.md。您还可以运行 e --help 以列出所有命令，并使用 --help 标志在任何命令上获取更多用法信息。

提示

有关项目结构的更多信息，请参阅源代码目录结构指南。

手动设置（高级）

手动设置（高级）

Electron 使用 GN 进行项目生成，并使用 siso 进行构建。项目配置可以在 electron/electron 仓库中的 .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.

您可以改用您自己的 fork（例如 https://github.com/<username>/electron），而不是 https://github.com/electron/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 通过检查 ${root}/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 的测试构建配置

在 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 的发布构建配置

在 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\`")"

注意

这将在 ${root}/src/ 下的 out/Testing 或 out/Release 构建目录中生成测试或发布构建，具体取决于上面传递的配置。您可以将 Testing|Release 替换为另一个名称，但它应该是 out 的子目录。

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

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

对于测试配置

$ ninja -C out/Testing electron

对于发布配置

$ 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

打包

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

$ ninja -C out/Release electron:electron_dist_zip

交叉编译

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

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

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

主机	目标	状态
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

接下来，如上所示运行 gn gen，并将 target_cpu="arm64"。

测试

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

$ ninja -C out/Testing electron:node_headers

现在您可以运行测试。

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

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

可以通过将它导出为 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

故障排除

`sync` 抱怨 rebase

如果 e sync (或 gclient sync) 被中断，git 树可能会处于错误状态，导致未来运行 sync 时出现难以理解的消息。

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

如果 ${root}/src/electron 中没有 git 冲突或 rebase，你可能需要中止 ${root}/src 中的 git am。

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

如果你在 ${root}/src/ 或其他依赖项的仓库中检出分支（而不是处于分离头指针状态），也可能会发生这种情况。如果是这样，在相应的仓库中执行 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 员工访问的内部版本）。

RBE 身份验证随机失败，出现“Token 无效”

这可能是由于机器上的本地时钟时间偏差较小造成的。使用 time.is 进行检查。

平台先决条件​

设置 @electron/build-tools（推荐）​

导航项目​

手动设置（高级）​

GN 文件​

GN 先决条件​

设置 git 缓存​

获取代码​

关于拉取/推送的说明​

构建​

打包​

交叉编译​

Windows on Arm​

测试​

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

故障排除​

sync 抱怨 rebase​

我被要求输入 chromium-internal.googlesource.com 的用户名/密码​

RBE 身份验证随机失败，出现“Token 无效”​

平台先决条件

设置 `@electron/build-tools`（推荐）

导航项目

手动设置（高级）

GN 文件

GN 先决条件

设置 git 缓存

获取代码

关于拉取/推送的说明

构建

打包

交叉编译

Windows on Arm

测试

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

故障排除

`sync` 抱怨 rebase

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

RBE 身份验证随机失败，出现“Token 无效”