Empacotamento e Distribuição de Apps Electron

Disponibilizar um app Electron para usuários reais envolve um pipeline de quatro etapas: empacotar o app em um instalador nativo da plataforma, assinar e notarizar para que os sistemas operacionais confiem nele, distribuir por um canal acessível aos usuários e configurar a atualização automática para mantê-los atualizados. A ferramenta escolhida para executar esse pipeline é a primeira decisão, e em 2026 ela se resume a duas opções: Electron Forge ou electron-builder. Este guia percorre o caminho completo com configurações prontas para uso, as regras de assinatura de código que mudaram em 2023 e 2024, e um workflow funcional no GitHub Actions que compila as três plataformas em paralelo — porque não é possível compilar tudo para todas as plataformas a partir de uma única máquina.

Electron Forge vs electron-builder em 2026

Escolha o Electron Forge se quiser um pipeline completo com suporte oficial; escolha o electron-builder se quiser o auto-updater integrado mais maduro e a maior base de usuários na comunidade. Ambos produzem instaladores assinados e atualizáveis para macOS, Windows e Linux. A diferença está no modelo de suporte e na filosofia, não na capacidade.

O Electron Forge é a ferramenta recomendada pelo projeto. É uma solução completa para empacotar e distribuir aplicações Electron que combina diversos pacotes de propósito único em um pipeline de build completo e funcional desde o início, incluindo assinatura de código, instaladores e publicação de artefatos. O Forge absorveu os utilitários mais antigos @electron/packager e @electron/osx-sign em seu sistema de Makers e Publishers. É importante destacar que, se você optar por não usar o Electron Forge, as demais ferramentas de terceiros são mantidas por membros da comunidade Electron e não contam com suporte oficial do projeto Electron.

O electron-builder é essa alternativa da comunidade — e a mais baixada, na faixa de 2 a 3 milhões de instalações semanais, dependendo da fonte consultada. Em junho de 2026, a versão estável atual é a 26.15.3, com novas versões lançadas várias vezes por mês, portanto fixe a versão e verifique novamente antes de cada ciclo de lançamento. A próxima versão principal, v27, está em alpha em junho de 2026 (linha 27.0.0-alpha): ela migra o electron-builder para ES modules nativos, eleva o requisito mínimo de runtime para Node.js 22.12 e remove APIs há muito depreciadas, portanto planeje uma verificação de Node e configuração antes de adotá-la — mas o canal estável ainda é o 26.x por enquanto. O motivo pelo qual muitas equipes o escolhem é o updater integrado: o electron-builder é uma solução completa que adiciona uma única dependência, gerencia internamente os requisitos adicionais e substitui recursos utilizados pelos mantenedores do Electron — como o auto-updater — por implementações próprias.

Este artigo utiliza o electron-builder nos exemplos de configuração porque seu bloco declarativo no package.json se mapeia de forma clara para cada alvo de plataforma, e seu companion electron-updater é o padrão de fato para atualizações self-hosted. Os conceitos se transferem para o Forge caso você prefira a rota oficial.

E o Tauri?

O Tauri 2.x é a alternativa mais leve e confiável ao Electron quando um bundle de ~100 MB é um impedimento real. Ele exibe sua UI através da WebView nativa do sistema operacional em vez de empacotar um runtime Chromium completo, o que produz binários dramaticamente menores (em ordem de grandeza, não exatamente). A troca é real: você abre mão da consistência de renderização do Electron entre máquinas e de seu vasto ecossistema de npm e módulos nativos, e precisa lidar com a fragmentação de versões de WebView entre os sistemas operacionais dos usuários. O Tauri é a escolha certa para um utilitário pequeno e sensível à segurança; o Electron se mantém à frente quando a fidelidade de UI e a profundidade do ecossistema importam mais do que o espaço em disco.

Empacotamento por plataforma com electron-builder

O electron-builder produz instaladores nativos a partir de um único bloco build no package.json. Defina uma configuração de nível superior mais chaves mac, win e linux por plataforma, nomeando os targets desejados. Uma configuração mínima multiplataforma tem esta aparência:

{
  "build": {
    "appId": "com.example.myapp",
    "productName": "MyApp",
    "directories": { "output": "dist" },
    "files": ["dist-app/**/*", "package.json"],
    "mac": {
      "category": "public.app-category.productivity",
      "target": ["dmg", "zip"],
      "hardenedRuntime": true,
      "notarize": true
    },
    "win": {
      "target": ["nsis"]
    },
    "linux": {
      "target": ["AppImage", "deb", "rpm"],
      "category": "Utility"
    },
    "publish": [{ "provider": "github" }]
  }
}

