Aggiornamento automatico dell'app Electron: Una guida pratica 2026

Ti sei già sbarazzato della build di Electron, la pagina di rilascio è live e arriva il primo ticket di supporto prima che il macchinario del caffè si fermi. Un utente dice che l'app non ha trovato l'aggiornamento. Un altro l'ha scaricato ma non può installarlo. Un terzo sta ancora utilizzando una versione vecchia con un flusso di autenticazione rotto, mentre i tuoi log mostrano quasi nulla di utile.

È questa la realtà scomoda di Aggiornamento automatico dell'app Electron. L'aggiornatore API è solo un componente. Una versione di produzione dipende inoltre da firma di piattaforma, politica di trasporto, manifesti, hosting, eventi di ciclo di vita, osservabilità, controlli di rollout e un percorso di rollback. Considera qualsiasi uno di questi come facoltativo e un patch di routine può diventare un incidente notturno.

Indice dei contenuti

• La vicenda dell'aggiornamento alle 2 del mattino che ha ispirato questa guida
• Scegliere il percorso giusto per l'aggiornatore dell'app Electron
• Implementare il flusso di aggiornamento automatico nel processo principale
  • Configura il target di pubblicazione per primo
  • Pianifica controlli e esponi gli eventi di ciclo di vita
  • Tenere informato il renderer senza bloccare il lavoro
• Collegare CI/CD per rilasci firmati e manifesti
  • Fare esplicita la firma in CI
• Strategie di rollout, canali e strategia di rollback
  • Usa le cohorti prima di una esposizione ampia
• Trattare l'aggiornamento automatico come un controllo di sicurezza
  • Proteggere i metadati con la stessa cura del binario
• La guida e il check-list per l'aggiornamento di produzione
  • Gli ostacoli di pre-rilascio
  • Canarino e rilascio completo
  • La risposta all'incidente

L'incidente di aggiornamento alle 2 del mattino che ha iniziato questa guida

La versione di rilascio aveva superato le verifiche di integrità e sembrava normale. Tuttavia, verso la fine di venerdì, un sviluppatore aveva pubblicato un build di Electron non firmato, e il job di pubblicazione aveva caricato abbastanza asset per far sembrare completa la versione di rilascio. L'applicazione era stata lanciata in testing, ma nessuno aveva eseguito il percorso di aggiornamento da un build di produzione installato.

Alle 2:08 del mattino, PagerDuty ha avvertito l'ingegnere di turno. Un nuovo flusso di autenticazione non era riuscito per parte della flotta, e gli utenti che avevano ricevuto l'aggiornamento non potevano completare l'accesso. Gli altri utenti erano rimasti sulla versione precedente perché l'aggiornatore non era riuscito a verificare o installare l'artifact. Alcuni clienti avevano una versione di rilascio rotta, mentre il resto della flotta aveva una versione diversa senza una spiegazione chiara.

L'indagine ha seguito cinque controlli:

1. Controlla il feed di rilascio La versione binaria esisteva, ma i metadati attesi non stabilivano chiaramente quali clienti dovrebbero riceverla. Un manifesto è un contratto tra la pipeline di rilascio e i clienti installati, non un dettaglio di caricamento facoltativo.
2. Ispeziona la firma. La rilascio non era firmata correttamente, quindi la verifica fallì sui piattaforme interessate. La firma deve impedire la pubblicazione quando è mancante o invalida.
3. Confronta i log dei clienti. Gli errori di aggiornamento non raggiunsero la telemetria centrale. L'applicazione inghiottì l'evento e continuò a funzionare, lasciando il team senza prove affidabili.
4. Controlla i controlli di distribuzione. Non esisteva un canale interno o un gruppo di staging. Tutti i clienti idonei utilizzavano lo stesso feed, quindi il fallimento si diffuse senza un punto di contenimento.
5. Cerca un rollback. La squadra non aveva una procedura testata per ripubblicare la versione precedente o per dirigere i clienti lontano dalla rilascio rotto.

