Empacotando seu aplicativo Electron para distribuição

Este guia mostra como criar um pacote MSIX para distribuir seu aplicativo Electron com APIs do Windows.

Pré-requisitos

Antes de empacotar, verifique se você:

Concluído a configuração do ambiente de desenvolvimento
[OPCIONAL] Criou e testou seu complemento (por exemplo, complemento Phi Silica ou complemento WinML)
Verificado que seu aplicativo é executado corretamente com npm start

Preparar para empacotamento

Configure o Electron Forge para excluir arquivos temporários do build final. Adicione uma ignore matriz ao seu packagerConfig em forge.config.js.

module.exports = {
  packagerConfig: {
    asar: true,
    ignore: [
      /^\/\.winapp($|\/)/,     // SDK packages and headers
      /^\/winapp\.yaml$/,       // SDK config
      /\.pfx$/,                 // Certificate files
      /\.pdb$/,                 // Debug symbols
      /\/obj($|\/)/,            // C# build artifacts
      /\/bin($|\/)/,            // C# build artifacts
      /\.msix$/                 // MSIX packages
    ]
  },
  // ... rest of your config
};

Importante

Verifique se o Package.appxmanifest corresponde à estrutura do seu aplicativo empacotado.

O atributo Executable deve apontar para o arquivo .exe correto no resultado empacotado.

Gerar um certificado de desenvolvimento

Antes de criar um pacote MSIX assinado, gere um certificado de desenvolvimento:

npx winapp cert generate

Isso cria um devcert.pfx arquivo na raiz do projeto que será usado para assinar o pacote MSIX.

Opções de empacotamento

Você tem duas opções para criar um pacote MSIX para seu aplicativo Electron:

Opção 1: Usando a CLI do Winapp diretamente – mais configurável, funciona com qualquer empacotador
Opção 2: Usando o Criador MSIX do Electron Forge – Melhor integrado ao fluxo de trabalho do Forge

Escolha a opção que melhor se ajusta ao fluxo de trabalho.

Opção 1: usar a CLI do winapp diretamente (recomendado para flexibilidade)

Essa abordagem oferece mais controle sobre o processo de empacotamento e funciona com qualquer empacotador Electron.

Construa seu aplicativo Electron

Para empacotar seu aplicativo Electron com MSIX, precisamos primeiro criar o layout de produção. Com o Electron Forge, podemos usar o comando de pacote:

# Package with Electron Forge (or your preferred packager)
npx electron-forge package

Isso criará uma versão de produção do seu aplicativo na ./out/ pasta. O nome exato da pasta dependerá do nome e da arquitetura do aplicativo (por exemplo, my-windows-app-win32-x64).

Criar o pacote MSIX

Agora, use a CLI do winapp para criar e assinar um pacote MSIX do seu aplicativo empacotado:

npx winapp pack .\out\<your-app-folder> --output .\out --cert .\devcert.pfx --manifest .\Package.appxmanifest

Substitua <your-app-folder> pelo nome da pasta real criado por Electron Forge (por exemplo, my-windows-app-win32-x64 para x64 ou my-windows-app-win32-arm64 para ARM64).

A --manifest opção é opcional. Se não for fornecido, ele procurará um Package.appxmanifest na pasta que está sendo empacotada ou no diretório atual.

A --cert opção também é opcional. Se não for fornecido, o msix não será assinado.

A --output opção também é opcional. Se não for fornecido, o diretório atual será usado.

O pacote MSIX será criado como ./out/<your-app-name>.msix.

Dica

Você pode adicionar esses comandos aos seus package.json scripts para conveniência:

{
  "scripts": {
    "package-msix": "npm run build-csAddon && npx electron-forge package && npx winapp pack ./out/my-windows-app-win32-x64 --output ./out --cert ./devcert.pfx --manifest Package.appxmanifest"
  }
}

Apenas certifique-se de atualizar o caminho para corresponder ao nome da pasta de saída real.

Opção 2: Usando o MSIX Maker do Electron Forge (para usuários do Forge)

Se você já estiver usando o Electron Forge, poderá integrar o empacotamento MSIX diretamente ao fluxo de trabalho do Forge usando o @electron-forge/maker-msix maker.

Instalar o MSIX Maker

npm install --save-dev @electron-forge/maker-msix

Configurar forge.config.js

Adicione o fabricante MSIX ao seu forge.config.js:

module.exports = {
  // ... other config
  makers: [
    {
      name: '@electron-forge/maker-msix',
      config: {
        appManifest: '.\\Package.appxmanifest',
        windowsSignOptions: {
          certificateFile: '.\\devcert.pfx',
          certificatePassword: 'password'
        }
      }
    }
  ],
  // ... rest of your config
};

Atualize Package.appxmanifest

O gerador MSIX do Electron Forge usa um layout de pasta diferente da abordagem CLI do winapp. Ele coloca seu aplicativo dentro de uma app\ pasta no MSIX. Essa pasta é criada automaticamente durante o empacotamento. Você não precisa criá-la por conta própria. Atualize o Executable caminho no seu Package.appxmanifest para que ele aponte para a pasta app.

