构建说明

请遵循以下指南来构建 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 会尝试下载一个只有 Googlers 才能访问的 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/electron/electron（例如 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 的测试构建配置

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

注意

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

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

要构建，请使用 electron 目标运行 ninja： 注意：这会花费一些时间，并可能使您的笔记本电脑发热。

对于测试配置

$ 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

打包

在 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	自动测试

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

有关 target_os 和 target_cpu 允许值的详细信息，请参阅 GN 参考。

Arm 上的 Windows（实验性）

要为 Arm 上的 Windows 进行交叉编译，请遵循 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/ 或其他依赖项的仓库中检出了一个分支（而不是处于分离头模式），也可能发生这种情况。如果是这种情况，在相应的仓库中执行 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 会尝试下载一个只有 Googlers 才能访问的 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 认证随机失败并显示“Token not valid”

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