La documentazione ufficiale di Electron chiarisce i limiti della piattaforma. Linux non supporta l'aggiornamento automatico integrato.e le richieste di aggiornamento di macOS devono soddisfare Requisiti di sicurezza di trasporto dell'applicazioneLa documentazione identifica anche la firma come prerequisito per aggiornamenti macOS affidabili e verifiche di rilascio. La documentazione di autoaggiornamento di Electron Definisce le API restrizioni, mentre il sistema di rilascio deve attuare i controlli operativi circostanti.

Lezione post mortem: Un aggiornatore che non può spiegare cosa è accaduto è un tentativo di installazione remota con telemetria mancante.

Il costo si è esteso oltre il tempo di ingegneria. I clienti hanno perso fiducia nel client desktop, il supporto doveva spiegare comportamenti inconsistenti, e il team ha trascorso il giorno successivo a ricostruire un processo di rilascio che avrebbe dovuto esistere prima dell'incidente.

Trattare l'autoaggiornamento come un Sistema operativo. La firma è una porta di uscita di rilascio, i manifesti definiscono il contratto del client, i canali di distribuzione limitano l'esposizione, e il rollback rimane un percorso testato piuttosto che un'invenzione di emergenza.

Scegliere il percorso giusto per l'aggiornatore di Electron

Alle 2 del mattino, la scelta sbagliata dell'aggiornatore diventa un problema operativo. Un aggiornamento binario nativo deve gestire la firma, i manifesti, gli installatori e il rollback. Un cambiamento di JavaScript o CSS eseguito solo nel renderer segue un percorso diverso. Le restrizioni di hosting anche contano: un piccolo progetto GitHub-hosted non ha bisogno dei medesimi controlli di rilascio di un servizio di distribuzione aziendale.

For i progetti che utilizzano electron-builder con pubblicazione di artefatti firmati, è solitamente il default pratico. Il suo ecosistema copre i target di pubblicazione, i manifesti di rilascio, i download degli artefatti e l'installazione alla prossima esecuzione. Supporta diversi modelli di hosting, ma il tuo team è ancora responsabile della firma, della disponibilità del feed, della politica dei canali, dei controlli di rilascio e della monitoraggio. L' integrazione del aggiornamento di Electron per __CAPGO_KEEP_0__ Electron updater integration for Capgo suita le squadre che desiderano un'integrazione di piccole dimensioni intorno ai rilasci di __CAPGO_KEEP_0__ . Verifica all'avvio e poi su un intervallo ricorrente, il che mantiene la configurazione semplice ma lascia meno spazio per la selezione avanzata dei canali, il traffico in fase di staging e le regole di rollback personalizzate. Il pacchetto è ragionevole per un processo di rilascio di piccole dimensioni, a condizione che i rilasci di __CAPGO_KEEP_1__ e la sua disponibilità corrispondano ai requisiti operativi.

update-electron-app suits teams that want a small integration around GitHub Releases. It checks at startup and then on a recurring interval, which keeps the setup simple but leaves less room for advanced channel selection, staged traffic, and custom rollback rules. The package is reasonable for a small release process, provided GitHub Releases and its availability match your operational requirements.

A un servizio personalizzato come Hazel, Nuts o un feed interno si adatta quando l'autorizzazione alla rilascio, la destinazione del tenant, i registri di audit o le regole di distribuzione regolamentate giustificano il costo di implementazione. L'equilibrio è la proprietà in corso. Il tuo team deve definire le semantiche del manifesto, proteggere le chiavi di firma, preservare la compatibilità del client, e testare i download falliti, le rilasci rifiutati e il comportamento di rollback.

Le aggiornamenti in tempo reale possono inviare modifiche al renderer senza ricostruire la shell nativa. Non sostituiscono gli aggiornamenti binari quando cambiano Electron, i moduli nativi, i permessi o il comportamento dell'installatore. Usa electron-updater a meno che non sia necessario una logica di distribuzione personalizzata. Se è necessaria una logica personalizzata, costruisci intorno alle convenzioni di manifesto e artefatto esistenti piuttosto che ricreare il comportamento di download e differenziale di aggiornamento. Un percorso affidabile è quello che il tuo team può osservare, mettere in scena e annullare sotto pressione.

