Zum Hauptinhalt springen

Fehlerbehebungs-Checkliste

Von der Grenze nach innen debuggen

Prüfe zuerst, ob Stream Deck das Plugin sieht, dann das Manifest, dann den Prozess, dann die Action-Events.

1. Plugin erscheint nicht​

Prüfe:

  • Die Stream Deck App läuft.
  • Das Plugin-Verzeichnis endet auf .sdPlugin.
  • Das Plugin ist gelinkt oder installiert.
  • manifest.json ist gültiges JSON.
  • Die Plugin-UUID ist gültiges Reverse-DNS in Kleinschreibung.
  • Software.MinimumVersion ist nicht höher als die installierte Stream Deck App.
  • OS unterstützt die aktuelle Plattform.
  • Die Stream Deck App wurde nach der Installation neu gestartet.

Elgato weist darauf hin, dass Stream Deck nach einer Neuinstallation oder einem App-Update mit erhöhten Rechten laufen kann und ein Neustart Probleme mit nicht angezeigten Plugins beheben kann.

2. Watch-Modus lädt nicht neu​

Prüfe:

  • npm run watch läuft noch.
  • Das generierte Watch-Skript enthält streamdeck restart <plugin_uuid>.
  • Die UUID im Watch-Befehl passt zur Manifest-UUID.
  • Rollup baut erfolgreich neu.
  • Stream Deck wird nicht durch OS-Berechtigungen blockiert.
  • Die geänderte Datei liegt unter src/ oder dem beobachteten Manifest-/Plugin-Pfad.

Manueller Ausweichweg:

npm run build
streamdeck restart com.example.plugin

3. Action erscheint, tut aber nichts​

Prüfe:

  • Die Action-UUID in @action({ UUID: '...' }) passt zur Action-UUID im Manifest.
  • Die Action-Klasse wird vom Plugin-Einstiegspunkt importiert.
  • Der Name der Event-Methode passt zum erwarteten Controller.
  • Du testest auf einem unterstützten Controller: Taste vs. Dial.
  • Fehler werden in die Plugin-Logs geschrieben.
  • Async-Aufrufe werden awaited und abgefangen.

Zur schnellen Isolierung ersetze externe API-Arbeit durch:

await ev.action.setTitle('OK');

Wenn das funktioniert, liegt das Problem in deiner Integrationslogik, nicht in der Event-Zustellung von Stream Deck.

4. Property Inspector öffnet nicht​

Prüfe:

  • PropertyInspectorPath zeigt auf eine existierende HTML-Datei.
  • Der Pfad ist relativ zum *.sdPlugin-Verzeichnis.
  • Das HTML hängt nicht von entfernten Assets ab, die offline fehlschlagen.
  • Browser-Konsolenfehler blockieren nicht die Initialisierung.
  • Die Einstellungsnamen im Inspector passen zu den Namen der Action-Einstellungen.

Bevorzuge lokales sdpi-components.js für eine zuverlässige Property-Inspector-UI.

5. Einstellungen fehlen​

Prüfe:

  • Die Action behandelt Standardwerte.
  • Der Property Inspector schreibt die erwarteten Keys.
  • Du hast keinen Einstellungs-Key ohne Kompatibilitäts-Fallback umbenannt.
  • Mehrere Actions teilen nicht versehentlich inkompatible Einstellungsformen.

Nutze tolerante Lesevorgänge:

const mode = ev.payload.settings.mode ?? 'default';

6. Bilder werden nicht angezeigt​

Prüfe:

  • Die Bildpfade im Manifest sind korrekt.
  • Die Dateien existieren in *.sdPlugin/imgs/.
  • Die Dateinamen stimmen exakt in der Groß-/Kleinschreibung überein.
  • Die Bilder sind gepackt, nicht durch .sdignore ignoriert.
  • Die Runtime-Bilderzeugung schreibt außerhalb unveränderlicher gepackter Dateien.

Wenn du Bilder aus dem Code setzt, stelle sicher, dass Bildformat und Data-URL von der aufgerufenen SDK-Methode akzeptiert werden.

7. Debugger kann sich nicht verbinden​

Prüfe:

  • Nodejs.Debug ist im Manifest aktiviert.
  • Stream Deck wurde nach Manifest-Änderungen neu gestartet.
  • Du verbindest dich mit dem korrekten Node-Prozess.
  • Ein fester Debug-Port ist nicht bereits belegt.

Temporärer fester Port:

{
  "Nodejs": {
    "Version": "24",
    "Debug": "--inspect=127.0.0.1:12345"
  }
}

8. Python kann das Gerät nicht öffnen​

Prüfe:

  • Die Stream Deck Desktop-App nutzt nicht dasselbe Gerät.
  • Die Linux-HID-Berechtigungen erlauben dem aktuellen Nutzer den Zugriff auf das Deck.
  • Das Gerät ist physisch verbunden und über USB sichtbar.
  • Du schließt das Deck nach Abstürzen oder Neustarts.
  • Das Ziel-Hardwaremodell wird von der Version der Python-Bibliothek unterstützt.

Direkte HID-Steuerung und offizielle Stream Deck App-Plugins sind unterschiedliche Betriebsmodi. Vermeide es, beide gleichzeitig auf derselben Hardware zu nutzen.

9. Pack schlägt fehl​

Prüfe:

  • Zuerst die Ausgabe von streamdeck validate.
  • Die erforderlichen Dateien existieren in *.sdPlugin.
  • manifest.json referenziert echte Dateien.
  • .sdignore schließt keine erforderlichen Assets aus.
  • Die Felder für Version und UUID sind gültig.
  • Das Plugin wurde vor dem Packen gebaut.

10. Checkliste für Release-Regressionen​

Vor der Veröffentlichung:

  • Die Neuinstallation funktioniert.
  • Der Neustart von Stream Deck funktioniert.
  • Alle Actions lassen sich zu einem sauberen Profil hinzufügen.
  • Property Inspectors öffnen und speichern Einstellungen.
  • Alte Einstellungen werden weiterhin korrekt gelesen.
  • Der Offline-Modus bricht die lokale UI nicht.
  • Logs sind nützlich, aber nicht zu geschwätzig.
  • Keine privaten Pfade, Geheimnisse oder Debug-Dateien werden gepackt.