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