Kapitel 13: Electron-Anwendungen paketieren

In diesem Kapitel lernen Sie, wie Sie Ihre Electron-Anwendung für die Verteilung paketieren.

13.1 Paketierungswerkzeuge wählen

electron-builder (empfohlen für Einsteiger)

Der am häufigsten verwendete Paketierer für Electron.

Installation

npm install electron-builder --save-dev

Grundlegende Konfiguration in package.json

{
  "name": "meine-app",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "pack": "electron-builder --dir",
    "dist": "electron-builder"
  },
  "build": {
    "appId": "com.beispiel.meineapp",
    "productName": "Meine App",
    "directories": {
      "output": "dist"
    },
    "files": [
      "**/*",
      "!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}",
      "!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}",
      "!**/node_modules/*.d.ts"
    ],
    "win": {
      "target": "nsis",
      "icon": "assets/icon.ico"
    },
    "mac": {
      "target": "dmg",
      "icon": "assets/icon.icns"
    },
    "linux": {
      "target": "AppImage",
      "icon": "assets/icon.png"
    }
  }
}

electron-packager (einfach zu verwenden)

Ein einfaches Werkzeug für schnelles Paketieren.

Installation

npm install electron-packager --save-dev

package.json Konfiguration

{
  "scripts": {
    "package:win": "electron-packager . MeineApp --platform=win32 --arch=x64 --out=dist/ --overwrite",
    "package:mac": "electron-packager . MeineApp --platform=darwin --arch=x64 --out=dist/ --overwrite",
    "package:linux": "electron-packager . MeineApp --platform=linux --arch=x64 --out=dist/ --overwrite"
  }
}

Vergleich der Paketierungswerkzeuge

Werkzeug	Vorteile	Nachteile	Empfohlen für
electron-builder	Funktionen, Auto-Update, Installer	Komplexere Konfiguration	Produktions-Apps
electron-packager	Einfach, schnell	Keine Installer, keine Auto-Updates	Schnelle Tests

13.2 Paketierungskonfiguration

package.json Konfiguration (Icons, Paket-Format, Ausgabepfad)

App-Informationen

{
  "build": {
    "appId": "com.beispiel.meineapp",  // Eindeutige App-ID
    "productName": "Meine App",           // Anzeigename
    "copyright": "Copyright © 2024",    // Copyright-Text
    "directories": {
      "output": "dist"                   // Ausgabeverzeichnis
    }
  }
}

Icons konfigurieren

assets/
├── icon.ico     # Windows (256x256 px, am besten mehrere Größen)
├── icon.icns    # macOS (512x512 px)
└── icon.png     # Linux (512x512 px, transparent)

{
  "build": {
    "icon": "assets/icon"  // Ohne Erweiterung (automatisch .ico/.icns/.png)
  }
}

Pakettypen festlegen

{
  "build": {
    "win": {
      "target": [
        "nsis",        // Windows Installer (.exe)
        "portable"     // Portable Version (.exe)
      ]
    },
    "mac": {
      "target": [
        "dmg",         // macOS Disk Image (.dmg)
        "zip"          // macOS ZIP-Archiv (.zip)
      ]
    },
    "linux": {
      "target": [
        "AppImage",    // Linux AppImage (.AppImage)
        "deb",         // Debian-Paket (.deb)
        "rpm",         // RPM-Paket (.rpm)
        "snap"         // Snap-Paket (.snap)
      ]
    }
  }
}

Erweiterte Konfiguration (electron-builder)

NSIS-Konfiguration (Windows)

{
  "build": {
    "nsis": {
      "oneClick": false,              // Nicht Ein-Klick-Installation
      "allowElevation": true,        // Rechteerhöhung erlauben
      "allowToChangeInstallationDirectory": true,  // Installationsverzeichnis ändern
      "createDesktopShortcut": true,  // Desktop-Verknüpfung
      "createStartMenuShortcut": true, // Startmenü-Verknüpfung
      "shortcutName": "Meine App",  // Verknüpfungsname
      "installerIcon": "assets/installer-icon.ico",
      "uninstallerIcon": "assets/uninstaller-icon.ico",
      "installerHeader": "assets/installer-header.bmp"
    }
  }
}

DMG-Konfiguration (macOS)

{
  "build": {
    "dmg": {
      "title": "Meine App ${version}",
      "icon": "assets/icon.icns",
      "iconSize": 80,
      "background": "assets/dmg-background.png",  // Hintergrundbild (540x380 px)
      "window": {
        "width": 540,
        "height": 380
      },
      "contents": [
        { "x": 410, "y": 170, "type": "link", "path": "/Applications" },
        { "x": 130, "y": 170, "type": "file" }
      ]
    }
  }
}

13.3 Multi-Plattform-Paketierung

Windows: exe-Installer

# Nur Windows-Build auf Windows
npm run dist -- --win

# Windows-Build auf macOS/Linux (erfordert Wine)
npm run dist -- --win --x64

Windows-Build-Konfiguration

{
  "build": {
    "win": {
      "target": "nsis",
      "icon": "assets/icon.ico",
      "publisherName": "Mein Unternehmen",
      "requestedExecutionLevel": "asInvoker"  // 'asInvoker', 'highestAvailable', 'requireAdministrator'
    }
  }
}

macOS: dmg

# macOS-Build (nur auf macOS möglich ohne Cloud-Dienst)
npm run dist -- --mac

macOS-Build-Konfiguration

