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