Configuração do Ambiente de Desenvolvimento

Este guia guia-o na configuração do seu ambiente de desenvolvimento Electron para desenvolvimento de APIs Windows. Vais instalar as ferramentas necessárias, inicializar o teu project e configurar SDKs do Windows.

Pré-requisitos

Antes de começar, certifique-se de que tem:

  • Windows 11
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio com a Carga de Trabalho Nativa para Desktop - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Passo 1: Criar uma nova aplicação Electron

Vamos começar com uma nova aplicação Electron usando o Electron Forge, que oferece excelente suporte de ferramentas e embalagem. Se estiver a começar a partir de uma aplicação já existente, pode saltar este passo.

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

Quando solicitado por Electron Forge:

  • Bundler: Selecionar Nenhum (recomendado — addons nativos funcionam sem configuração extra)
  • Linguagem: Selecione JavaScript (este guia usa JS; O TypeScript também funciona)
  • Versão Electron: Selecionar a versão mais recente
  • Inicialize git: A tua preferência

Verifique se a aplicação está a funcionar:

npm start

Deves ver a janela padrão do Electron Forge. Fecha-a e vamos adicionar capacidades do Windows!

Passo 2: Instalar a CLI do winapp

O fluxo de trabalho do Electron requer o pacote npm (@microsoft/winappcli) em vez da CLI autónoma instalada pelo winget. O pacote npm inclui ajudantes específicos de Node.js(como add-electron-debug-identity e create-addon) que não estão disponíveis na CLI nativa. Se já tiveres o WinApp instalado no WinGet, tudo bem — o pacote npm adiciona ferramentas específicas Node.jscomo dependência do projeto e não entra em conflito com a instalação do teu sistema.

npm install --save-dev @microsoft/winappcli

Passo 3: Iniciar o projeto para desenvolvimento no Windows

O winapp init comando configura tudo o que precisas de uma só vez: manifesto da app, assets e SDKs.

Execute o seguinte comando e siga as indicações:

npx winapp init .

Quando solicitado:

  • Nome do pacote: Pressione Enter para aceitar o predefinido (my-windows-app)
  • Nome do Publicador: Pressione Enter para aceitar o padrão ou inserir o seu nome
  • Versão: Pressione Enter para aceitar 1.0.0.0
  • Ponto de entrada: Pressione Enter para aceitar o padrão (my-windows-app.exe)
  • Configurar SDKs: Selecione "SDKs Estáveis"

O que faz winapp init ?

Este comando define tudo o que precisas para o desenvolvimento do Windows:

  1. Cria .winapp/ uma pasta contendo:

    • Cabeçalhos e bibliotecas do SDK Windows
    • Cabeçalhos e bibliotecas do SDK de Aplicações Windows
    • Pacotes NuGet com os binários necessários

  2. Gera Package.appxmanifest - O manifesto da aplicação necessário para a identidade da aplicação e o empacotamento MSIX

  3. Cria Assets/ pasta - Contém ícones da aplicação e recursos visuais para a sua aplicação

  4. Creates winapp.yaml - Monitoriza versões do SDK e configuração de projetos

  5. Instala SDK de Aplicações Windows runtime - Componentes de runtime necessários para APIs modernas

  6. Ativa o Modo Desenvolvedor em Windows - Necessário para depurar a nossa aplicação

Observação

A .winapp/ pasta é adicionada .gitignore automaticamente e não deve ser registada como fonte.

Pode abrir Package.appxmanifest para personalizar ainda mais propriedades como o nome de visualização, publicador e capacidades.

Sugestão

Sobre os SDKs Windows:

  • Windows SDK - Uma plataforma de desenvolvimento que permite construir aplicações Win32/desktop. Foi desenhado em torno de APIs do Windows acopladas a versões específicas do sistema operativo. Use isto para aceder às APIs principais do Win32, como sistemas de ficheiros, redes e serviços do sistema.

  • SDK de Aplicações Windows - Uma nova plataforma de desenvolvimento que permite criar aplicações modernas de ambiente de trabalho que podem ser instaladas em Windows versões (até Windows 10 1809). Proporciona uma abstração conveniente e desacoplada do sistema operativo em torno do rico catálogo de APIs do Windows OS. O SDK de Aplicações Windows inclui o WinUI 3 e oferece acesso a funcionalidades modernas como capacidades de IA (Phi Silica), notificações, gestão de janelas e mais, que recebem atualizações regulares independentemente das versões do Windows OS.

