Mise à jour automatique d'applications Electron : Guide pratique 2026

Vous avez livré la build Electron, la page de lancement est en ligne, et le premier ticket de support arrive avant que la machine à café ait fini. Un utilisateur dit que l'application n'a jamais trouvé la mise à jour. Un autre l'a téléchargée mais ne peut pas l'installer. Un troisième continue à utiliser une ancienne version avec un flux d'authentification cassé, tandis que vos journaux montrent presque rien d'utile.

C'est la réalité inconfortable de mise à jour de l'application Electron. Le mise à jour API est seulement un composant. Une mise en production dépend également de la signature de la plateforme, de la politique de transport, des manifestes, de l'hébergement, des événements de cycle de vie, de l'observabilité, des contrôles de déploiement et d'un chemin de reversion. Traitez n'importe lequel de ceux-ci comme optionnel et une mise à jour de routine peut devenir un incident nocturne.

Table des Matières

• L'incident de mise à jour de 2 h du matin qui a déclenché ce guide
• Choisir la Bonne Voie d'Actualisation d'Electron
• Choisir le Bon Chemin de Mise à Jour Electron
  • Configurez d'abord la cible de publication.
  • Configurez d'abord la cible de publication
  • Maintenez l'informateur du rendu sans bloquer le travail
• Configuration de CI/CD pour les sorties signées et les manifestes
  • Rendre explicite la signature dans la CI
• Stratégies de déploiement, de canaux et de retrait
  • Utiliser les cohortes avant une exposition large
• Gérer l'auto-mise à jour comme un contrôle de sécurité
  • Protéger les métadonnées avec autant de soin que le binaire
• Le guide de mise à jour de production et de checklist
  • Les portes de pré-sortie
  • Canary et déploiement complet
  • Réponse aux incidents

L'incident de mise à jour de 2 h du matin qui a déclenché ce guide

La mise en production a passé la CI et semblait ordinaire. Le vendredi soir, un développeur a poussé une build non signée d'Electron, et le job de publication a téléchargé suffisamment d'actifs pour rendre la mise en production complète. L'application a démarré en test, mais personne n'avait exercé la voie de mise à jour à partir d'une build de production installée.

At 2:08 a.m., PagerDuty avertit l'ingénieur en charge. Une nouvelle flux d'authentification a échoué pour une partie de la flotte, et les utilisateurs qui ont reçu la mise à jour ne pouvaient pas terminer la connexion. Les autres utilisateurs sont restés sur la version précédente car l'actualiseur ne pouvait pas vérifier ou installer l'artifact. Certains clients avaient une version défectueuse, tandis que le reste de la flotte exécutait une version différente sans explication claire.

La recherche a suivi cinq vérifications :

1. Vérifiez la chaîne de mise à jour. Le binaire existait, mais les métadonnées attendues n'ont pas établi clairement les clients qui devaient le recevoir. Un manifeste est un contrat entre la chaîne de mise à jour et les clients installés, et non une détail d'upload facultatif.
2. Inspectez la signature. La mise à jour n'était pas signée correctement, donc la vérification a échoué sur les plateformes affectées. La signature doit bloquer la publication lorsqu'elle est manquante ou invalide.
3. Comparez les journaux des clients. Les erreurs d'actualisation n'ont jamais atteint la télémétrie centrale. L'application a englouti l'événement et a continué à fonctionner, laissant l'équipe sans preuves fiables.
4. Vérifiez les contrôles de déploiement. Il n'y avait pas de canal interne ou de cohorte étalonnée. Tous les clients éligibles ont utilisé la même chaîne, donc l'échec s'est propagé sans point de contenance.
5. Recherchez un roulage. L'équipe n'avait pas de procédure testée pour républier la version précédente ou diriger les clients loin de la version défectueuse.