Cada target corresponde a um formato de instalador real:

Dois detalhes sobre targets do electron-builder costumam confundir as pessoas. O target zip no macOS não é opcional se você usar auto-update: o target zip para macOS é obrigatório para o Squirrel.Mac, caso contrário o arquivo latest-mac.yml não pode ser criado, o que causa um erro no autoUpdater — e como o target padrão do macOS já é dmg+zip, geralmente não é necessário especificá-lo explicitamente. Para o auto-update especificamente, a aplicação macOS precisa ser assinada para que as atualizações automáticas funcionem, e os targets padrão suportados são DMG (macOS), AppImage/DEB/Pacman/RPM (Linux) e NSIS (Windows). Execute um build com npx electron-builder --mac --win --linux, mas observe que você só pode compilar completamente os instaladores assinados de uma determinada plataforma nessa própria plataforma — razão pela qual o CI é fundamental mais adiante.

Sobre a linha de base de segurança: este artigo pressupõe que seu app já opera com a postura de segurança recomendada pelo Electron — um script de preload com contextIsolation habilitado e nodeIntegration desabilitado. Nunca distribua o inverso; o empacotamento não corrige um renderer inseguro.

Assinatura de código e notarização: a cadeia de dependências

Esta é a regra que quebra mais lançamentos no macOS do que qualquer outra: um app macOS não assinado pode notificar o usuário sobre uma atualização disponível, mas não pode instalá-la silenciosamente. A assinatura de código é um pré-requisito para a notarização, e a notarização é um pré-requisito para o auto-update funcional no macOS. Sua aplicação precisa ser assinada para que as atualizações automáticas funcionem no macOS — este é um requisito do Squirrel.Mac. Pule a assinatura e toda a cadeia subsequente colapsa.

macOS: assinar, depois notarizar

Você precisa de um certificado Apple Developer ID, que exige associação. O Apple Developer Program custa 99 USD por ano de associação, com preços listados em moeda local durante o cadastro — não “EUR99” — e a notarização está incluída: uma vez membro do Apple Developer Program, você pode notarizar apps para Mac sem custo adicional. A notarização (varredura automatizada de malware da Apple) é obrigatória para apps com Developer ID distribuídos fora da Mac App Store desde o macOS 10.15 Catalina.

No electron-builder, defina hardenedRuntime: true e notarize: true no bloco mac (conforme mostrado acima) e forneça as credenciais por meio de variáveis de ambiente no momento do build — nunca no repositório:

# Certificado de assinatura macOS (arquivo .p12 codificado em base64) e sua senha
export CSC_LINK="$(base64 -i developer-id.p12)"
export CSC_KEY_PASSWORD="••••••"
# Credenciais de notarização (API do App Store Connect ou senha específica de app do Apple ID)
export APPLE_ID="you@example.com"
export APPLE_APP_SPECIFIC_PASSWORD="abcd-efgh-ijkl-mnop"
export APPLE_TEAM_ID="XXXXXXXXXX"

Windows: a mudança no SmartScreen em 2024

Inicie sua decisão sobre Windows com a mudança que quase todos os guias mais antigos ignoram. Certificados EV não contornam mais o SmartScreen: anos atrás, assinar com um certificado Extended Validation gerava reputação positiva no SmartScreen por padrão, mas esse comportamento não existe mais, e pagar um valor premium por um certificado EV apenas para evitar avisos do SmartScreen não se justifica mais. Um instalador assinado com EV agora constrói reputação de download exatamente como um certificado Organization Validated (OV) mais barato.

A outra mudança diz respeito ao local onde as chaves devem residir. Desde 1º de junho de 2023, as chaves privadas de assinatura de código devem ser armazenadas em hardware certificado — razão exata pela qual um certificado OV em token USB quebra o CI sem interação humana. A documentação de assinatura Windows do Tauri marca o mesmo limite: o guia padrão deles se aplica apenas a certificados OV adquiridos antes de 1º de junho de 2023, e para certificados recebidos após essa data eles direcionam ao processo de token de hardware do emissor.