Saiba mais: Qual é a diferença entre o SDK de Aplicações Windows e o SDK Windows?

Passo 4: Adicionar o Restaurar ao seu pipeline de construção

Para garantir que os SDKs Windows estão disponíveis quando outros programadores clonam o seu projeto ou em pipelines CI/CD, adicione um script postinstall ao seu package.json:

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

Este script corre automaticamente depois npm install e faz duas coisas:

  1. winapp restore - Descarrega e restaura todos os pacotes SDK Windows na pasta .winapp/
  2. winapp node add-electron-debug-identity - Registar a sua aplicação Electron com a identidade de debug (mais sobre isto nos próximos passos)

Agora executa npm install para ativar o script de pós-instalação e configurar o ambiente Windows:

npm install

Observação

O postinstall script corre automaticamente após cada npm install. Isto significa que o ambiente Windows será configurado automaticamente sempre que alguém clonar o seu projeto e executar npm install.

💡 Desenvolvimento Multiplataforma (clique para expandir)

Se estiveres a construir uma aplicação Electron multiplataforma e tiveres programadores a trabalhar em macOS ou Linux, vais querer executar condicionalmente a configuração específica do Windows. Aqui está a abordagem recomendada:

Criar 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.');
}

Depois atualiza package.json:

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

Isto garante que a configuração específica do Windows só corre em máquinas Windows, permitindo que programadores de outras plataformas trabalhem no projeto sem erros.

Passo 5: Entender a Identidade para Depuração

Durante o npm install executado no Passo 4, foi acionado o script postinstall, que executou winapp node add-electron-debug-identity. Isto dá à sua aplicação uma identidade de depuração temporária para que possa testar APIs do Windows que requerem identidade de aplicação durante o desenvolvimento.

O que faz o Debug Identity?

Este comando:

  1. Lê o seu Package.appxmanifest para obter detalhes e funcionalidades da aplicação.
  2. Regista electron.exe no seu node_modules com uma identidade temporária
  3. Permite testar APIs que exigem identidade sem criar um pacote MSIX completo

A identidade de depuração foi aplicada automaticamente quando executou npm install no Passo 4. Daqui para a frente, será reaplicado sempre que alguém execute npm install.

Quando Atualizar Manualmente a Identidade de Depuração

Tens de executar este comando manualmente sempre que modificares Package.appxmanifest (mudar capacidades, identidade ou propriedades) ou qualquer um dos ativos ligados (ícones, mcp.json, etc.)

npx winapp node add-electron-debug-identity

Testar a Sua Configuração

Agora pode testar a sua aplicação Electron com o perfil de depuração aplicado:

npm start

Deverias ver uma janela de aplicação de ambiente de trabalho aberta (não um separador do navegador) — é assim que as aplicações Electron funcionam.

⚠️ Problema Conhecido: A Aplicação Crasha ou Janela Em Branco (clique para expandir)

Existe um bug conhecido no Windows com aplicações Electron em empacotamento esparso que faz com que a aplicação crashe ao iniciar ou não renderize conteúdo web. O problema foi resolvido no Windows, mas ainda não se propagou a todos os dispositivos.

Sintomas:

  • A aplicação crasha imediatamente após o lançamento
  • A janela abre, mas mostra o ecrã em branco.
  • Conteúdo web falha em renderizar

Solução:

Adicione a --no-sandbox flag ao seu script de início em package.json. Isto contorna o problema desativando o sandbox do Chromium, que é seguro para fins de desenvolvimento.

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

Importante: Este problema não afeta o empacotamento completo do MSIX – apenas a identidade de depuração durante o desenvolvimento.

Para desfazer a identidade de debug (se necessário para a resolução de problemas):

npx winapp node clear-electron-debug-identity

Isto restaura o executável do Electron na sua forma original, sem a identidade de depuração.

Próximas Etapas

Agora que o seu ambiente de desenvolvimento está configurado, está pronto para criar addons nativos e chamar APIs do Windows:

Ou voltar à Visão Geral de Como Começar.

  • Last updated on