La documentation officielle d'Electron clarifie les limites du plateforme. Linux has no built-in auto-updater supportet les demandes d'actualisation macOS doivent satisfaire Exigences de sécurité de transport d'applicationsLa documentation identifie également la signature comme un prérequis pour des mises à jour macOS fiables et la vérification des versions de sortie. Documentation d'auto-mise à jour d'Electron définit les contraintes API, tandis que le système de publication doit appliquer les contrôles opérationnels entourants.

Leçon post-mortem : An updater that cannot explain what happened is a remote installation attempt with missing telemetry.

The cost extended beyond engineering time. Customers lost confidence in the desktop client, support had to explain inconsistent behavior, and the team spent the next workday rebuilding a release process that should have existed before the incident.

Mettez à jour automatiquement en tant que système d'exploitation. La signature est une porte de sortie de version, les manifestes définissent le contrat du client, les canaux de déploiement limitent l'exposition, et le retrait est un chemin testé plutôt qu'une invention d'urgence.

Choisir le bon chemin d'actualisation d'Electron

À 2 heures du matin, le mauvais choix d'actualisation devient un problème opérationnel. Une mise à jour de code natif doit gérer la signature, les manifestes, les installateurs et le retrait. Une modification uniquement de JavaScript ou de CSS suit un chemin différent. Les contraintes d'hébergement comptent également : un petit projet hébergé par GitHub ne nécessite pas les mêmes contrôles de version que le service de distribution d'entreprise.

Pour les projets utilisant electron-builder avec la publication de l'artefact signé electron-updater est généralement le choix pratique par défaut. Son écosystème couvre les cibles de publication, les manifestes de version, les téléchargements d'artefacts et l'installation à la prochaine mise en route. Il prend en charge plusieurs modèles d'hébergement, mais votre équipe est toujours responsable de la signature, de la disponibilité de la source, de la politique de canal, des contrôles de déploiement et de la surveillance. L'intégration de l'actualisation d'Electron pour Capgo est pertinente lors de l'évaluation d'un modèle de livraison hybride pour les lots de couches web aux côtés des versions natives.

update-electron-app s'adapte aux équipes qui veulent une petite intégration autour des GitHub Releases. Il vérifie au démarrage et ensuite à intervalles réguliers, ce qui garde la mise en place simple mais laisse moins de place pour la sélection avancée de canal, le trafic étalé et les règles de retrait personnalisées. Le package est raisonnable pour un processus de versionnement simple, à condition que les GitHub Releases et leur disponibilité correspondent aux exigences opérationnelles.

Une service personnalisé tel que Hazel, Nuts ou un flux interne convient lorsque la justification des coûts d'implémentation, la cible de l'abonné, les enregistrements d'audit ou les règles de déploiement réglementé justifient la mise en œuvre. L'échange est une propriété en cours. Votre équipe doit définir les sémiatiques du manifeste, protéger les clés de signature, préserver la compatibilité du client et tester les téléchargements échoués, les libellés rejetés et le comportement de roulage.

Mises à jour en direct peuvent envoyer des modifications uniquement pour le rendu sans reconstruire la coquille native. Elles ne remplacent pas les mises à jour binaires lorsque Electron, les modules natives, les autorisations ou le comportement de l'installateur changent. Use electron-updater unless you need custom rollout logic. Si une logique personnalisée est requise, construisez autour des conventions de manifeste et d'artefact établies plutôt que de recréer le comportement de téléchargement et de mise à jour différentielle. Un chemin fiable est celui que votre équipe peut observer, étager et inverser sous pression.

Implémenter le flux d'actualisation automatique dans le processus principal

Le processus principal doit gérer les vérifications d'actualisation et les installations. Le rendu peut afficher le statut, mais il ne doit pas décider si une mise à jour exécutable est fiable ou quand l'application se ferme.

Configurez la cible de publication en premier

Une configuration minimale d'electron-builder pourrait ressembler à ceci :

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