Implementare il Flusso di Aggiornamento Automatico nel Processo Principale

Il processo principale dovrebbe gestire le verifiche di aggiornamento e l'installazione. Il renderer può visualizzare lo stato, ma non dovrebbe decidere se un aggiornamento eseguibile è affidabile o quando l'applicazione esce.

Configura il target di pubblicazione per primo

Una configurazione minimale di electron-builder potrebbe avere questo aspetto:

{
  "build": {
    "appId": "com.example.desktop",
    "publish": [
      {
        "provider": "s3",
        "bucket": "example-electron-releases",
        "channel": "stable"
      }
    ],
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    }
  }
}

Tenere separate le feed beta e stabili. Un canale è una politica di rilascio, non un etichetta nell'interfaccia utente. Ogni canale dovrebbe risolvere all'artefatto firmato corretto e al manifesto.

Pianificare le verifiche e esporre gli eventi di ciclo di vita

Chiamando checkForUpdates() Solo durante l'avvio è un comune errore di produzione. Un utente può lasciare l'applicazione aperta per giorni, quindi il processo principale ha bisogno di un intervallo controllato e di una strategia di riprova che rispetti l'operazione offline.

const { app, BrowserWindow, ipcMain } = require('electron');
const { autoUpdater } = require('electron-updater');

let mainWindow;
let isQuitting = false;
let retryDelay = 60 * 1000;

function sendUpdateStatus(status, payload = {}) {
  if (mainWindow && !mainWindow.isDestroyed()) {
    mainWindow.webContents.send('update-status', { status, ...payload });
  }
}

function scheduleUpdateCheck() {
  setTimeout(async () => {
    try {
      await autoUpdater.checkForUpdates();
      retryDelay = 60 * 1000;
    } catch (error) {
      sendUpdateStatus('error', { message: error.message });
      retryDelay = Math.min(retryDelay * 2, 30 * 60 * 1000);
    }
    scheduleUpdateCheck();
  }, retryDelay);
}

app.whenReady().then(() => {
  mainWindow = new BrowserWindow({
    webPreferences: {
      preload: require('path').join(__dirname, 'preload.js')
    }
  });

  autoUpdater.autoDownload = true;
  autoUpdater.autoInstallOnAppQuit = false;

  autoUpdater.on('checking-for-update', () => {
    sendUpdateStatus('checking');
  });

  autoUpdater.on('update-available', info => {
    sendUpdateStatus('available', { version: info.version });
  });

  autoUpdater.on('download-progress', progress => {
    sendUpdateStatus('progress', { percent: progress.percent });
  });

  autoUpdater.on('update-downloaded', info => {
    sendUpdateStatus('downloaded', { version: info.version });
  });

  autoUpdater.on('error', error => {
    sendUpdateStatus('error', { message: error.message });
  });

  autoUpdater.checkForUpdates().catch(error => {
    sendUpdateStatus('error', { message: error.message });
  });

  scheduleUpdateCheck();
});

ipcMain.handle('install-update', () => {
  isQuitting = true;
  autoUpdater.quitAndInstall(false, true);
});

app.on('before-quit', event => {
  if (!isQuitting) {
    return;
  }
});

Il comportamento esatto dell'evento di aggiornamento varia a seconda della piattaforma e della configurazione di packaging, quindi testa dagli artefatti installati piuttosto che dal modo di sviluppo. La documentazione di Electron chiama anche in causa le preoccupazioni relative al timing di avvio su Windows, compreso il caso Squirrel first-run. Non attivare un controllo di aggiornamento prima che l'applicazione abbia completato l'inizializzazione specifica della piattaforma di cui ha bisogno.

Tieni informato il renderer senza bloccare il lavoro

Il ponte di preload dovrebbe esporre un API ristretto:

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('updates', {
  onStatus(callback) {
    ipcRenderer.on('update-status', (_event, status) => callback(status));
  },
  install() {
    return ipcRenderer.invoke('install-update');
  }
});

