Nodejs 使用 sea 打包程式閃退與解法

定格視窗,抓出真正的錯誤紅字(極重要)

請不要直接雙擊執行檔。請透過 Windows 終端機手動執行,這樣即使程式崩潰,視窗也不會關閉:

  1. 在你的專案資料夾空白處,按住鍵盤 Shift 鍵不放,同時點擊滑鼠右鍵。
  2. 選擇「在終端機開啟」或「在此處開啟 PowerShell 視窗」。
  3. 在跳出的藍色/黑色視窗中,輸入:
PowerShell
.\music-server.exe

按下 Enter。此時畫面上會 100% 吐出導致閃退的紅字錯誤 stack trace(例如 Cannot find module ‘…’)。

這個錯誤 ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: webdav-server 揭開了 Node.js v26.12.0 閃退的終極原因!

PowerShell
PS D:\progs\nodejs\music-server> .\music-server.exe
node:internal/modules/helpers:292
  throw new ERR_UNKNOWN_BUILTIN_MODULE(id);
  ^

Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: webdav-server
    at loadBuiltinModuleForEmbedder (node:internal/modules/helpers:292:9)
    at embedderRequire (node:internal/main/embedding:108:10)
    at server.js:3:16
    at embedderRunCjs (node:internal/main/embedding:98:10)
    at embedderRunEntryPoint (node:internal/main/embedding:177:12) {
  code: 'ERR_UNKNOWN_BUILTIN_MODULE'
}

Node.js v26.12.0

原因分析

在 Node.js 官方的 SEA 機制中,當你指定了 “mainFormat”: “commonjs”,底層的 V8 引擎在執行被嵌入的程式碼時,它的 require 會誤以為所有模組都是 Node.js 內建的模組(如 fs, path),因而直接去核心庫尋找 webdav-server。由於找不到,就噴出了這個內建模組未知的錯誤並直接閃退。

解決方案:使用 esbuild 將其打包成「純 JavaScript」

要解決這個問題,我們必須使用前端或後端目前最主流的作法:利用 esbuild 工具,在交給 Node.js 打包成 .exe 之前,先把 server.js 與 webdav-server 套件融合成「單一一個完全不包含外部 require 的 JS 檔案」。
這樣一來,Node.js 26 讀到程式碼時,所有功能都已經寫在裡面了,不需要再去執行 require(‘webdav-server’),就能 100% 避開這個核心錯誤!
請按照以下步驟調整專案,即可完美打包且不再閃退:

步驟 1:安裝 esbuild 打包工具

在 VS Code 終端機執行以下指令來安裝這個極速打包工具:

Bash
npm install --save-dev esbuild

步驟 2:修改 package.json 中的腳本命令

請將 package.json 中的 “scripts” 區塊修改為以下工作流(先用 esbuild 融合成單一檔案,再交給 Node.js 封裝):

Bash
"scripts": {
  "dev": "node server.js",
  "build:sea": "npx esbuild server.js --bundle --platform=node --target=node26 --outfile=dist/bundle.js && node sea-build.js"
}

步驟 3:修改 sea-config.json 的讀取來源

因為程式碼已經被融合並輸出到 dist/bundle.js 了,我們要讓 SEA 機制改讀取這顆融合後的檔案。請修改 sea-config.json:

JSON
{
  "main": "dist/bundle.js",
  "output": "music-server.exe",
  "mainFormat": "commonjs",
  "disableExperimentalSEAWarning": true
}

步驟 4:調整 server.js 的實體路徑防護

當程式碼被 esbuild 融合成單一檔案並封裝進 .exe 後,傳統的 __dirname 就會失效。在官方 SEA 內核中,最安全、絕對不會抓錯的實體資料夾定位方式,是利用 process.execPath(代表使用者點擊的那個 .exe 的路徑)。
請將你的 server.js 開頭的路徑判斷修改為以下防護版本:

JavaScript
// 1. 判斷是否為 Node.js 官方 SEA 環境
const isSea = process.isSEA ? process.isSEA() : false;

// 2. 判斷是否為 pkg 打包環境
const isPkg = process.pkg ? true : false;

// 3. 根據不同的執行環境,動態決定基礎目錄 (baseDir)
let baseDir;

if (isSea) {
    // 官方 SEA 打包後,process.execPath 就是 .exe 的絕對路徑
    baseDir = path.dirname(process.execPath);
} else if (isPkg) {
    // pkg 打包後,process.execPath 同樣是 .exe 的絕對路徑
    baseDir = path.dirname(process.execPath);
} else {
    // VS Code 開發偵錯或直接執行 node server.js 時,使用當前腳本所在的目錄
    baseDir = __dirname;
}

// 4. 最終指向 Music 資料夾
const MUSIC_FOLDER = path.join(baseDir, 'Music');
// 測試列印(可在偵錯時確認路徑是否正確)
console.log(`[環境偵測] SEA: ${isSea}, Pkg: ${isPkg}`);
console.log(`[資料夾路徑] ${MUSIC_FOLDER}`);

步驟 5:重新執行打包命令

在 VS Code 終端機中,再次敲入指令:

Bash
npm run build:sea

打包結束後,直接去資料夾雙擊全新的 music-server.exe。這次因為程式碼內部已經自帶了完整的 webdav-server 原始碼,不需再透過系統 require 尋找,它便能完美、穩定地常駐啟動,絕對不會再跳出錯誤或閃退了!

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *