Skip to main content

构建说明

🌐 Build Instructions

按照以下指南构建Electron 本身，用于创建自定义 Electron 二进制文件。有关将你的应用代码与预构建的 Electron 二进制文件打包和分发，请参阅 应用分发 指南。

🌐 Follow the guidelines below for building Electron itself, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.

平台先决条件​

🌐 Platform prerequisites

在继续之前，请检查你平台的构建前提条件：

🌐 Check the build prerequisites for your platform before proceeding:

🌐 Setting up @electron/build-tools (recommended)

Electron 构建工具 自动化了大部分从源代码编译 Electron 所需的设置，支持不同的配置和构建目标。大部分手动设置说明都可以被更简单的构建工具命令替代。

tip

构建工具还可以让你访问 远程执行和构建操作缓存， 这将显著提升构建速度。

Electron 构建工具可以通过 npm 全局安装：

🌐 Electron Build Tools can be installed globally from npm:

npm install -g @electron/build-tools

安装完成后，e 命令应该可以在你的命令行中全局使用。e init 命令用于引导本地的 Electron 检发布本：

🌐 Once installed, the e command should be globally available in your command line. The e init command bootstraps a local checkout of 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 文件夹）。

🌐 The --bootstrap flag also runs e sync (synchronizes source code branches from DEPS using gclient) and e build (compiles the Electron binary into the ${root}/src/out folder).

info

在最初的 e sync 阶段之后的某个时间，你将被要求运行 e d rbe login 来认证远程构建执行，并继续进行构建。这可能需要大约 20-30 分钟！

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

🌐 Once the build is done compiling, you can test it by running e start (or by loading it into Electron Fiddle).

🌐 Navigating the project

在结账设置完成后，一些快速的构建小技巧：

🌐 Some quick tips on building once your checkout is set up:

  • 目录结构： 在项目中，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/electron/ 之外对 ${root}/src/ 做出更改时，你需要通过 Electron 的 补丁系统 来进行。一旦你的代码更改准备好，e patches 命令可以将所有相关补丁导出到 ${root}/src/electron/patches/。
info

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

tip

所有可用的 e 命令的详细文档可以在仓库的 README.md 中找到。你也可以运行 e --help 来列出所有命令，并对任何命令使用 --help 标志以获取更多使用信息。

tip

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

手动设置（高级）

手动设置（高级）​

🌐 Manual setup (advanced)

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

🌐 Electron uses GN for project generation and siso for building. Project configurations can be found in the .gn and .gni files in the electron/electron repo.

GN 文件​

🌐 GN files

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

🌐 The following gn files contain the main rules for building Electron:

GN 先决条件​

🌐 GN prerequisites

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

🌐 You'll need to install depot_tools, the toolset used for fetching Chromium and its dependencies.

此外，在 Windows 上，你需要设置环境变量 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 内部版本）。

🌐 Also, on Windows, you'll need to set the environment variable DEPOT_TOOLS_WIN_TOOLCHAIN=0. To do so, open Control Panel → System and Security → System → Advanced system settings and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version that only Googlers have access to).

设置 git 缓存​

🌐 Setting up the git cache

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

🌐 If you plan on checking out Electron more than once (for example, to have multiple parallel directories checked out to different branches), using the git cache will speed up subsequent calls to gclient. To do this, set a GIT_CACHE_PATH environment variable:

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

获取代码​

🌐 Getting the code

$ 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，而是使用你自己的分支 （类似 https://github.com/<username>/electron）。

关于拉/推的注意事项​

🌐 A note on pulling/pushing

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

🌐 If you intend to git pull or git push from the official electron repository in the future, you now need to update the respective folder's origin URLs.

$ 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 所需的所有依赖与该文件匹配。

为了执行拉取操作，你需要运行以下命令：

🌐 In order to pull, you'd run the following commands:

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

架构​

🌐 Building

为 Chromium 构建工具设置环境变量

在 Linux 和 MacOS 上

🌐 On Linux & MacOS

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

在 Windows 上：

🌐 On Windows:

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

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

生成 Electron 测试构建配置：

在 Linux 和 MacOS 上

🌐 On Linux & MacOS

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

在 Windows 上：

🌐 On 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 上

🌐 On Linux & MacOS

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

在 Windows 上：

🌐 On 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 替换为其他名称，但它应该是 out 的子目录。

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

🌐 Also you shouldn't have to run gn gen again—if you want to change the build arguments, you can run gn args out/Testing to bring up an editor. To see the list of available build configuration options, run gn args out/Testing --list.

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

