构建指南

按照下面的步骤构建 Electron，来生成自定义的 Electron 二进制文件。 为了将您的应用代码与预构建的 Electron 二进制文件打包并发布，请参阅 应用程序发布 指南。

平台要求

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

• macOS
• Linux
• Windows

构建工具

Electron的构建工具 自动化了很多配置不同的从源代码编译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}"
# 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
# 这将需要一段时间，喝杯咖啡休息一下。

除了使用 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 master
$ git branch --set-upstream-to=origin/master
$ cd -

📝 gclient 会检查 src/electron 目录下的 DEPS 文件，从中获取依赖信息 (就像 Chromium 或 Node.js 那样)。 运行 gclient sync -f 确保所有用来构建 Electron 的依赖都符合该文件的描述。

因此，为了拉取，您将运行以下命令：

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

构建

$ cd src
$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\") $GN_EXTRA_ARGS"

若在 Windows 上 (没有可选参数)：

$ cd src
$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\buildtools
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"

这将在src/下的out/Testing内生成一个有测试生成配置的文件夹 您可以用另一个名称 替换 Testing ，但它应该是 out 的子目录。 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.

要查看可用的构建配置选项的列表，运行 gn args out/Testing--list。

用于生成测试Electron的构建配置：

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

For generating Release (aka “non-component” or “static”) build config of Electron:

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

To build, run ninja with the electron target: Nota Bene: This will also take a while and probably heat up your lap.

For the testing configuration:

$ ninja -C out/Testing electron

For the release configuration:

$ ninja -C out/Release electron

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

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

打包

On linux, first strip the debugging and symbol information:

electron/script/strip-binaries.py -d out/Release

To package the electron build as a distributable zip file:

ninja -C out/Release electron:electron_dist_zip

交叉编译

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

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

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

有关 target_os 和 target_cpu 的有效值，请查看参考 GN。

Windows on Arm (experimental)

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 src/ directory.

$ ninja -C out/Testing third_party/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. More information: 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

故障排查

gclient sync complains about rebase

If gclient sync is interrupted the git tree may be left in a bad state, leading to a cryptic message when running gclient 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 src/electron, you may need to abort a git am in src:

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

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