建置說明

請遵循以下指南來建置 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 會嘗試下載 Google 內部版本，只有 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"'

並非所有來源和目標 CPU/OS 的組合都受到 Chromium 支援。

主機	目標	狀態
Windows x64	Windows arm64	實驗性
Windows x64	Windows x86	自動測試
Linux x64	Linux x86	自動測試

如果您測試其他組合並發現它們可以運作，請更新此文件 :)

請參閱 GN 參考文件，以了解 target_os 和 target_cpu 的允許值。

Windows on Arm (實驗性)

若要為 Windows on Arm 進行交叉編譯，請遵循 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 快取

可以透過將 gclient git 快取匯出為 Linux 上的 SMB 共享來與其他機器共享，但一次只能有一個程序/機器可以使用快取。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/ 或某些其他依賴項的儲存庫中簽出了分支（而不是擁有分離的 HEAD），也可能會發生這種情況。如果是這種情況，則在適當的儲存庫中執行 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 會嘗試下載 Google 內部版本，只有 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 進行檢查。