{
  "build": {
    "mac": {
      "category": "public.app-category.productivity",  // App-Kategorie
      "icon": "assets/icon.icns",
      "hardenedRuntime": true,       // Hardened Runtime (für Notarisierung)
      "gatekeeperAssess": false,     // Gatekeeper-Bewertung
      "entitlements": "build/entitlements.mac.plist",
      "entitlementsInherit": "build/entitlements.mac.plist"
    }
  }
}

Linux: deb/rpm

# Linux-Build
npm run dist -- --linux

# Spezifische Pakettypen
npm run dist -- --linux AppImage  # AppImage
npm run dist -- --linux deb       # Debian
npm run dist -- --linux rpm       # RPM
npm run dist -- --linux snap      # Snap

Linux-Build-Konfiguration

{
  "build": {
    "linux": {
      "target": "AppImage",
      "icon": "assets/icon.png",
      "category": "Utility",
      "maintainer": "Kontakt <kontakt@example.com>",
      "description": "Meine Electron-App",
      "desktop": {
        "Name": "Meine App",
        "Comment": "Eine tolle Electron-App",
        "Categories": "Utility;"
      }
    }
  }
}

Plattformübergreifende Paketierung

CI/CD für Multi-Plattform-Builds

# .github/workflows/build.yml
name: Build

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
    runs-on: ${{ matrix.os }}
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Node.js einrichten
        uses: actions/setup-node@v3
        with:
          node-version: 20
      
      - name: Abhängigkeiten installieren
        run: npm install
      
      - name: Paketieren
        run: npm run dist
      
      - name: Artefakte hochladen
        uses: actions/upload-artifact@v3
        with:
          name: ${{ matrix.os }}-build
          path: dist/

13.4 Häufige Paketierungsprobleme beheben

Problem 1: Paketierung schlägt fehl

Symptom

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

Lösung

# Heap-Größe erhöhen
export NODE_OPTIONS="--max-old-space-size=4096"  # Linux/macOS
set NODE_OPTIONS=--max-old-space-size=4096        # Windows

# Dann erneut paketieren
npm run dist

Problem 2: Icon wird nicht angezeigt

Überprüfung

1. Sicherstellen, dass Icon-Dateien existieren:
   - Windows: icon.ico (mindestens 256x256 px)
   - macOS: icon.icns (512x512 px)
   - Linux: icon.png (512x512 px, transparent)

2. Pfad in package.json prüfen:
   "icon": "assets/icon"  (ohne Erweiterung)

3. ICO-Datei mehrere Größen enthalten:
   - 16x16, 32x32, 48x48, 64x64, 128x128, 256x256

Problem 3: Anwendung lässt sich nach Paketierung nicht ausführen

Ursachen und Lösungen

Problem	Ursache	Lösung
Pfadfehler	Falsche Pfade in main.js	app.getAppPath() verwenden
Abhängigkeiten fehlen	In devDependencies statt dependencies	In dependencies verschieben
native Module	Nicht für Zielplattform kompiliert	npm rebuild ausführen

Richtige Pfadverwendung

// FALSCH (funktioniert nur in Entwicklung)
const data = fs.readFileSync('./data.json');

// RICHTIG (funktioniert auch nach Paketierung)
const { app } = require('electron');
const path = require('path');

const dataPath = app.isPackaged 
  ? path.join(process.resourcesPath, 'app.asar', 'data.json')
  : path.join(__dirname, 'data.json');

const data = fs.readFileSync(dataPath);

Problem 4: Anwendung lässt sich nach Paketierung nicht ausführen

Diagnose

# Windows: Event-Log prüfen
# macOS: Konsole.app öffnen
# Linux: Terminal-Ausgabe prüfen

# Mit Debug-Informationen paketieren
DEBUG=electron-builder npx electron-builder --win

13.5 Anwendungssignierung (optional, Sicherheitshinweis-Problem lösen)

Windows: Codesignierung

Voraussetzungen

1. Codesignierungs-Zertifikat erwerben (z.B. von DigiCert, Sectigo)
2. Zertifikat in Windows-Zertifikatspeicher importieren

Konfiguration

{
  "build": {
    "win": {
      "sign": true,
      "publisherName": "Mein Unternehmen GmbH"
    }
  }
}

Signierungsbefehl (manuell)

signtool sign /fd sha256 /a /f "mein-zertifikat.pfx" /p "zertifikats-passwort" "dist/MeineApp Setup.exe"

macOS: Codesignierung und Notarisierung

Voraussetzungen

1. Apple Developer ID Zertifikat
2. Xcode installiert
3. codesign-Werkzeug verfügbar

Signieren

# App signieren
codesign --deep --force --verify --verbose --sign "Developer ID Application: Mein Name (TEAMID)" "dist/mac/Meine App.app"

# Überprüfen
codesign --verify --deep --strict --verbose=2 "dist/mac/Meine App.app"

Notarisierung (erforderlich für Distribution außerhalb des Mac App Store)

{
  "build": {
    "mac": {
      "hardenedRuntime": true,
      "gatekeeperAssess": false,
      "notarize": true
    }
  }
}

# Umgebungsvariablen für Notarisierung
export APPLE_ID="meine-email@example.com"
export APPLE_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"  # App-spezifisches Passwort
export APPLE_TEAM_ID="TEAMID"

Zusammenfassung

In diesem Kapitel haben Sie gelernt:

• Paketierungswerkzeuge (electron-builder, electron-packager) auszuwählen
• Paketierungskonfiguration in package.json vorzunehmen
• Multi-Plattform-Paketierung durchzuführen
• Häufige Paketierungsprobleme zu beheben
• Anwendungen zu signieren (Windows/macOS)

Im nächsten Kapitel werden wir häufige Fehler und Fallstricke behandeln.