Conserve les flux bêta et stable séparés. Un canal est une politique de publication, et non une étiquette dans l'interface utilisateur. Chaque canal doit se résoudre à l'artifact signé et au manifeste corrects.

Schedule checks and expose lifecycle events

Appeler checkForUpdates() seul pendant le démarrage est une erreur courante en production. Un utilisateur peut laisser l'application ouverte pendant des jours, donc le processus principal nécessite un intervalle contrôlé et une stratégie de réessai qui respecte l'opération hors ligne.

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;
  }
});

Le comportement exact de l'événement de mise à jour varie en fonction de la plateforme et de la configuration de mise en boîte, donc testez à partir d'artefacts installés plutôt qu'en mode de développement. La documentation d'Electron souligne également les préoccupations de timing de démarrage sur Windows, notamment le cas Squirrel first-run. N'effectuez pas une vérification de mise à jour avant que l'application n'ait terminé l'initialisation spécifique à la plateforme qu'elle nécessite.

Tenir l'informé du rendu sans bloquer le travail

La passerelle de préchargement doit exposer un API étroit :

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 barre de progression côté rendu peut rester volontairement simple :

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

Verrouiller l'installation derrière le consentement de l'utilisateur en production, à moins que votre application n'ait une raison forte de redémarrer immédiatement. Définissez un isQuitting drapeau avant quitAndInstall(), car les gestionnaires de fermeture de fenêtre normaux peuvent autrement empêcher l'installateur de prendre le contrôle.

Deux échecs méritent des tests explicites. Tout d’abord, un client déjà en cours d’exécution doit appeler checkForUpdates() sur un horaire, pas seulement au lancement. Deuxièmement, le error l'événement doit parvenir aux journaux et à la télémétrie. Si l'application l'absorbe sans le signaler, votre flux de dépannage de l'application commence par des suppositions plutôt que par des preuves.

Configuration de CI/CD pour les versions signées et les manifestes

Le modèle de publication d’Electron-builder s’attend à ce que les métadonnées de sortie et la cible de mise à jour voyagent ensemble. Pour beaucoup de configurations, cela signifie un artefact tel que

Le modèle de publication d'Electron-builder s'attend à ce que les métadonnées de la mise en production et la cible de mise à jour voyagent ensemble. Pour de nombreuses configurations, cela signifie un artefact comme latest.yml pour Windows et latest-mac.yml Pour macOS, en plus des packages et fichiers de bloc spécifiques à la plateforme. Un manque de manifeste peut rendre un binaire valide invisible aux clients.

Un modèle simplifié d’Actions ressemble à ceci :

A simplified GitHub Actions pattern looks like this:

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

Utilisez des secrets spécifiques à la plateforme et gardez le matériau de signature à l'extérieur du dépôt. Un échec de signature devrait arrêter le job, et non produire un fallback non signé que quelqu'un télécharge manuellement.

Authentification de publication avec accès étroitement scénarisé

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

Before publication, gate the job on the package version, tag, commit SHA, and smoke-test result. After publication, verify that the feed contains the expected manifest and that the manifest points to the exact artifact generated by that job. The Guide de configuration de l'intégration continue est utile lorsque vous formalisez ces vérifications, et les équipes comparant l'orchestration de pipeline peuvent également bénéficier de la compréhension lorsque utiliser Jenkins et Ansible ensemble.

Les commandes qui exposent fréquemment une version incomplète sont intentionnellement ennuyeuses :

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

Ces vérifications ne remplacent pas un test d'installation signé. Elles détectent cependant l'erreur opérationnelle consistant à télécharger un binaire sans les métadonnées nécessaires aux clients pour le découvrir.

Stratégie de roulage, de canaux et de retrait

Un flux de version devrait se comporter plus comme une cible de déploiement qu'un dossier de téléchargement. Gardez intérieur, bêta, et dernier les canaux séparés, chacun étant soutenu par son propre manifeste et ensemble de artefacts signés. La promotion devrait déplacer une version testée entre les politiques, et non écraser un fichier pendant que les clients le téléchargent.

