构建说明
¥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
构建工具
¥Build Tools
Electron 的构建工具 自动化了使用不同配置和构建目标从源代码编译 Electron 的大部分设置。如果你希望手动设置环境，请参阅下面列出的说明。
¥Electron's Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. If you wish to set up the environment manually, the instructions are listed below.
Electron 使用 GN 进行项目生成，使用 ninja 进行构建。项目配置可以在 .gn 和 .gni 文件中找到。
¥Electron uses GN for project generation and
ninja for building. Project configurations can
be found in the .gn and .gni files.
GN 文件
¥GN Files
以下 gn 文件包含构建 Electron 的主要规则：
¥The following gn files contain the main rules for building Electron:
-
BUILD.gn定义了 Electron 本身的构建方式，并包含与 Chromium 链接的默认配置。¥
BUILD.gndefines how Electron itself is built and includes the default configurations for linking with Chromium. -
build/args/{testing,release,all}.gn包含构建 Electron 的默认构建参数。¥
build/args/{testing,release,all}.gncontain the default build arguments 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 并添加值为 0 的系统变量 DEPOT_TOOLS_WIN_TOOLCHAIN。这告诉 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/<username>/electron），而不是https://github.com/electron/electron。¥Instead of
https://github.com/electron/electron, you can use your own fork here (something likehttps://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 -
📝gclient 的工作原理是检查 src/electron 文件夹内名为 DEPS 的文件的依赖（例如 Chromium 或 Node.js）。运行 gclient sync -f 可确保构建 Electron 所需的所有依赖都与该文件匹配。
¥📝 gclient works by checking a file called DEPS inside the
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.
因此，为了拉取，你需要运行以下命令：
¥So, in order to pull, you'd run the following commands:
$ cd src/electron
$ git pull
$ gclient sync -f
架构
¥Building
设置 Chromium 构建工具的环境变量
¥Set the environment variable for chromium build tools
在 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 的测试构建配置：
¥To generate Testing build config of 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 的 Release 构建配置：
¥To generate Release build config of 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\`")"
注意：这将在 src/ 下生成 out/Testing 或 out/Release 构建目录，其中包含测试或发布构建，具体取决于上面传递的配置。你可以将 Testing|Release 替换为其他名称，但它应该是 out 的子目录。
¥Note: This will generate a out/Testing or out/Release build directory under src/ with the testing or release build depending upon the configuration passed above. You can replace Testing|Release with another names, but it should be a subdirectory of 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：注意：这也需要一段时间，并且可能会让你的膝盖变热。
¥To build, run ninja with the electron target:
Note: 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
这将构建之前 '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
在 linux 上，首先剥离调试和符号信息：
¥On linux, first strip the debugging and symbol information:
$ electron/script/strip-binaries.py -d out/Release
要将 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 x64 | Windows arm64 | 实验性的 |
| Windows x64 | Windows x86 | 自动测试 |
| Linux x64 | Linux x86 | 自动测试 |
如果你测试其他组合并发现它们可以工作，请更新此文档:)
¥If you test other combinations and find them to work, please update this document :)
有关 target_os 和 target_cpu 的允许值，请参阅 GN 参考。
¥See the GN reference for allowable values of target_os
and target_cpu.
Arm 上的 Windows（实验性）
¥Windows on Arm (experimental)
要针对 Arm、遵循 Chromium 的指南 上的 Windows 进行交叉编译，以获得必要的依赖、SDK 和库，然后在运行 gclient sync 之前在你的环境中使用 ELECTRON_BUILDING_WOA=1 进行构建。
¥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
接下来，按上述方式运行 gn gen 和 target_cpu="arm64"。
¥Next, run gn gen as above with target_cpu="arm64".
测试
¥Tests
要运行测试，你首先需要针对在构建过程中构建的同一版本的 Node.js 构建测试模块。要生成要编译的模块的构建标头，请在 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 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
通过将 gclient git 缓存导出为 Linux 上的 SMB 共享，可以与其他计算机共享 gclient git 缓存，但一次只能有一个进程/计算机使用该缓存。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
gclient 同步抱怨变基
¥gclient sync complains about rebase
如果 gclient sync 被中断，git 树可能会处于错误状态，从而在将来运行 gclient sync 时导致出现神秘消息：
¥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.
如果 src/electron 中没有 git 冲突或变基，你可能需要中止 src 中的 git am：
¥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
如果你签出了 electron/src/ 或其他依赖存储库中的分支（而不是分离的头），也可能会发生这种情况。如果是这种情况，适当存储库中的 git checkout --detach HEAD 应该可以解决问题。
¥This may also happen if you have checked out a branch (as opposed to having a detached head) in electron/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 将尝试下载只有 Google 员工可以访问的 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).
e 找不到模块
¥e Module not found
如果尽管运行 npm i -g @electron/build-tools 但仍无法识别 e，即：
¥If e is not recognized despite running npm i -g @electron/build-tools, ie:
Error: Cannot find module '/Users/<user>/.electron_build_tools/src/e'
我们建议通过 nvm 安装 Node。这允许更轻松的 Node 版本管理，并且通常是缺失 e 模块的修复。
¥We recommend installing Node through nvm. This allows for easier Node version management, and is often a fix for missing e modules.
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.