构建说明

按照下面的步骤构建 Electron，来生成自定义的 Electron 二进制文件。 For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.

平台要求

各个平台所对应的构建要求如下：:

• macOS
• Linux
• Windows

Setting up @electron/build-tools (recommended)

Electron Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. Most of the manual setup instructions can be replaced by simpler Build Tools commands.

[!TIP] Build Tools also gives you access to remote execution and caching of build actions, which will dramatically improve build times.

Electron Build Tools can be installed globally from npm:

npm install -g @electron/build-tools

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

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

Sometime after the initial e sync phase, you will be asked to run e d rbe login to auth into remote build execution and proceed into the build. This may take about 20-30 minutes!

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:

• Directory structure: Within the project, Chromium code is synced to ${root}/src/ while Electron's code (i.e. code in https://github.com/electron/electron) lives in ${root}/src/electron/. Note that both directories have their own git repositories.
• Updating your checkout: Run git commands such as git checkout <branch> and git pull from ${root}/src/electron. Whenever you update your commit HEAD, make sure to e sync before e build to sync dependencies such as Chromium and Node.js. This is especially relevant because the Chromium version in DEPS changes frequently.
• Rebuilding: When making changes to code in ${root}/src/electron/ in a local branch, you only need to re-run e build.
• Adding patches: When contributing changes in ${root}/src/ outside of ${root}/src/electron/, you need to do so via Electron's patch system. The e patches command can export all relevant patches to ${root}/src/electron/patches/ once your code change is ready.

[!IMPORTANT] Unless you're applying upstream patches, you should treat ${root}/src/ as a read-only folder and spend most of your development time in ${root}/src/electron/. You should not need to make any changes or run git commands in ${root}/src/.

[!TIP] Detailed documentation for all available e commands can be found in the repository's README.md. You can also run e --help to list all commands and use the --help flag on any command to get more usage info.

[!TIP] For more information on project structure, see the Source Code Directory Structure guide.

Manual setup (advanced)

Manual setup (advanced)

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 files

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

• BUILD.gn defines how Electron itself is built and includes the default configurations for linking with Chromium.
• build/args/{testing,release,all}.gn contain the default build arguments for building Electron.

前置知识

此外，你还需要安装depot_tools，这是一个用于获取Chromium，及其相关依赖工具。

另外，如果使用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将会下载一个只有谷歌内部员工有权限使用的内部版本)。

设置 git 缓存

如果您想 checkout 多份 Electron 源码 (例如多个并行目录 checkout 到不同的分支)， 推荐使用 git 缓存来加速后续对 gclient的调用。 为此，设置 GIT_CACHE_PATH 环境变量：

$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# 这将使用大约16G

获取源码

$ mkdir electron && cd electron
$ gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
$ gclient sync --with_branch_heads --with_tags
# 这将需要一段时间，喝杯咖啡休息一下。

除了使用 https://github.com/electron/electron， 你也可以使用你自己的 fork (形如 https://github.com/<username>/electron)。

拉/推的注意事项

如果您将来打算从 electron 官方地址进行 git pull 或 git push，那么您需要更新相应文件夹的源 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 works by checking a file called DEPS inside the ${root}/src/electron folder for dependencies (like Chromium or Node.js). Running gclient sync -f ensures that all dependencies required to build Electron match that file.

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

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

构建

设置chromium build tools的环境变量

On 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 的测试构建配置，请执行以下操作：

On 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 build 配置，请执行以下操作：

On 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] This will generate a out/Testing or out/Release build directory under ${root}/src/ with the testing or release build depending upon the configuration passed above. 您可以用另一个名称替换 Testing|Release ，但它应该是 out 的子目录。

如果你想改变构建参数，可以通过运行gn args out/Testing来将参数带入编辑器，而无需再次运行gn gen命令。 要查看可用的构建配置选项的列表，运行 gn args out/Testing --list。

**构建时请运行 ninja [参数] [输出目录] electron ** 注意：这也需要点时间，也可能会让你的电脑发烫。

测试配置：

$ ninja -C out/Testing electron

发布配置：

$ ninja -C out/Release electron

这个过程会构建 'libchromiumcontent' 里的所有内容，(如 chromium中的content，及其依赖 Blink and V8), so it will take a while.

构建需要在./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 and target_os GN 参数。 例如，要从一个x64主机编译一个 x86 目标程序，指定target_cpu = "x86" 中指定 gn args。

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

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

Host	目标	状态
Windows x64	Windows arm64	实验性功能
Windows x64	Windows x86	Automatically tested
Linux x64	Linux x86	Automatically tested

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

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

Windows on Arm

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

Or (if using PowerShell):

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

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

测试

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.

可以通过增加其它标记来调试程序，例如：

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

在多个计算机之间共享 git 缓存

可以将gclient git 缓存与其他机器共享，导出为 SMB 在linux上共享。 但每次只能有一个进程或机器可以使用缓存。 The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.

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

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

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

故障排查

sync complains about rebase

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.

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

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.

I'm being asked for a username/password for chromium-internal.googlesource.com

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. 这将促使depot_tools 使用本地已安装的Visual Studio(默认状态下，depot_tools将会下载一个只有谷歌内部员工有权限使用的内部版本)。

RBE authentication randomly fails with "Token not valid"

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