Compartir a través de

Configuración de Electron para el desarrollo de la API de Windows

Esta guía le guía a través de la configuración del entorno de desarrollo de Electron para el desarrollo de la API de Windows. Instalará las herramientas necesarias, inicializará sus proyectos y configurará los SDK de Windows.

Al final de esta guía, habrás creado una aplicación de Electron que:

  • Llama a las API modernas de Windows (Windows SDK y Windows App SDK)
  • Puede usar complementos nativos con funcionalidades de inteligencia artificial (PhiLice o WinML)
  • Se ejecuta con la identidad de la aplicación para probar las API protegidas
  • Se puede empaquetar como MSIX firmado para la distribución

Prerrequisitos

  • Windows 11 (Copilot+ PC si usa Phi Silica)
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio con la carga de trabajo de escritorio nativo - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Paso 1: Crear una nueva aplicación Electron

Comience con una nueva aplicación de Electron usando Electron Forge. Si tiene una aplicación existente, omita este paso.

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

Compruebe que la aplicación se ejecuta:

npm start

Paso 2: Instalación de la CLI de Winapp

npm install --save-dev @microsoft/winappcli

Paso 3: Inicializar el project para el desarrollo de Windows

npx winapp init

Cuando se le solicite,

  • Nombre del paquete: presione Entrar para aceptar el valor predeterminado (my-windows-app)
  • Nombre del editor: Presione Intro para aceptar el valor predeterminado o escriba su nombre.
  • Versión: presione Entrar para aceptar 1.0.0.0.
  • Punto de entrada: presione Entrar para aceptar el valor predeterminado (my-windows-app.exe)
  • SDK de configuración: seleccione "SDK estables"

¿Qué hace winapp init?

Este comando configura todo lo que necesita para el desarrollo de Windows:

  1. Crear .winapp/ que contiene encabezados y bibliotecas del SDK de Windows y Windows App SDK
  2. Genera appxmanifest.xml : el manifiesto de aplicación necesario para la identidad de la aplicación y el empaquetado MSIX
  3. Crea Assets/ una carpeta : contiene iconos de aplicación y recursos visuales
  4. Crea winapp.yaml: realiza un seguimiento de las versiones del SDK y la configuración del proyecto
  5. Instala Windows App SDK runtime - Componentes de tiempo de ejecución necesarios para las API modernas
  6. Habilita el modo de desarrollador en Windows: necesario para la depuración

Nota:

La carpeta .winapp/ se agrega automáticamente a .gitignore y no debe incluirse en el control de código fuente.

Paso 4: Agregar restauración a la canalización de compilación

Agregue un script de postinstall a su package.json para asegurarse de que los SDK de Windows estén disponibles cuando otros desarrolladores clonen el proyecto.

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

Este script se ejecuta después de npm install y:

  1. winapp restore - Descarga y restaura todos los paquetes de Windows SDK
  2. winapp node add-electron-debug-identity - Registra la aplicación Electron con la identidad de depuración.

Para proyectos multiplataforma, cree 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.');
}

A continuación, actualice package.json:

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

Paso 5: Comprensión de la identidad de depuración

Comando winapp node add-electron-debug-identity:

  1. Lee tu appxmanifest.xml para obtener detalles y capacidades de la aplicación.
  2. Registra electron.exe en su node_modules con una identidad temporal
  3. Permite probar las API necesarias para la identidad sin crear un paquete MSIX completo.

Ejecute este comando manualmente cada vez que modifique appxmanifest.xml o vincule los recursos:

npx winapp node add-electron-debug-identity

Pruebe la configuración:

npm start

Nota:

Hay un error conocido de Windows con aplicaciones de Electron de empaquetado disperso que pueden provocar bloqueos o ventanas en blanco. Agregue --no-sandbox al script de inicio como solución alternativa: "start": "electron-forge start -- --no-sandbox". Este problema no afecta al empaquetado MSIX completo. Para revertir la identidad de depuración, ejecute npx winapp node clear-electron-debug-identity.

Pasos siguientes

Ahora que el entorno de desarrollo está configurado, cree complementos nativos y llame a las API de Windows:

  • Last updated on