測驗：Electron + React 打包與發布

共 5 題，點選答案後會立即顯示結果

1. 在 Electron 應用程式打包中，`appId` 的用途是什麼？

A. 設定應用程式視窗的標題
B. 作為應用程式的唯一識別碼，像身分證號
C. 指定打包後的輸出資料夾名稱
D. 設定應用程式的版本號碼

2. 在 Windows 平台打包時，圖示檔案必須使用什麼格式？

A. .png
B. .icns
C. .ico
D. .svg

3. 關於跨平台打包的限制，下列哪個敘述是正確的？

A. 任何平台都可以打包所有作業系統的安裝檔
B. Windows 安裝檔只能在 macOS 上打包
C. Linux 安裝檔只能在 Linux 上打包
D. macOS 安裝檔只能在 macOS 上打包（需要簽名）

4. 在 package.json 的 build 設定中，`"files"` 欄位的用途是什麼？

A. 指定哪些檔案要包進安裝檔
B. 設定應用程式可以開啟的檔案類型
C. 指定打包後要刪除的檔案
D. 設定自動更新時要下載的檔案

5. 使用 electron-updater 設定自動更新時，下列程式碼片段的作用是什麼？

app.whenReady().then(() => {
  autoUpdater.checkForUpdatesAndNotify();
});

A. 強制下載並安裝最新版本
B. 應用程式啟動時檢查更新，有新版本就通知使用者
C. 檢查網路連線狀態是否正常
D. 驗證應用程式的數位簽章是否有效

一句話說明

把你的 Electron + React 應用程式打包成可以安裝的檔案，讓別人能下載使用。

這篇會用到的工具

工具	用途
`electron-builder`	把應用程式打包成安裝檔
`electron-updater`	讓應用程式可以自動更新

30 秒範例：安裝與設定

npm install electron-builder --save-dev

// package.json
{
  "name": "my-app",
  "version": "1.0.0",
  "main": "main.js",
  "build": {
    "appId": "com.example.myapp",
    "productName": "My App"
  },
  "scripts": {
    "build": "electron-builder"
  }
}
Code language: JSON / JSON with Comments (json)

npm run build

這段做了什麼：

安裝 electron-builder
在 package.json 設定應用程式資訊
執行打包，產出安裝檔

核心概念翻譯

package.json 的 build 設定

你會看到	意思
`"appId": "com.example.myapp"`	應用程式的唯一識別碼，像身分證號
`"productName": "My App"`	安裝後顯示的應用程式名稱
`"directories": { "output": "dist" }`	打包後的檔案放哪裡
`"files": ["build/*/", "main.js"]`	哪些檔案要包進安裝檔

最小設定範例

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "main": "main.js",
  "build": {
    "appId": "com.yourname.myapp",
    "productName": "我的應用程式",
    "directories": {
      "output": "release"
    }
  },
  "scripts": {
    "build": "electron-builder"
  }
}
Code language: JSON / JSON with Comments (json)

逐行翻譯：

appId：應用程式 ID，用網域反寫格式（com.公司.應用名）
productName：使用者看到的應用程式名稱
directories.output：打包後的安裝檔放在 release 資料夾

各平台打包格式

Windows（.exe）

{
  "build": {
    "win": {
      "target": "nsis",
      "icon": "assets/icon.ico"
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    }
  }
}
Code language: JSON / JSON with Comments (json)

設定	意思
`"target": "nsis"`	用 NSIS 格式，產出標準的 .exe 安裝檔
`"icon": "assets/icon.ico"`	Windows 圖示檔（必須是 .ico 格式）
`"oneClick": false`	不要一鍵安裝，顯示安裝精靈
`"allowToChangeInstallationDirectory": true`	讓使用者選安裝位置

macOS（.dmg）

{
  "build": {
    "mac": {
      "target": "dmg",
      "icon": "assets/icon.icns",
      "category": "public.app-category.developer-tools"
    }
  }
}
Code language: JSON / JSON with Comments (json)

設定	意思
`"target": "dmg"`	產出 .dmg 磁碟映像檔
`"icon": "assets/icon.icns"`	macOS 圖示檔（必須是 .icns 格式）
`"category"`	App Store 分類（不上架可省略）

Linux（.AppImage）

{
  "build": {
    "linux": {
      "target": "AppImage",
      "icon": "assets/icon.png",
      "category": "Development"
    }
  }
}
Code language: JSON / JSON with Comments (json)

設定	意思
`"target": "AppImage"`	產出 .AppImage，不需安裝直接執行
`"icon": "assets/icon.png"`	Linux 用 .png 圖示

