通过

配置 Electron 以开展 Windows API 开发

本指南指导你设置适用于 Windows API 开发的 Electron 开发环境。 你将安装必要的工具、初始化project和配置 Windows SDK。

本指南结束时，你将拥有一个电子应用，该应用包括：

  • 调用新式 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）
  • 发布者名称：按 Enter 接受默认值或输入名称
  • 版本：按 Enter 接受 1.0.0.0
  • 入口点：按 Enter 接受默认值（my-windows-app.exe）
  • 设置 SDK：选择“稳定 SDK”

winapp init 的作用是什么？

此命令设置 Windows 开发所需的一切：

  1. Creates .winapp/ 文件夹包含 Windows SDK 和 Windows App SDK 中的标头和库
  2. 生成 appxmanifest.xml - 应用标识和 MSIX 打包所需的应用清单
  3. Assets/创建文件夹 - 包含应用图标和视觉资产
  4. Creates winapp.yaml - 跟踪 SDK 版本和项目配置
  5. 安装 Windows App SDK 运行时 - 现代 API 所需的运行时组件
  6. 在 Windows 中启用开发者模式 - 这是调试所必需的

注释

.winapp/ 文件夹会自动添加到 .gitignore 中，不应提交到版本控制系统。

步骤 4：将恢复操作添加到构建管道

将 postinstall 脚本添加到 package.json，以确保其他开发人员克隆项目时，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. 使你无需创建完整的 MSIX 包即可测试所需的标识 API

修改appxmanifest.xml或链接的资源时，请手动运行此命令：

npx winapp node add-electron-debug-identity

测试您的设置：

npm start

注释

已知 Windows 的一个 bug 会导致稀疏打包的 Electron 应用程序崩溃或显示空白窗口。 作为临时解决方案，将 --no-sandbox 添加到启动脚本："start": "electron-forge start -- --no-sandbox"。 此问题不会影响完整的 MSIX 打包。 若要撤消调试标识，请运行 npx winapp node clear-electron-debug-identity。

后续步骤

设置开发环境后，请创建本机加载项并调用 Windows API：

  • Last updated on