La séparation des canaux protège également la production contre les builds de test accidentels. L'actualiseur doit savoir si un client appartient à un groupe de cohorte interne, à un public bêta ou à la population stable avant d'évaluer le flux.

Utilisez les cohortes avant une exposition large

A un champ de manifest personnalisé peut exprimer la livraison étalée :

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

Le processus principal peut attribuer un bac stable par utilisateur, puis comparer ce bac avec rolloutPercentage. L'attribution stable compte. Un utilisateur qui passe entre les états éligibles et non éligibles à chaque vérification recevra un comportement imprévisible et rendra les rapports de support difficiles à interpréter.

Élargir le groupe uniquement après que la mise à jour ait survécu à sa fenêtre d'observation. La fenêtre exacte devrait refléter votre modèle d'utilisation, mais la décision devrait être basée sur des signaux, et non sur un calendrier seul. Suivez les résultats de la vérification des mises à jour, la fin de la téléchargement, la santé de lancement, les plantages, les exceptions du rendu, et le succès de l'authentification.

N'établissez pas la confusion entre le roulage en arrière et la suppression d'un artefact. Les clients existants peuvent avoir des métadonnées mises en cache, et certains peuvent déjà exécuter la mauvaise version. Un plan de roulage en arrière nécessite une version signée précédente, une modification de la source, et un comportement de client qui peut se rétablir.

Règle opérationnelle : Le roulage en arrière doit être exécutable par l'ingénieur de permanence sans reconstruire l'application pendant l'incident.

En pratique, le livre de procédure devrait promouvoir le manifeste de la version précédente vers le canal affecté, invalider le marqueur de mise en scène, et confirmer que les nouvelles vérifications se résolvent vers la version sûre. Si l'incident se produit dans le rendu code plutôt que dans la coquille native, un roulage ciblé de la couche web peut être plus rapide. Un tel plateforme comme Capgo rollouts de phase Peut être pertinent pour ce niveau de livraison séparé, mais ne doit pas cacher la frontière entre un rollback de binaires natifs et un rollback de web-bundle.

Traiter l'auto-mise à jour comme un contrôle de sécurité

Un mises à jour Electron télécharge l'exécutable code et peut l'installer avec peu d'interaction utilisateur. Cela rend le chemin de mise à jour automatique. frontière de sécurité, et non simplement un avantage de commodité. La documentation officielle d'Electron décrit des contraintes de plateforme telles que macOS ATS, et la couverture de sécurité a documenté un scénario de 2022 dans lequel les attaquants contrôlant l'infrastructure de mise à jour pouvaient servir des packages malveillants qui passaient encore les vérifications de signature code, comme discuté dans la documentation de sécurité d'auto-mise à jour d'Electron Builder.

La signature de Code reste fondamentale, mais ce n'est pas le modèle de confiance entier. Signez chaque version, vérifiez le certificat et l'identité pendant la CI, et maintenez une procédure de rotation de clés documentée. Sur macOS, combinez la signature avec la notarisation et le runtime durcisé approprié à votre application. Sur Windows, faites de la propriété de certificat, de la renouvellement et de l'accès à la construction auditable. Linux nécessite une stratégie spécifique à la distribution car Electron ne fournit pas un mises à jour universel intégré là-bas.

Protégez les métadonnées avec autant de soin que le binaire

Ainsi, même un fichier binaire signé peut être associé à la mauvaise version si le canal de métadonnées est compromis ou mal configuré. Considérez l'ajout d'une signature de manifeste vérifiée contre une clé publique intégrée à l'application, imposez une version minimale autorisée et rejetez les rétrogradations inattendues à moins qu'un chemin de récupération autorisé ne les autorise explicitement.

La mise en production de la feed mérite également des contrôles.