應用程式圖示設定

圖示檔案需求

平台	格式	建議大小
Windows	.ico	256×256（含多尺寸）
macOS	.icns	1024×1024
Linux	.png	512×512

統一圖示設定

{
  "build": {
    "icon": "assets/icon"
  }
}
Code language: JSON / JSON with Comments (json)

翻譯：設定 "icon": "assets/icon"（不寫副檔名），electron-builder 會自動找：

Windows: assets/icon.ico
macOS: assets/icon.icns
Linux: assets/icon.png

快速產生各格式圖示

準備一張 1024×1024 的 PNG 圖片，用線上工具轉換：

# 用 electron-icon-builder（選用）
npm install electron-icon-builder --save-dev
npx electron-icon-builder --input=./icon.png --output=./assets
Code language: PHP (php)

完整設定範例

{
  "name": "my-electron-react-app",
  "version": "1.0.0",
  "description": "我的 Electron + React 應用程式",
  "main": "main.js",
  "author": "Your Name <[email protected]>",
  "license": "MIT",
  "build": {
    "appId": "com.yourname.myapp",
    "productName": "My App",
    "copyright": "Copyright 2024 Your Name",
    "directories": {
      "output": "release"
    },
    "files": [
      "build/**/*",
      "main.js",
      "preload.js"
    ],
    "win": {
      "target": "nsis",
      "icon": "assets/icon.ico"
    },
    "mac": {
      "target": "dmg",
      "icon": "assets/icon.icns"
    },
    "linux": {
      "target": "AppImage",
      "icon": "assets/icon.png"
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    }
  },
  "scripts": {
    "start": "electron .",
    "react-build": "react-scripts build",
    "electron-build": "electron-builder",
    "build": "npm run react-build && npm run electron-build",
    "build:win": "npm run build -- --win",
    "build:mac": "npm run build -- --mac",
    "build:linux": "npm run build -- --linux"
  }
}
Code language: JSON / JSON with Comments (json)

scripts 翻譯：

npm run build：先編譯 React，再打包 Electron
npm run build:win：只打包 Windows 版
npm run build:mac：只打包 macOS 版
npm run build:linux：只打包 Linux 版

打包指令

# 打包當前平台
npm run build

# 指定平台
npm run build -- --win      # Windows
npm run build -- --mac      # macOS
npm run build -- --linux    # Linux

# 同時打包多平台
npm run build -- --win --mac --linux
Code language: PHP (php)

注意：跨平台打包有限制：

Windows 只能在 Windows 打包
macOS 只能在 macOS 打包（需要簽名）
Linux 可以在任何平台打包

自動更新機制（知道就好）

安裝 electron-updater

npm install electron-updater

main.js 加入更新檢查

const { autoUpdater } = require('electron-updater');

// 應用程式啟動後檢查更新
app.whenReady().then(() => {
  autoUpdater.checkForUpdatesAndNotify();
});
Code language: JavaScript (javascript)

這段在幹嘛：應用程式啟動時，自動檢查有沒有新版本，有的話通知使用者。

package.json 設定更新來源

{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "your-username",
      "repo": "your-repo"
    }
  }
}
Code language: JSON / JSON with Comments (json)

翻譯：把安裝檔放到 GitHub Releases，應用程式會從那裡檢查更新。

常見問題與解決方案

問題 1：打包後應用程式打不開

Error: Cannot find module './build/index.html'
Code language: JavaScript (javascript)

原因：React 還沒編譯，或路徑設錯了

解法：

先執行 npm run react-build
確認 main.js 載入的路徑正確：

// main.js
mainWindow.loadFile(path.join(__dirname, 'build', 'index.html'));
Code language: JavaScript (javascript)

問題 2：圖示沒有顯示

原因：圖示格式或尺寸不對

解法：

Windows 必須用 .ico，且包含 256×256 尺寸
macOS 必須用 .icns
確認 package.json 路徑正確

問題 3：Windows 安裝後被防毒軟體擋

原因：未簽名的應用程式

解法（知道就好）：

購買 Windows 程式碼簽章憑證
在 build 設定加入簽名設定

問題 4：打包後檔案太大

原因：包進了不需要的檔案

解法：在 files 設定明確指定要包的檔案：

{
  "build": {
    "files": [
      "build/**/*",
      "main.js",
      "preload.js",
      "!node_modules/**/*"
    ]
  }
}
Code language: JSON / JSON with Comments (json)

