簡介對于使用 Electron 構建桌面應用的開發(fā)者而言在 Windows 平臺下進行打包時常因本地緩存目錄缺少關鍵依賴而構建失敗本資源正好解決了這一問題。資源標題所示的“全家桶”包含 electron-v8.5.5-win32-x64、nsis-3.0.4.2 和 winCodeSign-2.6.0 三個核心組件其中 Electron 8.5.5 負責應用運行時NSIS 3.0.4.2 用于生成安裝程序WinCodeSign 2.6.0 承擔代碼簽名與校驗三者配合 electron-builder 等工具可形成完整閉環(huán)顯著降低因依賴不齊、版本不匹配或網(wǎng)絡下載超時導致的打包失敗概率。壓縮包以 7z 格式發(fā)布整體約 356.44MB內(nèi)部按 Electron 官方 Cache 目錄結構整理解壓后放入 C:\Users\XXX\AppData\Local\electron\Cache 即可被構建工具自動識別免去逐個項目手動配置的繁瑣。資源已有 1548 人學習使用對剛入門打包的初學者、經(jīng)常重裝電腦或維護多臺構建機的開發(fā)者來說是一份省時省力的離線備件也能為團隊統(tǒng)一構建環(huán)境提供有效備份。整個壓縮包保留了各組件原始版本與目錄結構便于多環(huán)境重復部署和版本追溯特別適合離線環(huán)境或網(wǎng)絡狀況不佳的場景這套組合解決了大多數(shù) Electron 應用在 Windows 分發(fā)時的環(huán)境痛點。1. electron 打包全家桶三個緩存文件才是安裝包產(chǎn)線的真正主力Electron 打包慢十次有八次不是編譯慢而是卡在下載上。你看到的標題里那三個文件——electron-v8.5.5-win32-x64、nsis-3.0.4.2、winCodeSign-2.6.0——就是 electron-builder 打 Windows 安裝包時最依賴的“全家桶”。它們分別對應 Electron 運行時、NSIS 安裝程序框架和 Windows 代碼簽名工具默認落在本地緩存目錄里。把它們一次對齊、緩存好本機和 CI 出安裝包的速度能從十幾分鐘壓到兩三分鐘。這個方向適合被打包等待折磨過、又不想每次在網(wǎng)絡波動上下注的 Electron 桌面應用開發(fā)者。2. 從 electron-v8.5.5-win32-x64 到 exeelectron-builder 的完整打包鏈路2.1 electron-builder 到底在做什么下載、組裝、壓縮三步先拆解鏈路。Electron 應用本身是跑在 Chromium 和 Node 之上的應用要變成 Windows 上能雙擊運行的 exe需要經(jīng)歷把應用資源打成 app.asar拿一個與平臺匹配的 Electron 運行時也就是標題里的 electron-v8.5.5-win32-x64.zip把 asar 放進去形成綠色版的 win-unpacked 目錄再把 win-unpacked 用 7z 壓縮成 app-64.7z隨后調(diào)用 NSIS 生成 setup.exe 安裝引導這里的 nsis-3.0.4.2 就是安裝器外殼最后調(diào)用 winCodeSign-2.6.0 里的簽名工具給 exe 和安裝包簽名。我一般會把 7z 壓縮和 NSIS 生成這兩步放在一起看NSIS 安裝器并不是直接拷貝 win-unpacked 里的所有文件而是把壓縮后的 7z 嵌入安裝器用戶在安裝時邊解壓邊寫入。這也是為什么最后產(chǎn)物里能看到一個體積很大的 setup.exe但它內(nèi)部其實是“引導器 壓縮包 卸載器”三件套。這五步里真正需要網(wǎng)絡的是 2、4、5。第 2 步尤其容易被忽略electron-v8.5.5-win32-x64.zip 的體積通常在 80MB 以上如果你的 package.json 里聲明的是 8.5.5但本地之前的打包用到的是別的版本electron-builder 會按版本號重新抓舊緩存不會被復用。所以別以為“上次打包成功了這次就快”版本號一變之前的下載全作廢。2.2 最小配置跑通打包package.json 與 build 字段常見做法是直接在 package.json 里寫 build 配置命令用 electron-builder不需要額外引入 webpack 之類的構建鏈。如果你的渲染層不需要打包成單一 bundleelectron-builder 自己就能負責拷貝資源和 asar 封裝需要 webpack 的是純前端構建場景那是在跑 electron-builder 之前的事。我也順手對比過 pyinstaller 和 pyside 的打包流程electron-builder 更像個黑匣子——它不把每一步暴露成 spec 文件而是通過固定參數(shù)把三個緩存文件抓齊版本一不對就重新下載。最小配置長這樣{ name: demo-app, version: 1.0.0, main: src/main/index.js, scripts: { pack: electron-builder --win nsis --x64 }, devDependencies: { electron: 8.5.5, electron-builder: ^20.44.4 }, build: { appId: com.example.demo, productName: DemoApp, directories: { output: release }, files: [ src/**/*, package.json ], win: { target: [nsis], icon: build/icon.ico }, nsis: { oneClick: false, allowToChangeInstallationDirectory: true } } }執(zhí)行 npm run pack 之后electron-builder 會先檢查 devDependencies 里 electron 版本是 8.5.5就去緩存目錄找 electron-v8.5.5-win32-x64.zip找到就直接解壓復用找不到就下載。接著按 win.target 里的 nsis 去取 nsis-3.0.4.2 和 winCodeSign-2.6.0。這三個一旦就位后面的組裝基本是本地計算不再依賴網(wǎng)絡。關鍵參數(shù)說明main 指向的是 Electron 主進程入口electron-builder 不負責編譯主進程它只是把這個文件作為 app.asar 的入口。files 數(shù)組用來控制哪些目錄進安裝包。把 node_modules 漏掉是新手常犯的錯誤純 JS 依賴會被收進 asar但原生模塊需要單獨處理。win.target 寫成數(shù)組將來要同時出 nsis 和 zip 時可以寫 [nsis, zip]全家桶會分別跑兩遍不算多余。2.3 版本號對齊為什么全家桶必須是一個整體electron 8.5.5 對應 win32-x64nsis 固定 3.0.4.2winCodeSign 固定 2.6.0。這三者不是隨便拼的。electron-builder 的不同版本會對某一組 nsis / winCodeSign 版本有綁定關系日志里能看到 “Downloading nsis-3.0.4.2” 這樣的字樣。我自己的經(jīng)驗是只要升級 electron-builder 大版本nsis 和 winCodeSign 往往也會跟著換標題里這一組是 20.x 時代很常見的組合。緩存目錄長這樣文件默認緩存目錄electron-v8.5.5-win32-x64.zip%LOCALAPPDATA%\electron\Cachensis-3.0.4.2.7z%LOCALAPPDATA%\electron-builder\Cache\nsiswinCodeSign-2.6.0%LOCALAPPDATA%\electron-builder\Cache\winCodeSign注意 %LOCALAPPDATA% 在不同 Windows 賬號下不一樣而且 electron 二進制的緩存目錄和 electron-builder 自己的緩存目錄是兩個地方?？吹竭@三個路徑就能理解“打包全家桶”里的“全家桶”其實指的是只要把這三樣東西手工放對位置electron-builder 就以為你已經(jīng)下載過了直接進入組裝環(huán)節(jié)。這也是后面離線打包思路的基礎。3. nsis-3.0.4.2安裝包外殼的參數(shù)調(diào)優(yōu)與 7 個常用配置3.1 認識 nsis 在 electron-builder 里的角色模板與腳本NSIS 是一個 Windows 安裝程序制作工具electron-builder 沒有自己寫安裝器而是把 NSIS 當外殼。nsis-3.0.4.2 這個 7z 包里包含 NSIS 主程序、Stubs、Plugins還有 electron-builder 專用的模板腳本。打包時 electron-builder 用這些模板生成一個安裝器 exe安裝器在用戶機器上做的事包括解壓 app-64.7z、寫注冊表卸載信息、創(chuàng)建開始菜單快捷方式、顯示安裝向導界面。它并不是把 install.nsi 原樣拷貝。electron-builder 的模板是固定的通過配置項拼出一段 .nsi 腳本想自己寫 .nsi 也可以但只能在 build.nsis.include 里指定一個自定義腳本片段讓模板去 include 它。真的從頭寫一個完整的 NSIS 腳本在 electron-builder 體系里基本用不上也容易把打包流程帶偏。winform 打包成安裝程序時常用的 VS 自帶部署和 Electron 走 NSIS 是兩條完全不同的路線不要把兩者混著看。3.2 安裝向導的關鍵參數(shù)oneClick、perMachine、安裝目錄先看一段我常用的 nsis 配置nsis: { oneClick: false, perMachine: false, allowElevation: true, allowToChangeInstallationDirectory: true, createDesktopShortcut: true, createStartMenuShortcut: true, shortcutName: DemoApp, artifactName: ${productName}-Setup-${version}.${ext}, installerHeaderIcon: build/installer-icon.ico, deleteAppDataOnUninstall: false, include: build/nsis-custom.nsi }參數(shù)說明oneClick默認 true點一下就直接裝不顯示向導。改成 false 才走“下一步 / 下一步”的安裝向導頁。perMachine是否全機器安裝。false 表示裝到當前用戶目錄也就是 %LOCALAPPDATA%\Programstrue 需要管理員權限裝到 Program Files。allowElevation配合 perMachine 使用false 時不彈 UAC我一般保持 true避免以后切到 perMachine 時被權限卡住。allowToChangeInstallationDirectory不寫的話用戶安裝時看不到目錄選擇頁。artifactName輸出安裝包的名字。默認是${productName} Setup ${version}.exe我習慣用${productName}-Setup-${version}.${ext}CI 腳本好按模式匹配文件。deleteAppDataOnUninstall卸載時是否清掉用戶數(shù)據(jù)。這個默認 false建議不要開用戶卸載應用不意味著要刪掉本地數(shù)據(jù)。include自定義腳本入口后面單獨說。從實戰(zhàn)角度最影響安裝體驗的是 oneClick 和 perMachine 的組合。oneClicktrue 時安裝過程沒有任何選擇頁用戶連目錄都改不了oneClickfalse 時才能把“安裝選項”頁面釋放出來。產(chǎn)品經(jīng)理要求“用戶可選安裝目錄”時必須把 oneClick 關掉同時把 allowToChangeInstallationDirectory 打開缺一個都不生效。3.3 中文環(huán)境、快捷方式與卸載行為Electron 打包在中文 Windows 下最常見的兩個問題第一安裝路徑。productName 如果帶中文生成的默認安裝目錄就會帶中文。electron-builder 對中文目錄本身沒限制但如果 app.asar 里有原生 C 模塊某些模塊對路徑編碼敏感會出現(xiàn)模塊加載失敗。我一般把內(nèi)部用的 name 保持英文productName 按產(chǎn)品對外名稱走安裝體驗交給 installerLanguages 去控制系統(tǒng)語言。第二快捷方式殘留。shortcutName 決定開始菜單和桌面的名字同一臺機器如果裝過多個版本舊的快捷方式可能不會被卸載器清干凈菜單里出現(xiàn)兩個“DemoApp”。這種情況多數(shù)來自卸載時新老版本混裝卸載器按新版本的 uninstall 注冊表去處理舊目錄結果刪不干凈。我會先讓測試機做一次完整卸載再重裝確認不是安裝器覆蓋邏輯的問題再去追快捷方式來源。NSIS 的卸載器還會調(diào)用 electron-builder 生成的 uninstaller 腳本刪除開始菜單目錄和快捷方式。如果你的版本升級后卸載找不到舊版本多半是安裝目錄里新舊版本文件混著建議先卸載再重裝別直接覆蓋。3.4 一個自定義腳本的常見用法include 自定義腳本一般是改安裝完成后的動作比如寫注冊表或提示重啟。一個最小示例!macro customInstall WriteRegStr HKCU Software\DemoApp installed true !macroendcustomInstall 是 electron-builder 的 NSIS 模板向外暴露的宏不需要你懂整個 NSIS只要照著這個宏往里塞指令就行。把這個文件路徑填到 include 里構建時模板會自動拼進去。NSIS 腳本里路徑有空格要加引號用到 $INSTDIR 時要小心轉義這些錯誤在 electron-builder 日志里看不到出錯時非常難查。我一般只在需要寫注冊表、改 shell 行為時才加 include平時的安裝目錄控制都靠 JSON 配置不加腳本少一個黑盒就少一份風險。4. winCodeSign-2.6.0代碼簽名與 SmartScreen 信任鏈實操4.1 winCodeSign 裝了什么、何時被調(diào)用winCodeSign-2.6.0 是 electron-builder 用于 Windows 代碼簽名的一組工具集合里面是 signtool.exe 之類的可執(zhí)行文件和配套 dll。打包 Windows 目標時electron-builder 會先解壓 winCodeSign 到緩存把證書文件和密碼塞給它的 signtool對 win-unpacked 里的 exe、dll 以及最終的 setup.exe 逐個簽名。很多人以為簽名只針對 setup.exe其實 electron-builder 會對多個文件簽一遍主進程 exe、渲染進程里可能存在的 dll、升級用的 exe最后一個才是安裝器外殼。簽名順序先內(nèi)后外一旦順序反了Windows 會認為安裝包內(nèi)部組件來源不一致SmartScreen 反而更容易跳警告。4.2 自動簽名配置CSC_LINK 與 CSC_KEY_PASSWORDelectron-builder 的簽名不寫在 package.json 里而是走環(huán)境變量CSC_LINK證書文件路徑可以是 pfx、p12也可以是一個 base64 編碼的字符串。CSC_KEY_PASSWORD證書私鑰密碼。在 Windows PowerShell 里這樣設$env:CSC_LINK C:\certs\company.pfx $env:CSC_KEY_PASSWORD your-password npx electron-builder --win nsis --x64在 Git Bash 里export CSC_LINK/c/certs/company.pfx export CSC_KEY_PASSWORDyour-password npx electron-builder --win nsis --x64electron-builder 在打包流程的 sign 階段讀這兩個變量。如果 CSC_LINK 沒設置它會跳過簽名直接產(chǎn)出未簽名的 exe打包不報錯。這就是為什么新手沒配證書也能正常出安裝包只是裝上后 SmartScreen 會跳提示。CSC_LINK 另一個反直覺的點是它接受路徑也接受證書內(nèi)容的 base64。CI 里不想把 pfx 塞進代碼倉庫就先對證書做 base64 編碼再放到環(huán)境變量base64 -w 0 company.pfx把輸出的長字符串填給 CSC_LINK。注意 base64 字符串里不能有換行否則 signtool 解析會失敗這是 CI 上常見的簽名翻車點。4.3 手動簽名兜底什么時候繞過 electron-builder 的簽名有一種場景你想用腳本統(tǒng)一簽名而不是讓 electron-builder 每次自動簽。比如證書在遠程簽名服務上或者 electron-builder 自動簽名時不支持你指定的時間戳服務器。這時候可以先關掉自動簽名打包完成后自己調(diào)用 signtool。在 package.json 的 build.win 里加win: { sign: ./build/sign.js }sign.js 是一個導出函數(shù)的模塊electron-builder 會調(diào)用它代替內(nèi)置簽名邏輯。更簡單的做法是保持默認自動簽名等打包完成后對最終 exe 再用 signtool 簽一次。但同一個文件簽兩次不會覆蓋之前的簽名如果你的兩次證書鏈不一致SmartScreen 反而更亂。我建議用不到自定義簽名時別碰 sign 字段等真正需要時再動手。4.4 時間戳服務器與雙重簽名簽名參數(shù)對照表signtool 的核心參數(shù)長這樣signtool sign /f company.pfx /p your-password \ /tr http://timestamp.digicert.cn /td sha256 /fd sha256 \ /a DemoApp-Setup-1.0.0.exe參數(shù)作用常見坑/f指定證書文件路徑含空格要用引號包住/p證書密碼密碼帶特殊字符時注意轉義/trRFC3161 時間戳服務器地址必須用支持 sha256 的服務器/td時間戳摘要算法不寫時部分 Windows 版本認不出/fd文件摘要算法sha256 是常見選擇/a自動選擇最佳證書機器上證書多時建議用 /sha1 精確指定時間戳的意義是讓簽名在證書過期后仍然有效。只簽文件名、不寫 /tr簽名本身有效但 Windows 會顯示“數(shù)字簽名無效或時間戳不準”。我一般在打包機上固定一個時間戳服務器避免每次打包時來回換。簽名完成后用下面的命令驗證signtool verify /v /pa DemoApp-Setup-1.0.0.exe輸出里能看到簽名者、證書鏈、時間戳狀態(tài)。如果證書鏈完整SmartScreen 的提示會輕很多如果驗證結果是“證書鏈不完整”說明證書是自簽的或者中間證書沒裝全需要先解決證書本身的問題。5. 打包全家桶避坑記錄緩存、版本不匹配、簽名失敗5.1 卡在 Downloading electron-v8.5.5-win32-x64.zip現(xiàn)象執(zhí)行 electron-builder 后日志停在 “Downloading electron-v8.5.5-win32-x64.zip” 十幾分鐘不動或者反復下到一半就失敗。原因electron-builder 默認從 GitHub release 拉 Electron 二進制源站響應慢加上 zip 體積大很容易超時。不是項目配置的問題是下載環(huán)節(jié)扛不住波動。解決先把 zip 手動下載回來放到 %LOCALAPPDATA%\electron\Cache 目錄下。文件命名必須嚴格是 electron-v8.5.5-win32-x64.zip后綴不一致 electron-builder 認不出來。另一個做法是給 Electron 二進制設置鏡像地址export ELECTRON_MIRRORhttps://npmmirror.com/mirrors/electron/設置后 electron-builder 會自動從鏡像地址拼出完整下載路徑。注意這個鏡像只覆蓋 Electron 運行時不影響 nsis 和 winCodeSign 的下載源后兩者走的是另一處二進制鏡像不同 electron-builder 版本的變量名略有差異以日志里展示的下載 URL 為準。我養(yǎng)成的習慣是先看日志里的 Downloading 后面跟的 URL用它判斷當前走的是哪個源手動下載時也讓下載工具保存的文件名與 URL 最后一段完全一致。5.2 nsis 版本不匹配報錯現(xiàn)象報錯 “Cannot find nsis-3.0.4.2” 或 “Downloading nsis-3.0.4.2 failed”。也有反過來本地緩存里有 nsis-3.0.4.2但 electron-builder 要的是別的版本。原因electron-builder 的版本決定它要哪一個 nsis。本地緩存里同時躺著多個版本時electron-builder 只認自己要的那一個。緩存目錄被換位置、權限不對也會導致它找不到。解決直接清空對應緩存目錄讓它重新下載Remove-Item -Recurse -Force $env:LOCALAPPDATA\electron-builder\Cache\nsis npx electron-builder --win nsis --x64如果內(nèi)網(wǎng)能下載也可以手動放置 nsis-3.0.4.2.7z。手動放緩存要同時檢查兩樣東西7z 包本身以及它解壓后的目錄。electron-builder 解壓到一半失敗時會留下殘缺目錄這時候即使 7z 文件在構建照樣報錯。清空重下最省事別在這種地方節(jié)省時間。5.3 簽名失敗退出代碼 1現(xiàn)象打包進行到 sign 階段后失敗日志出現(xiàn) “Exit code: 1”后面跟一行 SignTool Error 或 crypt32 相關提示但不會直接告訴你密碼錯沒錯。原因winCodeSign 里的 signtool 拿到證書后讀不了私鑰。常見四條路證書密碼寫錯、證書文件本身不是 pfx/p12 而是一堆 DER 文件、證書已過期、緩存里的 winCodeSign 解壓不全。解決先不看 electron-builder 日志直接拿 winCodeSign 里的 signtool 試一次 $env:LOCALAPPDATA\electron-builder\Cache\winCodeSign\winCodeSign-2.6.0\windows-10\signtool.exe sign /f C:\certs\company.pfx /p guess-password /tr http://timestamp.digicert.cn /td sha256 /fd sha256 C:\demo.exe不帶 electron-builder 的包裝signtool 給出的錯誤信息直白得多密碼錯會說 “The password you specified is incorrect”文件格式不對會說 “Cannot open the file”。血淚經(jīng)驗證書文件別放在含中文或空格的路徑下signtool 對這類路徑的兼容性不穩(wěn)定先復制到 C:\certs 再簽名能少踩一半的坑。5.4 SmartScreen“未知發(fā)布者”但簽名驗證通過現(xiàn)象打包成功簽名也驗證通過但用戶機器上 Windows 仍然提示“Windows 已保護你的電腦”紅色界面。原因SmartScreen 的信譽不是只看“有沒有簽名”還看簽名的根證書是否在系統(tǒng)信任區(qū)、證書是否 EV、這個 exe 在信譽庫里有沒有歷史記錄。新證書、普通 OV 證書第一次出現(xiàn)提示是正常的。解決先確認簽名是不是真的進了安裝包signtool verify /v /pa DemoApp-Setup-1.0.0.exe看到簽發(fā)者是機構證書就可以把鍋歸到信譽積累而不是打包鏈路。要消除這種提示通常只能上 EV 證書并確保安裝包經(jīng)過了帶時間戳的 sha256 簽名。如果是自簽證書SmartScreen 怎么調(diào)優(yōu)都會攔。另一個可查的點是時間戳如果簽名時 /td 沒寫 sha256老時間戳服務可能簽出 sha1 時間戳新版系統(tǒng)上驗證狀態(tài)會顯示“可重新簽名時間”的灰色狀態(tài)用戶看到就是不信任。把 /tr /td 兩個參數(shù)補齊很多“簽名有效但體驗差”的問題會消失。5.5 清理盤符后打包速度從 3 分鐘退回 30 分鐘現(xiàn)象某天清理 C 盤剩余空間后打包從 3 分鐘變成 30 分鐘日志里重新出現(xiàn) Downloading 全家桶。原因%LOCALAPPDATA% 在 C 盤electron 和 electron-builder 的緩存目錄被掃盤工具清掉了。三個文件一旦沒了electron-builder 不認識本地還有副本只好重新下載。解決在專用打包機和 CI 上把緩存目錄遷出 C 盤。我自己的打包機把緩存目錄指向 D 盤重裝系統(tǒng)后只需要把 D 盤里的目錄拷回來。具體做法下一章給出核心是讓緩存目錄離開系統(tǒng)盤。不要以為這是偶然很多人第一次清理系統(tǒng)盤時就把 electron-builder 的緩存當成垃圾清掉了回頭打包慢得像換了一臺機器這真的不是玄學。6. 讓全家桶一次到位離線緩存與打包熱遷移技巧先說一個被驗證過很多次的結論electron-builder 的下載慢問題八成能用緩存預置解決。做法是把三個文件固定成一個可復制的目錄新機器和 CI 上直接放過去不用每次等它重下。第一步把現(xiàn)有緩存里的三件套歸檔到一起。以 Windows 打包機為例$cacheRoot $env:LOCALAPPDATA Copy-Item $cacheRoot\electron\Cache\electron-v8.5.5-win32-x64.zip D:\electron-pack-cache Copy-Item $cacheRoot\electron-builder\Cache\nsis\nsis-3.0.4.2.7z D:\electron-pack-cache Copy-Item $cacheRoot\electron-builder\Cache\winCodeSign D:\electron-pack-cache -Recurse理論上只要這三樣版本對齊新機器上把文件放到對應位置electron-builder 就會直接復用網(wǎng)絡波動不再影響產(chǎn)線。為了不讓系統(tǒng)盤清理誤傷我會把緩存根目錄遷出 C 盤$env:ELECTRON_BUILDER_CACHE D:\electron-pack-cache設置后 electron-builder 優(yōu)先認這個目錄作為緩存根目錄。注意這個環(huán)境變量控制的是 nsis 和 winCodeSign 的位置Electron 二進制的緩存位置由 ELECTRON_CACHE 控制兩個變量一起設全家桶才不會散。我踩過一次教訓把 ELECTRON_BUILDER_CACHE 指向了一個帶中文的路徑某些版本解析時把路徑轉成 URL中文被解析成亂碼緩存命中失敗構建回退到重新下載。后來一律用純英文路徑。另外別把 electron 緩存和 electron-builder 緩存疊在同一個子目錄兩個包對目錄層級的要求不同放錯層級的結果是沒被識別日志照樣去下載看起來像是玄學其實就是路徑層級不對。驗證緩存是否命中不需要等打包結束?？慈罩厩懊娴南螺d環(huán)節(jié)如果在命令輸出里找不到 Downloading electron / Downloading nsis / Downloading winCodeSign 三項而是直接進入 Building 階段說明全家桶命中。我最后想分享的習慣是把“緩存是否命中”當成打包速度問題的第一排查點每次打包前先看這一項比反復換下載源更靠得住。希望幫到你。本文還有配套的精品資源點擊獲取