建立開發環境

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

先決條件

在開始之前，請確保您擁有：

  • Windows 11
  • 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 應用程式開始，採用 Electron Forge，提供優秀的工具與包裝支援。 如果你是從現有的應用程式開始，可以跳過這個步驟。

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

當 Electron Forge 提示時：

  • 捆綁器：選擇 無（ 建議——原生外掛無需額外設定即可使用）
  • 語言：選擇 JavaScript （本指南使用JS;TypeScript 也可行）
  • Electron 版本：選擇 最新
  • 初始化git：你的偏好

確認應用程式是否運作：

npm start

你應該會看到預設的電子鍛造視窗。 關掉它，讓我們加入 Windows 功能！

步驟 2：安裝 winapp CLI

Electron 的工作流程需要 npm 套件 （@microsoft/winappcli），而非從 winget 安裝的獨立 CLI。 npm 套件包含了 Node.js專用的輔助工具（如 add-electron-debug-identity 和 create-addon），這些在原生 CLI 中沒有。 如果你已經從 winget 安裝了 winapp，那沒問題——npm 套件會新增 Node.js專屬工具作為專案相依，不會與系統安裝衝突。

npm install --save-dev @microsoft/winappcli

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

這個 winapp init 指令一次設定你需要的所有東西：應用程式清單、資產和 SDK。

執行以下指令並依照提示操作：

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 應用程式 SDK 的標頭與函式庫
    • NuGet 套件中包含所需的二進位檔

  2. 產生 Package.appxmanifest - 應用程式識別碼及 MSIX 封裝所需的應用程式清單

  3. 建立 Assets/ 資料夾 - 包含應用程式圖示與視覺素材

  4. 建立 winapp.yaml - 追蹤 SDK 版本及project設定

  5. 安裝 Windows 應用程式 SDK 執行時 - 現代 API 所需的必要執行時元件

  6. 啟用 Windows 開發者模式 - 為了除錯我們的應用程式所需

備註

該 .winapp/ 資料夾會自動加入 .gitignore ，且不應被輸入至原始碼。

你可以開啟 Package.appxmanifest 來進一步自訂屬性，例如顯示名稱、發佈者和功能。

Tip

關於Windows SDK：

  • Windows SDK - 一個開發平台，讓你能建立 Win32/桌面應用程式。 它是針對與特定作業系統版本結合的 Windows API 所設計。 利用這些工具存取核心的 Win32 API，如檔案系統、網路和系統服務。

  • Windows 應用程式 SDK - 一個新的開發平台，讓你能打造可跨Windows版本安裝的現代桌面應用程式（Windows 10 1809）。 它提供了一個方便且與作業系統分離的抽象介面，環繞 Windows 作業系統 API 的豐富目錄。 Windows 應用程式 SDK 包含 WinUI 3，並提供現代功能如 AI 功能（Phi Silica）、通知、視窗管理等，這些功能會獨立於 Windows 作業系統版本而定期更新。

了解更多：Windows 應用程式 SDK 和 Windows SDK 之間有什麼區別？

步驟 4：將 Restore 加入你的建置流程

為了確保當其他開發者複製你的專案或在 CI/CD 流程中時，Windows SDK 仍然可用，請在你的 postinstall 中加入一個 package.json 腳本：

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

這個腳本會在 npm install 之後自動執行，並執行兩件事：

  1. winapp restore - 下載並還原所有Windows SDK 套件到 .winapp/ 資料夾
  2. winapp node add-electron-debug-identity - 將您的 Electron 應用程式註冊為偵錯識別（後續步驟會詳細說明）

現在執行 npm install 來觸發安裝後腳本並設定 Windows 環境：

npm install

備註

postinstall後，每次npm install，腳本將自動執行。 這表示每當有人複製你的專案並執行 npm install，Windows 環境就會自動設定。

💡 跨平台開發（點擊展開）

如果你正在打造跨平台的 Electron 應用程式，且有開發者在 macOS 或 Linux 上工作，你會想要有條件地執行 Windows 專用的設定。 以下是建議的方法：

創建 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. If you are not developing Windows features, you can ignore this.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

然後更新 package.json：

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

這確保了 Windows 專用設定僅能在 Windows 機器上運行，讓其他平台的開發者能在專案中順利作業，且不會有錯誤。

步驟 5：了解偵錯身份

在第 4 步執行的npm install觸發了postinstall腳本，然後執行了winapp node add-electron-debug-identity。 這會讓你的應用程式獲得暫時的除錯身份，讓你能測試開發過程中需要應用程式身份的 Windows API。

偵錯身份能做什麼？

此命令：

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

偵錯身份是在你 npm install 執行第 4 步時自動套用的。 往後，只要有人執行 npm install，就會重新應用。

何時手動更新除錯身份

每當你修改 Package.appxmanifest （變更能力、身份或屬性）或任何連結的資產（圖示、mcp.json等）時，都需要手動執行這個指令。

npx winapp node add-electron-debug-identity

測試你的設備

你現在可以使用偵錯識別來測試你的 Electron 應用程式：

npm start

你應該會看到桌面 應用程式 視窗開啟（不是瀏覽器分頁）——這就是 Electron 應用程式的運作方式。

⚠️ 已知問題：應用程式當機或視窗空白（點擊展開）

Windows 有一個已知的 Electron 應用程式封裝稀疏錯誤，會導致應用程式啟動時當機或無法渲染網頁內容。 這個問題在 Windows 上已經修正，但尚未擴散到所有裝置。

症狀：

  • 應用程式一上線就當機
  • 視窗會打開但螢幕是空白/白色的
  • 網頁內容無法渲染

因應措施：

在package.json中，將--no-sandbox旗標加入你的開始腳本。 這透過關閉 Chromium 的沙盒功能來繞過這個問題，而沙盒對開發來說是安全的。

{
  "scripts": {
    "start": "electron-forge start -- --no-sandbox"
  }
}

重要： 此問題 不 影響完整的 MSIX 封裝，僅影響開發期間的除錯身份。

若要撤銷除錯身份 （如有需要進行故障排除）：

npx winapp node clear-electron-debug-identity

此時會恢復原始 Electron 執行檔，但不包含除錯識別。

後續步驟

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

  • 建立 Phi Silica 外掛 - 學習如何建立一個呼叫 Phi Silica AI API 的 C# 外掛
  • 建立 WinML 插件 - 學習如何建立使用 Windows 機器學習 的 C# 外掛
  • 封裝分發 - 建立 MSIX 封裝以進行分發

或者回到「 入門總覽」頁面。

  • Last updated on