Configuración del entorno de desarrollo

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.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene:

  • Windows 11
  • 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 App de Electron

Comenzaremos con una nueva aplicación Electron con Electron Forge, que proporciona una excelente compatibilidad con herramientas y embalajes. Si está empezando desde una aplicación existente, puede omitir este paso.

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

Cuando lo solicite Electron Forge:

  • Agrupador: seleccione Ninguno (recomendado: los complementos nativos funcionan sin configuración adicional)
  • Lenguaje: seleccione JavaScript (en esta guía se usa JS; TypeScript también funciona)
  • Versión de Electron: seleccione la versión más reciente.
  • Inicialización de Git: su preferencia

Compruebe que la aplicación se ejecuta:

npm start

Debería ver la ventana predeterminada de Electron Forge. Ciérrelo y vamos a agregar Windows funcionalidades.

Paso 2: Instalación de la CLI de Winapp

El flujo de trabajo de Electron requiere el paquete npm (@microsoft/winappcli) en lugar de la CLI independiente instalada desde winget. El paquete npm incluye ayudas específicas de Node.js (como add-electron-debug-identity y create-addon) que no están disponibles en la CLI nativa. Si ya tiene winapp instalado desde winget, está bien: el paquete npm añade herramientas específicas de Node.js como una dependencia del proyecto y no entrará en conflicto con la instalación de su sistema.

npm install --save-dev @microsoft/winappcli

Paso 3: Inicializar el project para el desarrollo de Windows

El winapp init comando configura todo lo que necesita en un solo uso: manifiesto de aplicación, recursos y SDK.

Ejecute el siguiente comando y siga las indicaciones:

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. Crea una .winapp/ carpeta que contiene:

    • Encabezados y bibliotecas del SDK de Windows
    • Encabezados y bibliotecas de la SDK de Aplicaciones para Windows
    • Paquetes NuGet con los archivos binarios necesarios

  2. Genera Package.appxmanifest : 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 para la aplicación

  4. Crea winapp.yaml: realiza un seguimiento de las versiones del SDK y la configuración del proyecto

  5. Instala SDK de Aplicaciones para Windows runtime - Componentes de tiempo de ejecución necesarios para las API modernas

  6. Enables Modo de desarrollador en Windows: necesario para depurar nuestra aplicación

Nota:

La carpeta .winapp/ se agrega automáticamente a .gitignore y no debe ser registrada en el control de versiones.

Puede abrir Package.appxmanifest para personalizar aún más las propiedades, como el nombre para mostrar, el publicador y las funcionalidades.

Tip

About the Windows SDKs:

  • Windows SDK: una plataforma de desarrollo que le permite crear aplicaciones de escritorio o Win32. Está diseñado en torno a las API de Windows que están asociadas a versiones concretas del sistema operativo. Úselo para acceder a las API principales de Win32, como el sistema de archivos, las redes y los servicios del sistema.

  • SDK de Aplicaciones para Windows: una nueva plataforma de desarrollo que le permite crear aplicaciones de escritorio modernas que se pueden instalar en versiones de Windows (hasta Windows 10 1809). Proporciona una abstracción cómoda y desacoplada del OS en torno al amplio catálogo de APIs del sistema operativo Windows. El SDK de Aplicaciones para Windows incluye WinUI 3 y proporciona acceso a características modernas, como funcionalidades de inteligencia artificial (PhiLice), notificaciones, administración de ventanas y mucho más que reciben actualizaciones periódicas independientemente de las versiones del sistema operativo Windows.

Más información: ¿Cuál es la diferencia entre la SDK de Aplicaciones para Windows y el SDK de Windows?

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

Para garantizar que los SDK de Windows estén disponibles cuando otros desarrolladores clonen tu proyecto o en las canalizaciones de CI/CD, agrega un script a tu postinstallpackage.json:

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

Este script se ejecuta automáticamente después de npm install y hace dos cosas:

  1. winapp restore - descarga y restaura todos los paquetes del SDK de Windows en la carpeta .winapp/
  2. winapp node add-electron-debug-identity - Registra tu aplicación de Electron con la identidad de debugging (más información sobre esto en los pasos siguientes)

Ahora ejecute npm install para desencadenar el script posterior a la instalación y configurar el entorno de Windows:

npm install

Nota:

El postinstall script se ejecuta automáticamente después de cada npm install. Esto significa que el entorno de Windows se configurará automáticamente siempre que alguien clone el proyecto y ejecute npm install.

💡 Desarrollo multiplataforma (haga clic para expandir)

Si va a compilar una aplicación Electron multiplataforma y tiene desarrolladores que trabajan en macOS o Linux, querrá ejecutar condicionalmente la configuración específica para Windows. Este es el enfoque recomendado:

Creación de 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.');
}

A continuación, actualice package.json:

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

Esto garantiza que la configuración específica de Windows solo se ejecute en las máquinas Windows, permitiendo a los desarrolladores en otras plataformas trabajar en el proyecto sin errores.

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

El npm install que ejecutó en el paso 4 desencadenó el postinstall script, que ejecutó winapp node add-electron-debug-identity. Esto proporciona a su aplicación una identidad de depuración temporal para que pueda, durante el desarrollo, probar las API de Windows que requieren identidad de aplicación.

¿Qué hace la función Identidad de Depuración?

Este comando:

  1. Lee tu Package.appxmanifest 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.

La identidad de depuración se aplicó automáticamente cuando se ejecutó npm install en el paso 4. En el futuro, se volverá a aplicar cada vez que alguien ejecute npm install.

Cuándo se debe actualizar manualmente la identidad de depuración

Debe ejecutar este comando manualmente siempre que modifique Package.appxmanifest (cambiar funcionalidades, identidades o propiedades) o cualquiera de los recursos vinculados (iconos, mcp.json, etc.)

npx winapp node add-electron-debug-identity

Prueba de la configuración

Ahora puede probar la aplicación Electron con la identidad de depuración aplicada:

npm start

Debería ver una ventana de aplicación de escritorio abierta (no una pestaña del explorador). Así es como se ejecutan las aplicaciones Electron.

⚠️ Problema conocido: Bloqueos de la aplicación o ventana en blanco (haga clic para expandir)

Hay un error conocido de Windows con aplicaciones Electron de empaquetado ligero o disperso que hace que la aplicación se bloquee al iniciar o no mostrar contenido web. El problema se ha corregido en Windows pero aún no se ha propagado a todos los dispositivos.

Síntomas:

  • La aplicación se bloquea inmediatamente después del inicio
  • Se abre la ventana, pero se muestra la pantalla en blanco.
  • El contenido web no se puede representar

Solución alternativa:

Agregue la --no-sandbox marca al script de inicio en package.json. Esto soluciona el problema al deshabilitar el espacio aislado de Chromium, que es seguro para desarrollo.

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

Importante: Este problema no afecta al empaquetado MSIX completo: solo afecta a la identidad de depuración durante el desarrollo.

Para revertir la identidad de depuración (si es necesario para solucionar problemas):

npx winapp node clear-electron-debug-identity

Esto restaura el ejecutable Electron original sin la identidad de depuración.

Pasos siguientes

Ahora que el entorno de desarrollo está configurado, está listo para crear complementos nativos y llamar a Windows API:

O vuelva a la Descripción general de cómo empezar.

  • Last updated on