对于测试配置：

🌐 For the testing configuration:

$ ninja -C out/Testing electron

对于发布配置：

🌐 For the release configuration:

$ ninja -C out/Release electron

这将构建之前的“libchromiumcontent”（即 chromium 的 content/ 目录及其依赖，包括 Blink 和 V8），所以会花费一些时间。

🌐 This will build all of what was previously 'libchromiumcontent' (i.e. the content/ directory of chromium and its dependencies, incl. Blink and V8), so it will take a while.

生成的可执行文件将位于 ./out/Testing 下：

🌐 The built executable will be under ./out/Testing:

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

封装​

🌐 Packaging

要将 Electron 版本打包为可分发的 zip 文件：

🌐 To package the electron build as a distributable zip file:

$ ninja -C out/Release electron:electron_dist_zip

交叉编译​

🌐 Cross-compiling

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

🌐 To compile for a platform that isn't the same as the one you're building on, set the target_cpu and target_os GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = "x86" in gn args.

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

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

🌐 Not all combinations of source and target CPU/OS are supported by Chromium.

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

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

🌐 If you test other combinations and find them to work, please update this document :)

请参阅 GN 参考以了解 target_os 和 target_cpu 的允许值。

🌐 See the GN reference for allowable values of target_os and target_cpu.

Arm 架构上的 Windows​

🌐 Windows on Arm

要为 Windows 上的 Arm 进行交叉编译，请按照 Chromium 的指南获取必要的依赖、SDK 和库，然后在你的环境中使用 ELECTRON_BUILDING_WOA=1 构建，再运行 gclient sync。

🌐 To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1 in your environment before running gclient sync.

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

或者（如果使用 PowerShell）：

🌐 Or (if using PowerShell):

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

接下来，像上面一样使用 target_cpu="arm64" 运行 gn gen。

🌐 Next, run gn gen as above with target_cpu="arm64".

测试​

🌐 Tests

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

🌐 To run the tests, you'll first need to build the test modules against the same version of Node.js that was built as part of the build process. To generate build headers for the modules to compile against, run the following under ${root}/src/ directory.

$ ninja -C out/Testing electron:node_headers

你现在可以运行测试。

🌐 You can now run the tests.

如果你正在调试某些东西，将一些额外的标志传递给 Electron 可执行文件可能会有帮助：

🌐 If you're debugging something, it can be helpful to pass some extra flags to the Electron binary:

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

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

🌐 Sharing the git cache between multiple machines

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

🌐 It is possible to share the gclient git cache with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a time. The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.

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

🌐 On Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key

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

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

🌐 to 0. More information: https://stackoverflow.com/a/9935126

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

🌐 This can be set quickly in powershell (ran as administrator):

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

故障排除​

🌐 Troubleshooting

sync 抱怨变基​

🌐 sync complains about rebase

如果 e sync（或 gclient sync）被中断，git 树可能会处于不良状态，导致将来运行 sync 时出现难以理解的消息：

🌐 If e sync (or gclient sync) is interrupted, the git tree may be left in a bad state, leading to a cryptic message when running sync in the future:

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 冲突或变基，你可能需要在 ${root}/src 中中止 git am：

🌐 If there are no git conflicts or rebases in ${root}/src/electron, you may need to abort a git am in ${root}/src:

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

如果你在 ${root}/src/ 或其他依赖仓库中签出了一个分支（而不是处于分离头指针状态），也可能会发生这种情况。如果是这种情况，在相应的仓库中执行 git checkout --detach HEAD 应该就能解决问题。

🌐 This may also happen if you have checked out a branch (as opposed to having a detached head) in ${root}/src/ or some other dependency’s repository. If that is the case, a git checkout --detach HEAD in the appropriate repository should do the trick.

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

🌐 I'm being asked for a username/password for 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 会尝试下载一个只有 Googler 才能访问的 Google 内部版本）。

🌐 If you see a prompt for Username for 'https://chrome-internal.googlesource.com': when running gclient sync on Windows, it's probably because the DEPOT_TOOLS_WIN_TOOLCHAIN environment variable is not set to 0. Open Control Panel → System and Security → System → Advanced system settings and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version that only Googlers have access to).

RBE 认证会随机出现“令牌无效”失败​

🌐 RBE authentication randomly fails with "Token not valid"

这可能是由于机器上的本地时钟时间有一点偏差造成的。使用 time.is 来检查。

🌐 This could be caused by the local clock time on the machine being off by a small amount. Use time.is to check.