設定 Electron 用於 Windows API 開發

本指南將引導你如何為 Windows API 開發設定 Electron 開發環境。 你將安裝必要的工具、初始化你的 project，並設定 Windows SDK。

完成本指南後，你會有一個 Electron 應用程式：

  • 呼叫現代 Windows API（Windows SDK 與 Windows App SDK）
  • 可以使用具備 AI 功能的原生插件（Phi Silica 或 WinML）
  • 以應用程式身份執行以測試受保護的 API
  • 可作為簽署的 MSIX 格式打包進行分發

先決條件

  • Windows 11（如果使用 Phi Silica，則可以使用 Copilot+ PC）
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio 搭配原生桌面工作負載 - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

步驟 1：建立新的 Electron 應用程式

先用 Electron Forge 的新 Electron 應用程式開始。 如果你已有應用程式，可以跳過這個步驟。

npm create electron-app@latest my-windows-app
cd my-windows-app

確認應用程式是否運作：

npm start

步驟 2：安裝 winapp CLI

npm install --save-dev @microsoft/winappcli

步驟 3：初始化專案以進行 Windows 開發

npx winapp init

出現提示時：

  • 套件名稱：按下 Enter 鍵以接受預設的（my-windows-app）
  • Publisher name：按 Enter 接受預設或輸入你的名字
  • 版本：按下 "Enter" 以接受 1.0.0.0
  • 入口點：按 Enter 接受預設（my-windows-app.exe）
  • 設定 SDK：選擇「穩定 SDK」

winapp init 的用途為何？

這個指令可以幫你設定 Windows 開發所需的一切：

  1. 建立 .winapp/ 資料夾，包含來自 Windows SDK 和 Windows App SDK 的標頭與函式庫。
  2. 產生 appxmanifest.xml - 應用程式識別碼及 MSIX 封裝所需的應用程式清單
  3. 建立 Assets/ 資料夾 - 包含應用程式圖示與視覺素材
  4. 建立 winapp.yaml - 追蹤 SDK 版本及project設定
  5. 安裝 Windows App SDK 執行時 - 現代 API 所需的必要執行時元件
  6. 啟用 Windows 開發者模式 - 除錯必備功能

備註

該.winapp/資料夾會自動加入.gitignore，且不應檢入至版本控制。

步驟四：將還原加入你的建構流程

在你的 postinstall 中加入 package.json 腳本，以確保當其他開發者克隆你的 project時，Windows SDK 仍然可用：

{
  "scripts": {
    "postinstall": "winapp restore && winapp node add-electron-debug-identity"
  }
}

此腳本在 npm install 之後執行：

  1. winapp restore - 下載並還原所有 Windows SDK 套件
  2. winapp node add-electron-debug-identity - 將您的 Electron 應用程式註冊為偵錯身分識別

跨平台專案請建立 scripts/postinstall.js：

if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  try {
    execSync('npx winapp restore && npx winapp cert generate --if-exists skip && npx winapp node add-electron-debug-identity', {
      stdio: 'inherit'
    });
  } catch (error) {
    console.warn('Warning: Windows-specific setup failed.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

然後更新 package.json：

{
  "scripts": {
    "postinstall": "node scripts/postinstall.js"
  }
}

步驟 5：了解識別除錯身份

winapp node add-electron-debug-identity 命令：

  1. 這個程式會讀取你的 appxmanifest.xml 應用程式的詳細資料和功能。
  2. 在您的node_modules中以臨時身份註冊electron.exe
  3. 讓你能測試身份要求的 API，而不必建立完整的 MSIX 套件

每當你修改 appxmanifest.xml 或連結資產時，請手動執行這個指令：

npx winapp node add-electron-debug-identity

測試你的設備：

npm start

備註

Electron 應用程式的稀疏封裝已知會在 Windows 系統中引發錯誤，可能導致當機或視窗空白。 請在您的啟動腳本中加入 --no-sandbox 作為替代方案："start": "electron-forge start -- --no-sandbox"。 此問題不影響完整的 MSIX 封裝。 要撤銷除錯身份，執行 npx winapp node clear-electron-debug-identity。

下一步

現在你的開發環境已經建立好，請建立原生外掛並呼叫 Windows API：

  • Last updated on