• Restreindre l'accès à la publication : Accordez à la CI uniquement les permissions requises pour publier les actifs de version.
• Protéger les secrets de signature : Conservez les certificats et les clés privées dans un stockage de secrets géré, pas dans les fichiers de dépôt.
• Fixer les dépendances : Verrouillez Electron, electron-builder et les dépendances transitives dans la CI.
• Examiner les artefacts : Analysez les packages générés et comparez-les avec le commit et la version intentionnels.
• Exiger un transport sécurisé : Suivez les exigences ATS et HTTPS strictes pour les demandes d'actualisation.
• Surveiller les échecs de vérification : Traitez les échecs répétés de signature ou de manifeste comme des événements de sécurité, et non comme un bruit de réseau ordinaire.

Le système d'outils maintenu par Electron continue d'ajouter une couverture de packaging et d'actualisation, mais la maintenance n'enlève pas la nécessité de modélisation de menaces. L'objectif pratique est de s'assurer que si un attaquant compromet un conteneur, une CDN ou une étape de construction, il ne peut toujours pas faire accepter au client une mise à jour non autorisée. La guidance de vérification de signature fournit un contexte utile pour concevoir cette couche de vérification supplémentaire.

Le Runbook et le Checklist de Production

Une mise à jour est prête uniquement lorsque l'un autre ingénieur peut l'exploiter sous pression. Gardez le checklist près de l'opération de déploiement et du canal d'incident.

Barrières de pré-version

• Identité de version : Confirmez la version du package, la balise de version, l'ID de commit et le changelog.
• Signature : Vérifiez que chaque artefact de plateforme est signé et que la notarisation ou une validation équivalente est terminée.
• Contrat de manifeste : Confirmer latest.yml, latest-mac.yml, les hachages, les chemins et les blockmaps correspondent aux artefacts téléchargés.
• Sécurité de la chaîne : Publiez sur le flux interne ou bêta avant de promouvoir la chaîne de version.
• Telemétrie : Vérifications de mise à jour confirmées, progression de téléchargement, complétion d'installation, santé de lancement et erreurs arrivent.

Canary et déploiement complet

• Contrôle de cohorte : Démarrer avec un petit public interne ou bêta délibérément.
• Budget de santé : Tenir la promotion si les échecs de lancement, les échecs de téléchargement de mise à jour, les exceptions du rendu ou les échecs d'authentification dépassent les limites approuvées de l'équipe.
• Approbation de la promotion : Exiger une décision explicite de poursuite ou d'arrêt avant de déplacer la version vers le flux stable.
• Impact sur le client : Préparez vos messages de support avant la large diffusion, pas après la première incident.

Réponse à l'incident

Si le nouveau binaire ne démarre pas, si la création de processus échoue ou si les téléchargements de mise à jour s'arrêtent, arrêtez immédiatement la promotion. Rétablissez le manifeste signé précédent, invalidez le marqueur de mise en scène, et vérifiez que les clients frais se résolvent vers la version précédente. Vérifiez ensuite à l'aide de la télémétrie que la flotte se rétablit avant de communiquer la fermeture.

Les commandes de reversion exactes dépendent de votre fournisseur, mais la séquence doit toujours être documentée : Fléchir le manifeste de canal vers la version précédente, invalidez le marqueur de mise en scène, poussez un marqueur de mise à jour forcée si la récupération le nécessite, et vérifiez le chemin de reversion avec la télémétrie en direct.Une reversion non testée n'est qu'une espérance.

Capgo propose un mise à jour pour Electron pour livrer des changements de couche web signés, des canaux ciblés, des contrôles de lancement et l'observabilité des mises à jour sans recompiler la coquille native pour chaque changement de rendu. Si vous souhaitez séparer les sorties de binaires natifs des livraisons de JavaScript et de CSS contrôlées, visitez Capgo et l'évaluez-l’en parallèl’avec votre pipeline de mise à jour Electron existant.