Un barra di avanzamento del renderer può rimanere deliberatamente semplice:

window.updates.onStatus(status => {
  const progress = document.querySelector('#update-progress');
  const message = document.querySelector('#update-message');

  if (status.status === 'progress') {
    progress.hidden = false;
    progress.value = status.percent;
    message.textContent = `Downloading update, ${Math.round(status.percent)}%`;
  }

  if (status.status === 'downloaded') {
    message.textContent = `Version ${status.version} is ready to install`;
  }

  if (status.status === 'error') {
    message.textContent = 'The update could not be downloaded. We will retry later.';
  }
});

Blocca l'installazione dietro il consenso dell'utente in produzione a meno che la tua applicazione non abbia una forte ragione per riavviarsi immediatamente. Imposta un isQuitting flag prima quitAndInstall()perché i gestori di chiusura della finestra normale possono altrimenti impedire all'installatore di prendere il controllo.

Due fallimenti meritano test espliciti. In primo luogo, un cliente già in esecuzione deve chiamare checkForUpdates() su un orario, non solo all'avvio. In secondo luogo, l' error evento deve raggiungere i log e la telemetria. Se l'applicazione ingoia senza segnalare, il tuo Flusso di lavoro di risoluzione dei problemi dell'app Inizia con congetture invece che con prove.

Configurazione di CI/CD per rilasci firmati e manifesti

Il flusso di rilascio è la fonte di verità per ciò che gli utenti installano. Una costruzione locale che funziona su una macchina di un singolo sviluppatore non dimostra che il binario pubblicato, il manifesto, la firma e il canale descrivano tutti la stessa versione.

L'API di pubblicazione di Electron-builder aspetta che i metadati di rilascio e l'obiettivo di aggiornamento viaggino insieme. Per molte configurazioni, ciò significa un artefatto come latest.yml per Windows e latest-mac.yml per macOS, insieme a pacchetti specifici per piattaforma e file di blockmap. Un manifesto mancante può rendere un binario perfettamente valido invisibile ai clienti.

Fare la firma esplicita in CI

Un modello semplificato di GitHub Actions ha questo aspetto:

name: release

on:
  push:
    tags:
      - "v*"