O padrão mais limpo para 2026 contorna completamente o token. O Azure Artifact Signing — anteriormente chamado de Trusted Signing — é um serviço de assinatura de código totalmente gerenciado e integrado ao Azure. Ele assina a partir da nuvem sem token USB, executa nativamente em pipelines de CI/CD e armazena chaves em HSMs gerenciados pela Microsoft. Use esta ordem de decisão:

1. Azure Artifact Signing em primeiro lugar. É nativo para CI e de baixo custo (a Microsoft documenta planos baseados em consumo na faixa de ~$10/mês para projetos pequenos). A disponibilidade é limitada a organizações nos EUA, Canadá, UE e Reino Unido, enquanto desenvolvedores individuais estão atualmente limitados aos EUA e Canadá.
2. Certificado OV da DigiCert, Sectigo ou GlobalSign se você estiver fora dessas regiões. Certificados OV são funcionalmente equivalentes ao Azure Artifact Signing para fins de SmartScreen.
3. Mantenha um certificado EV que você já possui até ele expirar — mas se você já tem um certificado EV, ele ainda é válido e funcional para assinatura, embora pagar o valor premium do EV apenas para evitar avisos do SmartScreen não seja mais justificável. Não compre um novo por esse motivo.

Assinado vs não assinado

Builds não assinados são aceitáveis para um público de desenvolvedores familiarizado com as etapas de contorno. Para usuários não técnicos — e para qualquer app que se auto-atualize no macOS — a assinatura é inegociável.

Atualizações automáticas com electron-updater

O electron-updater (companion do electron-builder) oferece atualizações self-hosted multiplataforma com código mínimo. Ele suporta GitHub Releases, Amazon S3, DigitalOcean Spaces, Keygen e um servidor HTTP(S) genérico nativamente, e precisa de apenas duas linhas de código para funcionar. O caso mais comum:

const { autoUpdater } = require("electron-updater");

app.whenReady().then(() => {
  createWindow();
  autoUpdater.checkForUpdatesAndNotify();
});

Chame autoUpdater.checkForUpdatesAndNotify() — e não chame setFeedURL, pois o electron-builder cria automaticamente um arquivo interno app-update.yml durante o build. O local onde você hospeda os releases é definido pelo bloco publish na sua configuração de build; apontá-lo para { "provider": "github" } significa que uma tag enviada dispara o CI, faz upload dos artefatos para um GitHub Release, e o updater os encontra automaticamente. No macOS, essa única linha não faz nada útil a menos que o build esteja assinado e notarizado — a mesma cadeia da seção anterior. O Linux não possui um mecanismo universal de auto-update; atualizações de AppImage funcionam via electron-updater, mas usuários de deb/rpm atualizam pelo gerenciador de pacotes.

Canais de distribuição

Escolha os canais com base no alcance do público e no quanto de receita e confiança você deseja manter:

• Seu próprio site. Controle total, assinado ou não, sem comissão, e se integra diretamente ao electron-updater via GitHub Releases ou S3.
• GitHub Releases. Hospedagem gratuita, histórico de versões e o caminho de menor resistência para integração com auto-update.
• Mac App Store. Aumenta a descoberta, mas exige sandboxing e revisão, e cobra a comissão padrão de 30% da Apple — reduzida para 15% pelo App Store Small Business Program para desenvolvedores com receita anual abaixo de USD 1 milhão.
• Microsoft Store. Vale a pena pelo benefício do SmartScreen: publicar um pacote MSIX pela Microsoft Store significa que a Microsoft re-assina seu pacote automaticamente, portanto os usuários nunca veem um aviso do SmartScreen e você nunca precisa comprar ou renovar um certificado.
• Homebrew Cask. Distribuição gratuita e amigável para desenvolvedores no macOS via pull request para o repositório de casks — ideal para alcançar usuários técnicos com brew install.

Uma observação prática que vale ter em mente: como um renderer Electron é uma janela Chromium, instrumentação de session replay do navegador funciona sem modificações em um build desktop empacotado, o que é uma das poucas maneiras práticas de observar regressões de UI que surgem apenas após o empacotamento ou auto-update na máquina do usuário — fluxos de menu nativo e bandeja do sistema, fluxos de diálogo de arquivo, diferenças de CSP em builds assinados — e que nunca aparecem durante o desenvolvimento com electron ..

Compilando as três plataformas no CI com GitHub Actions