<Applications>
  <Application Id="myApp"
    Executable="app\my-app.exe"
    EntryPoint="Windows.FullTrustApplication">
    <!-- ... rest of your application config -->
  </Application>
</Applications>

Substitua my-app.exe pelo nome executável real. Isso é baseado no campo productName (ou name) em seu package.json.

Note

O gerador Forge MSIX procura ferramentas do SDK do Windows com base no MinVersion em seu Package.appxmanifest. Se você receber um erro sobre o WindowsKit não ter sido encontrado, verifique se a versão do SDK especificada está instalada em MinVersion seu computador ou atualize MinVersion para corresponder a uma versão do SDK instalada.

Criar o pacote MSIX

Agora você pode criar o pacote MSIX. Use o --targets flag para executar apenas o gerador MSIX (caso contrário, o Forge executará todos os geradores configurados):

npx electron-forge make --targets @electron-forge/maker-msix

O pacote MSIX será criado na ./out/make/msix/<arch>/ pasta (por exemplo, ./out/make/msix/arm64/ ou ./out/make/msix/x64/).

Dica

Essa abordagem é mais integrada ao fluxo de trabalho do Electron Forge e manipula automaticamente o empacotamento e a criação do MSIX em uma etapa.

Instalar e testar o MSIX

Primeiro, instale o certificado de desenvolvimento (configuração única):

# Run as Administrator:
npx winapp cert install .\devcert.pfx

Agora instale o pacote MSIX. Clique duas vezes no arquivo msix ou execute o seguinte comando:

# Option 1 output:
Add-AppxPackage .\out\<your-app-name>.msix

# Option 2 output:
Add-AppxPackage .\out\make\msix\<arch>\<your-app-name>.msix

Substitua <your-app-name> e <arch> pelos valores reais da saída do build.

Seu aplicativo será exibido no Menu Iniciar! Inicie-o e teste seus recursos de API Windows.

Opções de distribuição

Depois de ter um pacote MSIX funcional, você terá várias opções para distribuir seu aplicativo:

Download Direto

Hospede o pacote MSIX em seu site para download direto. Certifique-se de assiná-lo com um certificado de autenticação de código de uma AC (autoridade de certificação) confiável para que os usuários possam instalá-lo sem avisos de segurança.

Microsoft Store

Envie seu aplicativo para o Microsoft Store para a distribuição mais ampla e as atualizações automáticas. Você precisará:

Criar uma conta de Microsoft Partner Center
Reservar o nome do aplicativo
Atualize Package.appxmanifest com a identidade da sua loja. Não é necessário assinar o msix, o processo de publicação da loja assinará automaticamente.
Enviar para certificação

Saiba mais: Publish seu aplicativo no Microsoft Store

Distribuição Empresarial

Distribua diretamente aos clientes corporativos por meio de:

Portal da Empresa – Para organizações que usam o Intune
Download Direto – Hospedar o MSIX em seu site
Sideloading – Instalar por meio do PowerShell ou do Instalador de Aplicativos

Saiba mais: Distribuir aplicativos fora da Loja

Instalador de Aplicativo

Crie um .appinstaller arquivo para atualizações automáticas:

<?xml version="1.0" encoding="utf-8"?>
<AppInstaller
    Uri="https://your-domain.com/packages/myapp.appinstaller"
    Version="1.0.0.0"
    xmlns="http://schemas.microsoft.com/appx/appinstaller/2017/2">
    <MainPackage
        Name="YourAppName"
        Version="1.0.0.0"
        Publisher="CN=YourPublisher"
        Uri="https://your-domain.com/packages/myapp.msix"
        ProcessorArchitecture="x64" />
    <UpdateSettings>
        <OnLaunch HoursBetweenUpdateChecks="24" />
    </UpdateSettings>
</AppInstaller>

Saiba mais: Visão geral do arquivo do Instalador de Aplicativos

Próximas etapas

Parabéns! Você empacotou com êxito seu aplicativo Electron habilitado para Windows para distribuição! 🎉

Recursos adicionais

Documentação da CLI do winapp – Referência completa da CLI
Exemplo de aplicativo Electron – exemplo totalmente funcional
Documentação do empacotamento MSIX – Saiba mais sobre o MSIX
aplicativo do Windows Certification Kit – Testar seu aplicativo antes do envio para a Loja

Retornar à Visão Geral

Visão geral de introdução – Retornar ao guia principal
Configurando o ambiente de desenvolvimento – examinar as etapas de instalação
Criando um Addon Phi Silica – Revisar a criação do addon
Criando um Addon WinML – Aprenda sobre a integração com WinML

Obter Ajuda

Encontrou um bug?Registrar um problema

Boas distribuições! 🚀

Comentários

Esta página foi útil?

Last updated on 2026-05-12