翻譯：!node_modules/*/ 表示排除 node_modules（electron-builder 會自動處理需要的依賴）

Vibe Coder 檢查點

打包應用程式時確認：

[ ] package.json 有設定 build.appId 嗎？
[ ] 版本號 version 有更新嗎？
[ ] React 有先編譯（npm run react-build）嗎？
[ ] 圖示檔案格式正確嗎？（Windows 要 .ico）
[ ] main.js 載入的 HTML 路徑是 build 資料夾嗎？
[ ] 打包後有測試安裝檔能正常執行嗎？

打包流程總整理

1. 準備圖示檔案
   └── assets/icon.ico (Windows)
   └── assets/icon.icns (macOS)
   └── assets/icon.png (Linux)

2. 設定 package.json
   └── build.appId
   └── build.productName
   └── scripts.build

3. 編譯 React
   └── npm run react-build

4. 打包 Electron
   └── npm run build

5. 測試安裝檔
   └── release/ 資料夾找到安裝檔
   └── 安裝並執行確認功能正常

延伸：知道就好

這些進階功能遇到再查：

程式碼簽名：讓 Windows/macOS 信任你的應用程式，需要購買憑證
自動更新：用 electron-updater 配合 GitHub Releases
CI/CD 自動打包：用 GitHub Actions 自動打包多平台版本
asar 封裝：把程式碼封裝成單一檔案，electron-builder 預設開啟
多語系安裝程式：NSIS 可以設定多語系安裝介面

系列總結

恭喜完成 Electron + React 系列！你已經學會：

#01 環境建置：建立 Electron + React 專案
#02 雙向溝通：Main 和 Renderer 之間傳遞資料
#03 視窗操作：建立選單和系統托盤
#04 系統整合：檔案對話框、通知、快捷鍵
#05 打包發布：產出可安裝的應用程式

現在你已經具備閱讀和理解 Electron + React 專案的能力，當 AI 幫你生成程式碼時，你知道它在做什麼！

進階測驗：Electron + React 打包與發布

測驗目標：驗證你是否能在實際情境中應用所學。
共 5 題，包含情境題與錯誤診斷題。

1. 你正在開發 Electron + React 應用程式，需要同時支援 Windows、macOS 和 Linux。你在一台 macOS 電腦上工作，想要打包所有平台的安裝檔。最佳做法是什麼？情境題

A. 執行 npm run build -- --win --mac --linux 一次完成所有平台
B. 安裝虛擬機來模擬其他作業系統進行打包
C. 在 macOS 打包 macOS 和 Linux 版，Windows 版需在 Windows 電腦打包
D. 使用雲端服務遠端編譯，本地完全無法跨平台打包

2. 使用者回報打包後的應用程式無法啟動，出現以下錯誤訊息。最可能的原因是什麼？錯誤診斷

Error: Cannot find module ‘./build/index.html’

A. electron-builder 版本太舊需要更新
B. React 還沒編譯，或 main.js 載入的路徑設定錯誤
C. 缺少 Node.js 執行環境
D. 使用者電腦沒有安裝必要的系統函式庫

3. 你的應用程式打包後檔案大小超過 500MB，嚴重影響下載和安裝體驗。你檢查了 package.json 發現沒有設定 `files` 欄位。下列哪個設定最能有效減少檔案大小？情境題

{
  “build”: {
    “files”: [
      // 你要加入什麼？
    ]
  }
}

A. ["**/*"]
B. ["src/**/*", "node_modules/**/*"]
C. ["*.js", "*.html", "*.css"]
D. ["build/**/*", "main.js", "preload.js", "!node_modules/**/*"]

4. 你為 Windows 應用程式設定了圖示，但打包後安裝檔和應用程式都沒有顯示圖示。你的設定如下，問題最可能出在哪裡？錯誤診斷

{
  “build”: {
    “win”: {
      “target”: “nsis”,
      “icon”: “assets/icon.png”
    }
  }
}

A. Windows 圖示必須使用 .ico 格式，不能用 .png
B. 圖示路徑應該使用絕對路徑而非相對路徑
C. 需要額外設定 iconPath 欄位
D. NSIS 打包格式不支援自訂圖示

5. 你想讓使用者在安裝 Windows 應用程式時可以選擇安裝位置，而不是自動安裝到預設目錄。你應該如何設定 package.json？情境題

A. 設定 "win": { "installDir": "custom" }
B. 設定 "nsis": { "oneClick": false, "allowToChangeInstallationDirectory": true }
C. 設定 "win": { "target": "portable" }
D. 設定 "directories": { "installDir": "user-choice" }