Não é possível compilar para todas as plataformas localmente: a notarização de DMG requer ferramentas do macOS, e instaladores Windows assinados requerem ferramentas do Windows. O caminho mais realista em 2026 é uma matrix no GitHub Actions executando macos-latest, windows-latest e ubuntu-latest em paralelo, com segredos de assinatura injetados como variáveis de ambiente criptografadas. Um release.yml completo que compila e publica ao criar uma tag:

name: Release
on:
  push:
    tags: ["v*"]

jobs:
  release:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - name: Build, sign, and publish
        run: npx electron-builder --publish always
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Assinatura + notarização macOS (lido apenas no macos-latest)
          CSC_LINK: ${{ secrets.MAC_CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.MAC_CSC_KEY_PASSWORD }}
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
          # Windows: credenciais do Azure Artifact Signing (lido apenas no windows-latest)
          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}

Cada runner compila apenas os targets de sua própria plataforma, o electron-builder assina usando as credenciais presentes no ambiente daquele runner, e --publish always faz upload de cada artefato mais os metadados de atualização latest*.yml para um único GitHub Release. Armazene todos os segredos nos segredos do repositório ou de ambiente — nunca no arquivo de workflow. Como o Azure Artifact Signing funciona com GitHub Actions e Azure DevOps por meio de variáveis de ambiente simples, o job do Windows não precisa de token USB nem de runner self-hosted.

Distribuir um app Electron é menos sobre um comando mágico e mais sobre respeitar a cadeia: assine para poder notarizar, notarize para que o auto-update no macOS funcione, e execute tudo em uma matrix de CI porque nenhuma máquina única consegue compilar para as três plataformas. Configure o bloco build, adicione o electron-updater, faça commit de um release.yml, e seu próximo git tag v1.0.0 && git push --tags produzirá instaladores assinados e atualizáveis para todas as plataformas de uma só vez.

Perguntas Frequentes

Posso compilar instaladores assinados para macOS, Windows e Linux em uma única máquina?

Não. A notarização de DMG requer ferramentas do macOS e instaladores Windows assinados requerem ferramentas do Windows, portanto nenhuma máquina única consegue produzir builds assinados para todas as três plataformas. Você pode compilar para a plataforma em que está trabalhando, e o electron-builder suporta alguma compilação cruzada, mas a assinatura e a notarização estão vinculadas à plataforma. A abordagem mais realista em 2026 é uma matrix no GitHub Actions executando macos-latest, windows-latest e ubuntu-latest em paralelo, onde cada runner compila e assina apenas os targets de sua própria plataforma.

A Microsoft Store remove os avisos do SmartScreen sem um certificado de assinatura de código?

Sim. Publicar um pacote MSIX pela Microsoft Store significa que a Microsoft re-assina seu pacote automaticamente, portanto os usuários nunca veem um aviso do SmartScreen e você nunca precisa comprar ou renovar um certificado. Isso torna a Microsoft Store uma forma eficaz de eliminar tanto os custos com certificados quanto o processo de construção de reputação. A contrapartida é o envio para a loja, a revisão e o empacotamento do app como MSIX em vez de distribuir um instalador NSIS ou MSI independente diretamente do seu próprio site.

Por que meu app macOS notifica os usuários sobre atualizações, mas nunca as instala automaticamente?

O build quase certamente não está assinado. No macOS, uma aplicação precisa ser assinada para que as atualizações automáticas funcionem, pois o Squirrel.Mac exige isso. Um app não assinado pode detectar e notificar o usuário de que uma nova versão existe, mas não pode substituir o binário silenciosamente. A solução é a cadeia completa: obtenha um certificado Apple Developer ID, assine o app e depois notarize-o. A assinatura de código é um pré-requisito para a notarização, e a notarização é um pré-requisito para o auto-update silencioso no macOS.

Ainda vale a pena pagar por um certificado EV para evitar avisos do SmartScreen no Windows?

Não. Certificados EV anteriormente ignoravam o SmartScreen completamente no primeiro download, mas a Microsoft removeu esse comportamento de reputação instantânea em 2024. Um instalador assinado com EV agora constrói reputação de download exatamente como um certificado Organization Validated mais barato, portanto pagar o valor premium do EV apenas para evitar o SmartScreen não se justifica mais. Para a maioria das equipes em 2026, o padrão mais adequado é o Azure Artifact Signing, que assina a partir da nuvem sem token USB, ou um certificado OV se você estiver fora das regiões elegíveis.