Build Instructions 构建说明¶

请遵循以下指南来构建 Electron 本身，以创建自定义的 Electron 二进制文件。如需使用预构建的 Electron 二进制文件来打包和分发你的应用代码，请参阅应用程序分发指南。

平台先决条件¶

在继续之前，请先查看适用于你平台的构建先决条件：

• macOS
• Linux
• Windows

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

Electron Build Tools 自动化了从源码编译 Electron 的大部分设置，并支持不同的配置和构建目标。 大部分手动设置说明都可以替换为更简单的 Build Tools 命令。

[!TIP] Build Tools 还允许你使用构建操作的远程执行与缓存，这将显著缩短构建时间。

Electron Build Tools 可以通过 npm 进行全局安装：

npm install -g @electron/build-tools

安装完成后，e 命令应已在你的命令行中全局可用。e init 命令会引导创建一份本地 Electron 检出（checkout）：

# 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 目录中）。

[!IMPORTANT]

在初始的 e sync 阶段结束后的某个时刻，系统会提示你运行 e d rbe login 以登录远程构建执行服务，然后继续构建。这可能大约需要 20-30 分钟！

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

项目导航¶

以下是一些快速提示，帮助你在检出（checkout）设置完成后进行构建：

• 目录结构： 在项目内，Chromium 代码会同步到 ${root}/src/，而 Electron 的代码（即 https://github.com/electron/electron 中的代码）位于 ${root}/src/electron/。请注意，这两个目录都有自己的 git 仓库。
• 更新你的检出： 在 ${root}/src/electron 目录中运行 git checkout <branch> 和 git pull 等 git 命令。每当你更新 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/。

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

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

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

$ 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 -

[!TIP] gclient 的工作原理是检查 ${root}/src/electron 文件夹中名为 DEPS 的文件， 以获取依赖项（如 Chromium 或 Node.js）。 运行 gclient sync -f 可以确保构建 Electron 所需的所有依赖都与该文件匹配。

要拉取更新，可以运行以下命令：

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

构建¶

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

[!NOTE] 根据上面传入的配置，这将在 ${root}/src/ 下生成一个 out/Testing 或 out/Release 构建目录， 分别对应 testing 或 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

打包¶

要将 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"'

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

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

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

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'

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

可以通过将 gclient git 缓存导出为 Linux 上的 SMB 共享来与其他机器共享， 但同一时间只能有一个进程/机器使用该缓存。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/ 或其他某个依赖仓库中检出了分支（而不是处于游离 HEAD 状态），也可能出现此问题。如果是这样，在相应的仓库中执行 git checkout --detach HEAD 即可解决。

系统提示我输入 chromium-internal.googlesource.com 的用户名/密码¶

如果你在 Windows 上运行 gclient sync 时看到提示 Username for 'https://chrome-internal.googlesource.com':，那很可能是因为 DEPOT_TOOLS_WIN_TOOLCHAIN 环境变量未设置为 0。打开 Control Panel → System and Security → System → Advanced system settings，并添加一个系统变量 DEPOT_TOOLS_WIN_TOOLCHAIN，值设为 0。这会告诉 depot_tools 使用你本地安装的 Visual Studio 版本（默认情况下，depot_tools 会尝试下载一个只有 Google 员工才能访问的 Google 内部版本）。

RBE 认证偶尔失败并提示 “Token not valid”¶

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