设置开发环境

本指南指导你设置适用于 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 Forge 的全新 Electron 应用开始，该应用提供出色的工具和包装支持。 如果从现有应用开始，可以跳过此步骤。

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

当 Electron Forge 提示时：

  • Bundler：选择 “无”（推荐 — 本地插件无需额外配置）
  • 语言：选择 JavaScript （本指南使用 JS;TypeScript 也适用）
  • 电子版本：选择最新版
  • 初始化 git：首选项

验证应用是否运行：

npm start

您应该会看到默认的 Electron Forge 窗口。 关闭它，让我们添加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）
  • 发布者名称：按 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. Creates winapp.yaml - 跟踪 SDK 版本和项目配置

  5. 安装 Windows 应用 SDK 运行时 - 现代 API 所需的运行时组件

  6. 在 Windows 中启用开发者模式 - 这是调试我们应用程序所必需的

注释

该 .winapp/ 文件夹会自动添加到 .gitignore 中，不应签入代码库。

可以打开 Package.appxmanifest 以进一步自定义属性，如显示名称、发布者和功能。

Tip

关于 Windows SDK：

  • Windows SDK - 一种开发平台，可用于生成 Win32/桌面应用。 它围绕与特定版本的 OS 耦合的 Windows API 进行设计。 使用此 API 访问核心 Win32 API，例如文件系统、网络和系统服务。

  • Windows 应用 SDK - 一个新的开发平台，可用于生成可跨Windows版本（Windows 10 1809）安装的新桌面应用。 它围绕Windows OS API 的丰富目录提供了一个方便的、与 OS 分离的抽象。 Windows 应用 SDK 包括 WinUI 3，并提供 AI 功能（Phi Silica）、通知、窗口管理等现代功能的访问权限，这些功能与 Windows 操作系统版本无关，并能接收常规更新。

了解详细信息：Windows 应用 SDK与Windows SDK有何区别？

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

若要确保在其他开发人员克隆项目或 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 以触发 postinstall 脚本并配置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. 使你无需创建完整的 MSIX 包即可测试所需的标识 API

在步骤 4 中运行 npm install 时，调试标识会自动应用。 今后，每当有人运行 npm install 时，它都会被重新应用。

何时手动更新调试标识

每当修改 Package.appxmanifest （更改功能、标识或属性）或任何链接资产（图标、mcp.json等）时，都需要手动运行此命令

npx winapp node add-electron-debug-identity

测试您的设置

现在，您可以使用调试身份标识来测试您的 Electron 应用程序：

npm start

应会看到 桌面应用程序窗口 处于打开状态（而不是浏览器选项卡），这就是 Electron 应用运行方式。

⚠️ 已知问题：应用崩溃或空白窗口（单击以展开）

已知存在与稀疏打包相关的Windows bug，会导致Electron应用程序启动时崩溃或无法呈现Web内容。 此问题已在Windows中修复，但尚未传播到所有设备。

症状：

  • 应用在启动后立即崩溃
  • 窗口打开，但显示空白/白色屏幕
  • Web 内容无法呈现

解决方法：

将 --no-sandbox 标志添加到起始脚本中 package.json。 这可以通过禁用 Chromium 沙箱来解决此问题，这对于开发而言是安全的。

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

重要： 此问题 不会影响 完整的 MSIX 打包，仅影响开发期间的调试标识。

若要撤消调试标识 （如果需要进行故障排除）：

npx winapp node clear-electron-debug-identity

这会还原原始的 Electron 可执行文件，而不使用调试标识。

后续步骤

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

或返回到 入门概述。

  • Last updated on