做過(guò) Electron 開(kāi)發(fā)的人基本都逃不過(guò)這一關(guān)寫(xiě)代碼一時(shí)爽一到打包就翻車。尤其是 Windows 平臺(tái)本地 dev 跑得好好的要產(chǎn)出能發(fā)給別人的 exe中間的坑能寫(xiě)一本小冊(cè)子。我這些年幫團(tuán)隊(duì)處理過(guò)不少 Windows 下的 Electron 打包問(wèn)題也踩過(guò)無(wú)數(shù)回自己埋的雷從 electron-builder 配置到 serialport 這類原生模塊從 pnpm 兼容到 fpm 報(bào)錯(cuò)幾乎都經(jīng)歷了一遍。今天把 Windows 平臺(tái) Electron 打包的整套思路、核心配置和排查經(jīng)驗(yàn)一次性講清楚給正在被安裝包折磨的朋友一條能直接走通的路。這篇文章適合兩類人一是用 Electron 做桌面應(yīng)用、準(zhǔn)備向 Windows 用戶分發(fā)安裝包的開(kāi)發(fā)者二是已經(jīng)在打包但卡在白屏、原生模塊報(bào)錯(cuò)、安裝器被攔截等具體問(wèn)題上的同學(xué)。看完你至少能搞定三件事選對(duì)打包工具、寫(xiě)出一份可靠的 Windows 打包配置、遇到高頻報(bào)錯(cuò)時(shí)知道先查哪里。1. 先選對(duì)路子Windows 下 Electron 打包方案怎么定很多人一上來(lái)就搜Electron 打包搜出來(lái)一堆工具反而懵了。其實(shí) Windows 平臺(tái)常用的方案就那么幾種區(qū)別主要在于最終產(chǎn)物形態(tài)、配置復(fù)雜度和對(duì)原生模塊的支持情況。這里先把這個(gè)選擇題做對(duì)后面少走一半彎路。1.1 electron-packager、electron-builder、electron-forge 怎么選社區(qū)里現(xiàn)在最常被提到的三個(gè)工具是 electron-packager、electron-builder 和 electron-forge。它們不是一個(gè)東西適合的場(chǎng)景也不太一樣。electron-packager 是最早的一批打包工具核心能力就是把你項(xiàng)目的文件和一個(gè)對(duì)應(yīng)平臺(tái)的 Electron 二進(jìn)制拼在一起輸出一個(gè)可執(zhí)行文件夾。你雙擊里面的 exe 能跑但沒(méi)有安裝界面也沒(méi)有開(kāi)始菜單快捷方式。它適合極早期驗(yàn)證或者企業(yè)內(nèi)部直接發(fā)綠色目錄的場(chǎng)景。不過(guò)指望它做出正式的分發(fā)安裝包還得再套別的工具比較繞。electron-forge 是 Electron 官方后來(lái)推的集成方案把初始化、開(kāi)發(fā)、打包、發(fā)布串成一條鏈路默認(rèn)集成了 Webpack 或 Vite 模板。如果你是完全新開(kāi)項(xiàng)目用它起步挺舒服。但它的封裝更深遇到 Windows 安裝包定制需求時(shí)想改 NSIS 這類底層行為往往沒(méi)有 electron-builder 那么直觀。electron-builder 是我個(gè)人長(zhǎng)期在用的方案。它不是官方出的但生態(tài)非常成熟配置文件集中在一個(gè)字段或一個(gè) yml 里能直接產(chǎn)出 NSIS 安裝包、portable 免安裝 exe、zip 壓縮包同時(shí)也覆蓋 macOS 的 dmg 和 Linux 的 AppImage、deb、rpm。對(duì) Windows 平臺(tái)來(lái)說(shuō)它的 NSIS 定制能力和原生模塊處理機(jī)制目前是三個(gè)方案里最讓我省心的。工具主要產(chǎn)物配置復(fù)雜度原生模塊支持多平臺(tái)覆蓋electron-packager綠色可執(zhí)行目錄低需自己 rebuild支持electron-builder安裝包 綠色目錄中install-app-deps 自動(dòng)處理支持electron-forge安裝包 可執(zhí)行目錄中集成 rebuild支持1.2 我一直用 electron-builder 的三個(gè)理由第一配置集中。我能用一份 electron-builder.yml 同時(shí)控制 Windows、Linux、macOS 的打包行為不需要在各個(gè)工具腳本之間來(lái)回跳。對(duì)要長(zhǎng)期維護(hù)的項(xiàng)目來(lái)說(shuō)這種一處配置管全平臺(tái)的方式非常省事。第二對(duì) Windows 安裝包的控制力足夠強(qiáng)。electron-builder 底層接 NSIS我可以精確控制安裝包是一鍵安裝還是傳統(tǒng)向?qū)б灰试S用戶改安裝目錄要不要?jiǎng)?chuàng)建桌面快捷方式甚至安裝后的卸載程序行為。這些看起來(lái)是小細(xì)節(jié)但對(duì)最終用戶體驗(yàn)影響很大。第三原生模塊處理省心。Windows 下最常出問(wèn)題的就是 serialport、sqlite3 這類帶 .node 文件的原生模塊。electron-builder 提供了install-app-deps命令會(huì)自動(dòng)讀取你項(xiàng)目里的 Electron 版本并把原生模塊重新編譯成匹配 Electron ABI 的版本。這個(gè)機(jī)制幫我解決過(guò)大量打包后模塊崩潰的問(wèn)題。1.3 先理清前端構(gòu)建和 Electron 打包的分工很多人容易把前端構(gòu)建和Electron 打包混在一起。實(shí)際它們是兩個(gè)階段。前端構(gòu)建階段用 Vite、Webpack 這類工具把你的 Vue、React 代碼編譯成靜態(tài)資源輸出到一個(gè) dist 目錄。Electron 打包階段electron-builder 只負(fù)責(zé)把主進(jìn)程代碼、預(yù)加載腳本、前端靜態(tài)資源、依賴 node_modules 和 Electron 運(yùn)行時(shí)組裝成安裝包。所以項(xiàng)目里通常有兩套配置并存一套是前端腳手架的構(gòu)建配置一套是 electron-builder 的打包配置。兩者之間唯一的聯(lián)系就是 electron-builder 的 files 配置里要包含前端構(gòu)建產(chǎn)物。想清楚這一層后面遇到打包后白屏資源找不到這類問(wèn)題時(shí)就能快速定位是構(gòu)建階段的問(wèn)題還是打包階段的問(wèn)題。2. 開(kāi)打前先處理好三件事環(huán)境、包管理器、ABI正式跑打包命令之前有三大前置問(wèn)題必須先解決。很多人在這一步就卡住了而且報(bào)錯(cuò)信息往往容易誤導(dǎo)人比如明明只是網(wǎng)絡(luò)問(wèn)題卻顯示成下載失敗明明只是 pnpm 的目錄結(jié)構(gòu)與打包器不兼容卻提示找不到模塊。2.1 Windows 上真正需要裝的工具只有這幾樣打包 Electron 應(yīng)用本身不需要裝什么特殊環(huán)境Node.js 是基礎(chǔ)。我建議用 Node.js 的 LTS 版本比如 18 或 20太老的版本跑不動(dòng)新版 electron-builder太新的版本有時(shí)會(huì)出現(xiàn)一些依賴兼容問(wèn)題。如果你的項(xiàng)目里包含原生模塊那 Windows 上還需要 Visual Studio Build Tools。以前的教程經(jīng)常提windows-build-tools一鍵腳本但現(xiàn)在官方更推薦直接安裝 Visual Studio 2022 Build Tools安裝時(shí)勾選使用 C 的桌面開(kāi)發(fā)工作負(fù)載。否則執(zhí)行 install-app-deps 時(shí)node-gyp 會(huì)報(bào)gyp ERR! find Python或者找不到 MSVC 編譯器。另外 Git 不是必須的但很多依賴源安裝時(shí)需要它裝了能少一些莫名其妙的下載失敗問(wèn)題。代碼簽名工具signtool如果你不配證書(shū)暫時(shí)用不上后面第 5.4 節(jié)會(huì)專門(mén)講 SmartScreen 的問(wèn)題。2.2 用 pnpm 的項(xiàng)目必須改 node-linker 配置我現(xiàn)在的新項(xiàng)目基本都是 pnpm 管理依賴因?yàn)槭〈疟P(pán)、安裝快。但 electron-builder 對(duì) pnpm 的支持一直有歷史遺留問(wèn)題核心原因在于 pnpm 默認(rèn)使用符號(hào)鏈接結(jié)構(gòu)存放 node_modules而不是像 npm 那樣平鋪。electron-builder 在收集依賴時(shí)可能無(wú)法按預(yù)期找到某個(gè)包表現(xiàn)出來(lái)就是打包后應(yīng)用啟動(dòng)報(bào)找不到模塊 xx。解決辦法是在項(xiàng)目根目錄的.npmrc里加上這么一行node-linkerhoisted如果你用的 pnpm 版本較老也可以用shamefully-hoisttrue效果類似都是讓 node_modules 結(jié)構(gòu)更接近 npm 的平鋪方式。改完之后記得刪掉 node_modules重新執(zhí)行一次完整安裝否則配置不生效。注意不要為了省事跳過(guò)這一步。我見(jiàn)過(guò)有人用 pnpm 默認(rèn)配置硬打結(jié)果在本機(jī)怎么測(cè)都正常換一臺(tái)干凈機(jī)器裝上安裝包就白屏或缺模塊最后排查了半天才發(fā)現(xiàn)是依賴結(jié)構(gòu)問(wèn)題。2.3 native 模塊能不能活下來(lái)全看 Node ABI 對(duì)不對(duì)ABI 這個(gè)詞聽(tīng)起來(lái)深其實(shí)可以這么理解Node.js 原生模塊編譯出來(lái)的是一個(gè) .node 文件它和特定版本的 Node 運(yùn)行時(shí)之間存在一套固定的二進(jìn)制接口約定。Electron 內(nèi)置的 Node 版本并不等于你本機(jī)裝的 Node 版本所以直接用你本機(jī)的 node-gyp 編譯出來(lái)的原生模塊放進(jìn) Electron 里運(yùn)行十有八九會(huì)崩。這是 serialport、robotjs、sqlite3 這類庫(kù)打包后報(bào)錯(cuò)的根本原因。正確做法不是手動(dòng) node-gyp rebuild而是使用 electron-builder 提供的命令npx electron-builder install-app-deps它會(huì)自動(dòng)讀取 package.json 里的 electron 版本把 dependencies 中的原生模塊重新編譯成匹配 Electron ABI 的版本。每次升級(jí) Electron 或改了原生模塊版本后都要重新跑一次這個(gè)命令否則早晚會(huì)踩Module did not self-register這類錯(cuò)誤。3. 核心配置逐段拆解用 electron-builder.yml 管住一切環(huán)境問(wèn)題解決之后就可以進(jìn)入真正的核心環(huán)節(jié)了寫(xiě)配置。electron-builder 支持把配置寫(xiě)在 package.json 的 build 字段里也支持獨(dú)立文件。我推薦獨(dú)立拆出一個(gè) electron-builder.yml因?yàn)榇虬渲迷陧?xiàng)目里會(huì)越加越多放在 package.json 里會(huì)顯得臃腫。3.1 一份能直接用的 Windows 打包配置下面是一份我在 Windows 項(xiàng)目里常駐的配置模板覆蓋了常規(guī)桌面應(yīng)用的需求appId: com.example.myapp productName: MyApp directories: output: release buildResources: build files: - dist-electron/** - dist/** - package.json asar: true asarUnpack: - **/*.node win: icon: build/icon.ico target: - target: nsis arch: - x64 nsis: oneClick: false perMachine: false allowToChangeInstallationDirectory: true createDesktopShortcut: true createStartMenuShortcut: true shortcutName: MyApp artifactName: ${productName}-${version}-${arch}.${ext} compression: maximum逐段說(shuō)幾個(gè)關(guān)鍵點(diǎn)。appId 是應(yīng)用唯一標(biāo)識(shí)建議用反域名格式。productName 是安裝完成后在系統(tǒng)里顯示的應(yīng)用名也是安裝包文件名的組成部分。directories.output 指定安裝包輸出目錄我習(xí)慣用 release這樣不會(huì)和前端構(gòu)建產(chǎn)物目錄混在一起。files 是打包內(nèi)容的白名單非常重要。這里我只讓dist-electron主進(jìn)程構(gòu)建產(chǎn)物、dist前端靜態(tài)資源和 package.json 進(jìn)包。如果你不加這個(gè)字段electron-builder 會(huì)把整個(gè)項(xiàng)目目錄都收進(jìn)去本機(jī) node_modules 里的開(kāi)發(fā)依賴、測(cè)試文件、.env 全都可能被塞進(jìn)安裝包既臃腫又危險(xiǎn)。asar 字段默認(rèn)就是 true作用是把應(yīng)用代碼打成一個(gè) asar 壓縮包保護(hù)源碼結(jié)構(gòu)、減少文件數(shù)量。但原生模塊需要單獨(dú)處理所以加了asarUnpack把 .node 文件排除在 asar 之外。后面 serialport 那節(jié)會(huì)繼續(xù)展開(kāi)。3.2 Windows 目標(biāo)格式和架構(gòu)怎么選win.target 可以指定多個(gè)目標(biāo)和架構(gòu)。最常見(jiàn)的三個(gè)目標(biāo)nsis標(biāo)準(zhǔn) Windows 安裝程序支持安裝目錄選擇、快捷方式創(chuàng)建、卸載入口適合正式分發(fā)。portable免安裝的單 exe運(yùn)行時(shí)會(huì)自解壓到臨時(shí)目錄適合給非技術(shù)用戶快速體驗(yàn)。zip綠色壓縮包適合企業(yè)管理員批量部署或開(kāi)發(fā)者自己分發(fā)。架構(gòu)方面目前 x64 是主流絕大多數(shù) Windows 10/11 用戶都是 64 位系統(tǒng)。如果用戶群體里還有大量老舊電腦可以同時(shí)打 x64 和 ia32。arm64 目前有需求但不多主要針對(duì) Surface Pro X 這類設(shè)備。建議用一個(gè)變量控制避免把架構(gòu)寫(xiě)死在代碼里win: target: - target: nsis arch: - x64artifactName 里的${arch}就是用來(lái)區(qū)分架構(gòu)的否則 x64 和 ia32 版本同名發(fā)布時(shí)就亂了。3.3 NSIS 安裝體驗(yàn)調(diào)優(yōu)從能裝到好裝NSIS 配置是 Windows 安裝包體驗(yàn)的關(guān)鍵。很多人打出來(lái)的安裝包雙擊后直接裝了用戶連裝到哪里都不知道卸載時(shí)也找不到入口體驗(yàn)很差。我一般會(huì)關(guān)掉 oneClick開(kāi)啟傳統(tǒng)安裝向?qū)Ｊ健neClick 設(shè)為 false 后用戶安裝時(shí)會(huì)有選擇安裝目錄是否創(chuàng)建快捷方式這些步驟對(duì)普通用戶更友好。allowToChangeInstallationDirectory 設(shè)為 true配合前面那個(gè)設(shè)置用戶才能真正改安裝目錄。perMachine 我通常設(shè)置為 false這樣默認(rèn)安裝到當(dāng)前用戶目錄不需要管理員權(quán)限也不會(huì)觸發(fā) UAC 彈窗如果產(chǎn)品需要安裝到 Program Files那就要設(shè)為 true并接受 UAC 提權(quán)。還有一個(gè)容易忽略的點(diǎn)shortcutName 最好和 productName 保持一致否則用戶安裝完找不到應(yīng)用名字對(duì)應(yīng)的快捷方式會(huì)以為安裝失敗了。注意NSIS 安裝路徑盡量不要讓用戶選中文或特殊字符目錄。雖然 Windows 能創(chuàng)建中文明目錄但后續(xù)應(yīng)用讀寫(xiě)文件時(shí)個(gè)別原生庫(kù)會(huì)在路徑編碼上出問(wèn)題這個(gè)坑比較隱蔽。4. 完整實(shí)操流程從項(xiàng)目目錄到能分發(fā)的安裝包配置寫(xiě)完之后實(shí)際操作其實(shí)就幾條命令的事但每一步都有值得注意的細(xì)節(jié)。我第一次打 Windows 包時(shí)因?yàn)椴恢酪?win-unpacked 目錄直接在安裝包裝上踩了半小時(shí)后來(lái)逐步形成了一套標(biāo)準(zhǔn)流程。4.1 首次打包兩條命令跑通先看 unpacked 目錄安裝 electron-builder 后先在 package.json 里配好腳本{ scripts: { build:app: vite build, pack:dir: electron-builder --dir, pack:win: electron-builder --win --x64 } }第一次執(zhí)行打包時(shí)不建議直接打安裝包而是先跑electron-builder --dir。這個(gè)命令不會(huì)生成 NSIS 安裝程序只會(huì)生成一個(gè)win-unpacked目錄里面就是解壓后的完整應(yīng)用。你可以直接運(yùn)行里面的 exe驗(yàn)證主進(jìn)程邏輯、前端資源、原生模塊是否正常。確認(rèn) win-unpacked 里的應(yīng)用沒(méi)問(wèn)題后再執(zhí)行pack:win產(chǎn)出正式安裝包。這樣能把應(yīng)用本身有問(wèn)題和安裝包制作有問(wèn)題兩個(gè)環(huán)節(jié)隔離開(kāi)排查時(shí)思路清晰很多。首次打包還需要下載 Electron 二進(jìn)制和 NSIS 工具這一步最容易卡住。如果長(zhǎng)時(shí)間停留在下載階段可以先設(shè)置鏡像源$env:ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/ $env:ELECTRON_BUILDER_BINARIES_MIRROR https://npmmirror.com/mirrors/electron-builder-binaries/設(shè)置后重新執(zhí)行打包命令下載進(jìn)度會(huì)明顯變快。下載完的文件會(huì)緩存在%LOCALAPPDATA%\electron-builder\Cache后續(xù)打包不會(huì)再重復(fù)下載。4.2 圖標(biāo)、版本號(hào)和文件屬性一次配到位如果你不配置圖標(biāo)安裝包和應(yīng)用 exe 會(huì)使用 Electron 默認(rèn)圖標(biāo)一眼就能看出來(lái)不是專業(yè)產(chǎn)物。Windows 平臺(tái)對(duì)圖標(biāo)格式有要求必須用 .ico 文件且建議包含 256x256 尺寸。很多設(shè)計(jì)工具直接導(dǎo)出的 png 不能直接用得先轉(zhuǎn)成 ico。拿到 icon.ico 后放到 build 目錄下在 win 配置里指定win: icon: build/icon.ico版本號(hào)方面electron-builder 會(huì)自動(dòng)讀取 package.json 里的 version 字段所以一定讓 version 和應(yīng)用實(shí)際版本同步。除此之外可以通過(guò)win.signAndEditExecutable相關(guān)的配置來(lái)寫(xiě)入文件屬性信息比如公司名、產(chǎn)品描述。做企業(yè)內(nèi)部分發(fā)時(shí)這些細(xì)節(jié)會(huì)讓系統(tǒng)屬性里的信息看起來(lái)正規(guī)很多。4.3 serialport 這類原生模塊的正確打包姿勢(shì)serialport 是很多硬件桌面項(xiàng)目繞不開(kāi)的庫(kù)也是 Electron 打包問(wèn)題里出現(xiàn)頻率最高的一類。它的問(wèn)題集中在兩個(gè)點(diǎn)ABI 編譯和文件路徑。ABI 編譯前面講過(guò)打包前一定要執(zhí)行npx electron-builder install-app-deps。不要手動(dòng)執(zhí)行 npm 的 rebuild否則編譯出來(lái)的版本只匹配本機(jī) Node不匹配 Electron。文件路徑問(wèn)題在于serialport 編譯出來(lái)的 .node 文件如果被打進(jìn) asar 壓縮包運(yùn)行時(shí)無(wú)法直接加載。所以配置里要加 unpack 規(guī)則asarUnpack: - **/*.node - **/node_modules/serialport/**這里把 serialport 整個(gè)模塊目錄都排除出 asar 了確保它的 .node 文件和動(dòng)態(tài)依賴能被安全訪問(wèn)。改完配置后重新打包一般能解決大多數(shù) serialport 相關(guān)報(bào)錯(cuò)。如果還是不行多半是 serialport 的依賴?yán)锶鄙?vcruntime140.dll 這類運(yùn)行庫(kù)或者安裝了非官方精簡(jiǎn)版系統(tǒng)的用戶環(huán)境里缺運(yùn)行庫(kù)。遇到這種情況可以把需要的 dll 放到 extraResources再在應(yīng)用啟動(dòng)時(shí)手動(dòng)加載但這種情況相對(duì)少見(jiàn)。4.4 白屏和布局異常絕大多數(shù)卡在這里Electron 應(yīng)用打包后白屏是出現(xiàn)率最高的前端問(wèn)題十次里有八次是路由模式導(dǎo)致的。開(kāi)發(fā)環(huán)境用的是 localhost 地址路由用 createWebHistory 沒(méi)問(wèn)題但打包后應(yīng)用通過(guò) file:// 協(xié)議加載本地文件history 路由會(huì)直接失效頁(yè)面空白。解決辦法有兩個(gè)簡(jiǎn)單粗暴的是把前端路由改成 createHashHistory另一種是保留 history 模式但把前端構(gòu)建的 publicPath 配成相對(duì)路徑并在 Electron 里用自定義協(xié)議加載。前者實(shí)現(xiàn)快后者體驗(yàn)更接近標(biāo)準(zhǔn) web 應(yīng)用都可以。熱詞里還有vue 打包后 布局異常這類問(wèn)題。我排查過(guò)的一個(gè)典型案例是CSS 里引用的圖片路徑是絕對(duì)路徑打包后在本地 file:// 協(xié)議下加載失敗導(dǎo)致樣式失效、布局全亂。把構(gòu)建配置里的 base 或 publicPath 改成相對(duì)路徑絕大多數(shù)這類問(wèn)題都能解決。所以遇到白屏或布局異常先別急著懷疑 electron-builder 配置重點(diǎn)檢查三樣?xùn)|西路由模式、構(gòu)建 publicPath、資源引用路徑。用electron-builder --dir生成目錄后可以直接在本地運(yùn)行 exe打開(kāi)開(kāi)發(fā)者工具看 Console 報(bào)錯(cuò)比反復(fù)打安裝包高效很多。5. 高頻報(bào)錯(cuò)與排查實(shí)錄直接對(duì)著癥狀找答案下面這些報(bào)錯(cuò)和現(xiàn)象是 Windows 打包里最常見(jiàn)的。我把它們整理成問(wèn)題排查表你在實(shí)際操作中可以直接對(duì)照省掉到處搜的功夫。5.1 卡在下載 winCodeSign / nsis是網(wǎng)絡(luò)而不是配置錯(cuò)了很多初次打包的人看到Downloading winCodeSign或Downloading nsis卡住以為配置寫(xiě)錯(cuò)了實(shí)際上只是 electron-builder 從 GitHub Releases 下載輔助工具失敗或特別慢。這類問(wèn)題的典型日志是反復(fù)重試后報(bào) timeout 或 404。解決辦法就是前面提到的設(shè)置鏡像源。如果公司內(nèi)網(wǎng)有統(tǒng)一的 npm 鏡像也可以把 electron 和 electron-builder 的二進(jìn)制鏡像一起配置進(jìn)系統(tǒng)的環(huán)境變量團(tuán)隊(duì)所有人共享。另外既然下載工具卡頓是常態(tài)我在團(tuán)隊(duì)內(nèi)部會(huì)建議維護(hù)一個(gè)打包緩存目錄的備份。把%LOCALAPPDATA%\electron-builder\Cache里已經(jīng)下載好的文件壓縮存檔換新機(jī)器時(shí)直接解壓到對(duì)應(yīng)目錄能省不少時(shí)間。5.2 遇到 fpm 相關(guān)報(bào)錯(cuò)先別急著重裝環(huán)境fpm 報(bào)錯(cuò)在很多打包場(chǎng)景里都會(huì)出現(xiàn)但它往往不是因?yàn)槟愕?Electron 配置有誤而是因?yàn)槟阍噲D在某個(gè)平臺(tái)上去構(gòu)建另一個(gè)平臺(tái)的安裝包或者構(gòu)建 deb/rpm 包時(shí)依賴不對(duì)。fpm 早期是 electron-builder 在 Linux 下生成 deb/rpm 包時(shí)依賴的外部工具如果你的 Linux 環(huán)境缺少 Ruby 和 fpm就會(huì)看到類似cannot exec fpm或fpm failed的報(bào)錯(cuò)。新版 electron-builder 已經(jīng)內(nèi)置了部分能力但老項(xiàng)目或特定發(fā)行版仍可能遇到。更常見(jiàn)的情況是有人在 Windows 上嘗試直接打 Linux 包然后遇到 fpm 系列問(wèn)題。這是最不建議做的事。Windows 平臺(tái)老老實(shí)實(shí)打 Windows 包Linux 包交給 Linux 環(huán)境或 CI 去完成macOS 包也同理?？缙脚_(tái)打包看似方便遇到了坑才知道代價(jià)更大。5.3 原生模塊打進(jìn)包后仍報(bào)錯(cuò)按順序查三點(diǎn)如果 serialport 或者其他原生模塊在 win-unpacked 里運(yùn)行時(shí)報(bào)錯(cuò)按下面順序排查基本能定位第一先看報(bào)錯(cuò)里有沒(méi)有was compiled against a different Node.js version或Module did not self-register。有的話幾乎可以確定 ABI 沒(méi)對(duì)上重新執(zhí)行electron-builder install-app-deps。第二檢查 .node 文件是否進(jìn)了 asar。把 win-unpacked 里的 resources/app.asar 解包看一下如果 serialport 的 .node 文件在 asar 內(nèi)部就要調(diào)整 asarUnpack 配置重新打包。第三檢查系統(tǒng)運(yùn)行庫(kù)。在干凈的 Windows 虛擬機(jī)里測(cè)試如果報(bào)錯(cuò)提示缺 dll說(shuō)明用戶環(huán)境可能缺 Microsoft Visual C Redistributable。這種情況要要么在安裝包里帶上運(yùn)行庫(kù)要么在文檔里標(biāo)注前置要求。5.4 SmartScreen 攔截安裝包個(gè)人開(kāi)發(fā)者怎么應(yīng)對(duì)“Windows 已保護(hù)你的電腦”這個(gè)提示用 Electron 分發(fā)過(guò)應(yīng)用的人都見(jiàn)過(guò)。原因很簡(jiǎn)單你的 exe 沒(méi)有代碼簽名證書(shū)Windows Defender SmartScreen 對(duì)發(fā)布者不明的程序默認(rèn)不信任。如果你只是內(nèi)部工具沒(méi)有證書(shū)可以暫時(shí)不處理但要讓團(tuán)隊(duì)知道安裝時(shí)可能需要點(diǎn)擊更多信息然后選擇仍要運(yùn)行。如果你要公開(kāi)發(fā)布我建議認(rèn)真考慮買(mǎi)代碼簽名證書(shū)普通 OV 證書(shū)和 EV 證書(shū)差價(jià)不小但 EV 證書(shū)能讓 SmartScreen 更快積累信譽(yù)。有一點(diǎn)必須強(qiáng)調(diào)不要去網(wǎng)上找那些所謂的免殺處理過(guò)白名單手段這類操作既不專業(yè)也有合規(guī)風(fēng)險(xiǎn)。正路就是證書(shū)簽名或者先通過(guò)開(kāi)源發(fā)布讓?xiě)?yīng)用積累用戶反饋和信譽(yù)。SmartScreen 檢測(cè)的是數(shù)字簽名信任體系常規(guī)發(fā)布手段短期有提示是正常的堅(jiān)持正規(guī)分發(fā)聲譽(yù)會(huì)逐步建立起來(lái)。5.5 安裝包異常大、.env 和源碼被打進(jìn)去怎么查進(jìn)程構(gòu)建產(chǎn)物通常只有幾兆但如果你 files 配置沒(méi)寫(xiě)好把整個(gè)項(xiàng)目目錄包含進(jìn)去node_modules 里開(kāi)發(fā)依賴那些東西會(huì)被全部打進(jìn)去安裝包隨隨便便超過(guò) 150MB甚至 300MB。排查方法很直接用electron-builder --dir打包出目錄后進(jìn)win-unpacked/resources/查看 app.asar 的體積再用npx asar list app.asar查看文件清單。重點(diǎn)檢查有沒(méi)有出現(xiàn) .env、.git、src 目錄、測(cè)試文件等不該出現(xiàn)的文件。一旦發(fā)現(xiàn) .env 被打進(jìn)包立刻處理把 .env 加入 .gitignore 只是第一步還要在 electron-builder 的 files 配置里顯式排除并且輪換掉所有已泄露的密鑰。這件事千萬(wàn)別拖我在實(shí)際工作中見(jiàn)過(guò)不止一次因?yàn)榇虬渲脤捤蓪?dǎo)致密鑰外泄的事故。5.6 安裝不完整或升級(jí)失敗常見(jiàn)的用戶側(cè)原因熱詞里大量出現(xiàn)xx windows 安裝未完成類似問(wèn)題Electron 應(yīng)用自己也會(huì)有這個(gè)現(xiàn)象。絕大多數(shù)情況不在打包本身而在安裝和升級(jí)過(guò)程。安裝不完整常見(jiàn)于殺毒軟件把安裝包釋放的臨時(shí)文件攔截了或者安裝目錄沒(méi)有寫(xiě)權(quán)限。NSIS 安裝包在解壓過(guò)程中被安全軟件掃描到異常行為直接殺掉進(jìn)程就會(huì)出現(xiàn)安裝到一半失敗的表現(xiàn)。升級(jí)失敗常見(jiàn)于舊版本應(yīng)用還在運(yùn)行安裝程序嘗試覆蓋文件時(shí)發(fā)現(xiàn)文件被占用。所以做升級(jí)邏輯時(shí)先引導(dǎo)用戶退出舊版本再啟動(dòng)新安裝包。如果是 perMachine 模式還要確保用戶有管理員權(quán)限否則 UAC 提權(quán)失敗也會(huì)中斷安裝。6. 多平臺(tái)分發(fā)與發(fā)版前的自檢清單Electron 的好處是寫(xiě)一套代碼能跑三個(gè)平臺(tái)但能跑不代表能打包到全平臺(tái)。尤其是 Windows、Linux、macOS 的打包環(huán)境差異很大處理好這些差異才能讓分發(fā)流程穩(wěn)定不折騰。6.1 想同時(shí)出 Windows / Linux / macOS在 CI 里各打各的electron-builder 支持一條命令同時(shí)指定多平臺(tái)比如electron-builder --win --linux但這個(gè)做法我不推薦你直接在本機(jī)執(zhí)行尤其是 Windows 上交叉打 Linux 包。deb/rpm/AppImage 需要 Linux 工具鏈macOS 的 dmg 更是只能在 macOS 上完成。更穩(wěn)妥的做法是走 CI比如 GitHub Actions 或公司的 Jenkins。Windows 上跑 Windows 打包任務(wù)Ubuntu 上跑 Linux 打包任務(wù)macOS 上跑 macOS 打包任務(wù)各平臺(tái)各打各的產(chǎn)物互不干擾。這樣也方便在發(fā)布時(shí)自動(dòng)生成各平臺(tái)的安裝包統(tǒng)一上傳到 realease。如果你用 GitHub Actionsworkflow 核心思路大致是先 checkout 代碼再安裝依賴然后執(zhí)行對(duì)應(yīng)的打包命令- name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx electron-builder --win --x64這樣一套配置維護(hù)一份三個(gè)平臺(tái)都能持續(xù)產(chǎn)出也避免了本機(jī)交叉編譯的許多歷史遺留坑。6.2 我每次發(fā)版前都會(huì)過(guò)一遍的 8 項(xiàng)檢查經(jīng)常打 Windows 包之后我形成了一個(gè)比較固定的發(fā)版前檢查清單每次照著走一遍能少犯很多低級(jí)錯(cuò)誤。檢查項(xiàng)操作方式常見(jiàn)問(wèn)題主進(jìn)程加載路徑確認(rèn)開(kāi)發(fā)路徑和生產(chǎn)路徑分開(kāi)用了 file:// 或本地服務(wù)器方式不一致導(dǎo)致白屏前端路由模式確認(rèn)生產(chǎn)環(huán)境用 hash 或自定義協(xié)議history 模式在 file:// 下白屏資源引用路徑構(gòu)建產(chǎn)物 publicPath 設(shè)成相對(duì)路徑絕對(duì)路徑導(dǎo)致圖片、CSS 加載失敗原生模塊 ABI執(zhí)行 install-app-deps原生模塊報(bào) NODE_MODULE_VERSION 錯(cuò)誤asar 文件清單用 asar list 抽查.env、源碼、測(cè)試文件混入安裝包體積觀察是否出現(xiàn)異常膨脹files 配置過(guò)寬開(kāi)發(fā)依賴混入干凈環(huán)境安裝測(cè)試用虛擬機(jī)或新用戶測(cè)試缺運(yùn)行庫(kù)、SmartScreen 攔截、安裝路徑異常升級(jí)覆蓋測(cè)試舊版本運(yùn)行中安裝新版本文件被占用、版本回退、配置丟失這套清單我從一開(kāi)始的想到什么查什么慢慢迭代成了現(xiàn)在的固定模板。做完再發(fā)布心情都會(huì)穩(wěn)不少。最后再分享一個(gè)我自己摸索出來(lái)的習(xí)慣每次打包前先花一分鐘看一下 electron-builder 的版本和 Electron 的版本別讓這兩個(gè)核心依賴長(zhǎng)期停留在很舊的版本上。Electron 升一個(gè)大版本Builder 也要跟著升否則很容易出現(xiàn)新版 Electron 和舊版 Builder 不兼容的問(wèn)題。打包這個(gè)事做到后期拼的其實(shí)不是花活而是把每一步該確認(rèn)的事情老老實(shí)實(shí)確認(rèn)完。希望這篇文章能幫你少走幾步彎路早點(diǎn)把精力放回你的產(chǎn)品本身。