jobs:
  build:
    strategy:
      matrix:
        os: [macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run test
      - run: npm run build

      - name: Build and publish
        shell: bash
        env:
          CSC_LINK: ${{ secrets.CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
          WIN_CSC_LINK: ${{ secrets.WIN_CSC_LINK }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: npx electron-builder --publish always

Usare segreti specifici per piattaforma e tenere il materiale di firma fuori dal repository. Un fallimento di firma dovrebbe fermare il lavoro, non produrre un fallback non firmato che qualcuno carica manualmente.

La configurazione di pubblicazione dovrebbe identificare il provider e il canale in modo coerente:

{
  "build": {
    "publish": {
      "provider": "s3",
      "bucket": "example-electron-releases",
      "channel": "stable",
      "publishAutoUpdate": true,
      "updaterCacheDirName": "example-desktop-updater"
    }
  }
}

Prima della pubblicazione, blocca il lavoro sulla versione del pacchetto, sulla etichetta, sul SHA del commit e sul risultato del test di fumo. Dopo la pubblicazione, verificare che il feed contenga il manifesto previsto e che il manifesto punti all'artefatto esatto generato da quel lavoro. Il guida per la configurazione di integrazione continua è utile quando formalizzi quei controlli, e i team che confrontano l'orchestrazione delle pipeline possono anche trarre vantaggio dall'individuare quando utilizzare insieme Jenkins e Ansible.

I comandi che comunemente espongono una versione di rilascio incompleta sono intenzionalmente noiosi:

npx electron-builder --publish never
test -f dist/latest.yml
test -f dist/latest-mac.yml
find dist -name "*.blockmap" -print

Quei controlli non sostituiscono un test di installazione firmato. Catturano l'errore operativo di caricamento di un binario senza i metadati necessari per scoprirlo.

Rilasci, Canali e Strategia di Annullamento

La feed di rilascio dovrebbe comportarsi più come un obiettivo di distribuzione che come una cartella di download. Mantieni interni, beta, e canali più recenti separati, con ogni canale supportato da un proprio manifesto e set di artefatti firmati. La promozione dovrebbe spostare un rilascio testato tra le politiche, anziché sovrascrivere un file mentre i clienti lo stanno scaricando. La separazione dei canali protegge anche la produzione da costruzioni di test accidentali. L'aggiornatore dovrebbe sapere se un client appartiene a un gruppo di cohorte interno, a un pubblico di beta o alla popolazione stabile prima di valutare la feed.

Utilizza i gruppi di cohorte prima di una esposizione ampia

Un campo di manifesto personalizzato può esprimere la consegna in fase di staging:

Il processo principale può assegnare un bucket stabile per utente, quindi confrontarlo con

version: 4.8.0
path: Example-Setup-4.8.0.exe
sha512: signed-artifact-hash
rolloutPercentage: 10

. L'assegnazione stabile conta. Un utente che si sposta tra stati eleggibili e non eleggibili su ogni controllo riceverà comportamenti imprevedibili e renderà i rapporti di supporto difficili da interpretare. rolloutPercentageinternal

Espandere il cohort solo dopo che la versione ha superato la sua finestra di osservazione. La finestra esatta dovrebbe riflettere il tuo pattern di utilizzo, ma la decisione dovrebbe essere basata su segnali, non su un calendario solo. Tracciare i risultati della verifica dell'aggiornamento, la completamento del download, la salute di avvio, i crash, le eccezioni del renderer, e il successo dell'autenticazione.

Non confondere il rollback con la cancellazione di un artefatto. Gli clienti esistenti possono avere i metadati memorizzati in cache, e alcuni possono già essere in esecuzione della versione danneggiata. Un piano di rollback richiede una versione precedente firmata, un cambio di feed e un comportamento del client che possa riprendersi.

Regola operativa: Il rollback deve essere eseguibile dall'ingegnere di chiamata senza ricostruire l'applicazione durante l'incidente.

In pratica, il runbook dovrebbe promuovere il manifesto della versione precedente di nuovo nel canale interessato, invalidare il marker di staging e confermare che le nuove verifiche risolvano alla versione sicura. Se l'errore è nella shell nativa code piuttosto che nel renderer, un rollback web-layer mirato può essere più veloce. Una piattaforma come Capgo rollouts fasi può essere rilevante per quel livello di consegna separato, ma non dovrebbe oscurare il confine tra un rollback binario nativo e un rollback di bundle web.

Trattare l'aggiornamento automatico come un controllo di sicurezza

Un aggiornatore di Electron scarica l'eseguibile code e può installarlo con poca interazione utente. Ciò rende il percorso di aggiornamento un barriera di sicurezza, non solo una funzione di comodità. La documentazione ufficiale di Electron descrive le restrizioni del sistema come ad esempio ATS di macOS, e la copertura di sicurezza ha documentato uno scenario del 2022 in cui gli attaccanti che controllavano l'infrastruttura di aggiornamento potevano servire pacchetti maliziosi che ancora superavano i controlli di firma code, come discusso nel documentazione di sicurezza di aggiornamento di Electron Builder.

La firma Code rimane fondamentale, ma non è il modello di fiducia intero. Firma ogni rilascio, verifica il certificato e l'identità durante la CI, e mantieni una procedura di rotazione della chiave documentata. Su macOS, combina la firma con la notarizzazione e il runtime hardenato appropriato per la tua applicazione. Su Windows, rendi la proprietà del certificato, la rinnovazione e l'accesso alla costruzione auditabile. Linux richiede una strategia specifica per la distribuzione perché Electron non fornisce un aggiornatore universale integrato lì.

Proteggere i metadati con la stessa cura del binario

Un binario firmato può ancora essere associato al rilascio sbagliato se il canale dei metadati è compromesso o configurato in modo errato. Considera l'aggiunta di una firma di manifesto verificata contro una chiave pubblica incorporata nell'applicazione, imponi una versione minima consentita e rifiuta gli scendi inaspettati a meno che non sia esplicitamente permesso un percorso di recupero autorizzato.

Il feed merita anche controlli di produzione:

• Limitare l'accesso alla pubblicazione: Dai alla CI solo le autorizzazioni necessarie per pubblicare gli asset di rilascio.
• Proteggi i segreti di firma: Tieni i certificati e le chiavi private in un archivio di segreti gestito, non in file di repository.
• Dependenze da fissare: Blocca Electron, electron-builder e dipendenze transitive in CI.
• Recensione degli artefatti: Scansiona i pacchetti generati e confrontali con il commit e la versione previsti.
• Richiedi trasporto sicuro: Segui le linee guida ATS e HTTPS rigorosi per le richieste di aggiornamento.
• Monitora gli errori di verifica: Tratta ripetuti errori di firma o manifesto come eventi di sicurezza, non come rumore di rete ordinario.

L'ecosistema di strumenti mantenuti da Electron continua ad aggiungere copertura di packaging e aggiornamento, ma la manutenzione non elimina la necessità di modellazione di minacce. L'obiettivo pratico è assicurarsi che un attaccante che compromette un bucket, una CDN o un passaggio di costruzione non possa comunque far accettare al client un rilascio non autorizzato. La guida alla verifica della firma fornisce un utile contesto per progettare quella ulteriore layer di verifica.

Il Runbook e il Checklist di Aggiornamento di Produzione

Una rilascia è pronta solo quando un altro ingegnere può operarla sotto pressione. Tieni il checklist vicino al lavoro di distribuzione e al canale di incidente.

Pre-release gates

• Identità della versione: Conferma la versione del pacchetto, la tag di rilascio, l'indirizzo SHA del commit e il changelog concordino.
• Firma: Verifica che ogni artefatto di piattaforma sia firmato e che la notarizzazione o la validazione equivalente sia stata completata.
• Contratto del manifesto: Conferma latest.yml, latest-mac.ymlI hash, le percorso e i blockmaps corrispondono agli artefatti caricati.
• Sicurezza del canale: Pubblica sul feed interno o beta prima di promuovere il canale di rilascio.
• Telemetria: I conferme gli aggiornamenti, il progresso del download, la completamento dell'installazione, la salute di avvio e gli errori stanno arrivando.

Canarino e full rollout

• Controllo del cohort: Inizia con un piccolo pubblico interno o beta deliberatamente selezionato.
• Budget di salute: Mantieni la promozione se i fallimenti di lancio, i fallimenti del download degli aggiornamenti, le eccezioni del renderer o i fallimenti di autenticazione superano i limiti approvati dalla squadra.
• Approvazione della promozione: Richiedi una decisione esplicita di andare o no prima di spostare la versione nella feed stabile.
• Impatto del cliente: Prepara il messaggio di supporto prima della distribuzione ampia, non dopo il primo incidente.

Risposta all'incidente

Se il nuovo binario non riesce a lanciarsi, la creazione di processi si interrompe o le download degli aggiornamenti si interrompono, interrompi immediatamente la promozione. Ripristina il manifesto firmato precedente, invalida il marker di staging e verifica che i clienti freschi risolvano alla versione precedente. Verifica quindi attraverso la telemetria che la flotta si sta riprendendo prima di comunicare la chiusura.

La sequenza esatta dei comandi di rollback dipende dal tuo provider, ma la sequenza dovrebbe sempre essere documentata: Inverti il manifesto del canale alla versione precedente, invalida il tag di staging, invia un marker di aggiornamento forzato se il recupero lo richiede e verifica il percorso di downgrade con la telemetria in tempo reale.Un rollback non testato è solo una speranza.

Capgo offers an Electron updater for delivering signed web-layer changes, targeted channels, rollout controls, and update observability without rebuilding the native shell for every renderer change. If you want to separate native binary releases from controlled JavaScript and CSS delivery, visit Capgo e valutalo insieme al tuo pipeline di rilascio esistente di Electron.