Fehlerbehebung bei fehlgeschlagenen Builds

When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit…

Wenn ein Orbit Build fehlschlägt, zeigt die Seite mit den Bereitstellungsdetails das vollständige Protokoll sowie eine kategorisierte Fehlerzusammenfassung und einen vorgeschlagenen Fix. Diese Anleitung führt Sie durch das Lesen dieser Seite, die Fehler, die Orbit namentlich erkennt, die Fehler, die es nicht erkennt, und was Sie tun sollten, wenn ein Build erfolgreich ist, aber die Website immer noch falsch angezeigt wird.

Fehler lesen

Öffnen Sie Ihr Projekt in Orbit.
Öffnen Sie die Registerkarte Deployments.
Klicken Sie auf die Bereitstellung mit dem Status Failed.
Lesen Sie zunächst die Fehlerzusammenfassung über dem Protokoll und dann das Protokoll selbst.

Fehlgeschlagene Bereitstellung mit kategorisierter Fehlerzusammenfassung

Orbit weist jedem Fehler eine Kategorie zu: Out of memory, Compile error, Test failure, Lint error, Install error, Network error, Timeout oder Unknown error. Die Kategorie zeigt Ihnen, welcher Teil der Pipeline zu betrachten ist, bevor Sie eine einzige Protokollzeile lesen.

Es gibt auch einen Button Get AI diagnosis. Dieser liest die letzten 120 Zeilen des Protokolls zusammen mit dem erkannten Framework und der Fehlerkategorie und gibt eine Erklärung in natürlicher Sprache zurück.

Die Diagnose ist als AI-generated, verify before acting gekennzeichnet. Behandeln Sie sie als einen sehr guten Hinweis auf die richtige Protokollzeile, nicht als Autorität für Ihre Codebasis. Lesen Sie die Zeile, auf die sie verweist, bevor Sie etwas ändern.

Wenn der Build nie gestartet wurde und bei Queued hängenbleibt, fahren Sie unten mit dem Abschnitt zu warteschlangen Build fortfahren.

Fehler, die Orbit namentlich erkennt

Diese werden mit einem spezifischen vorgeschlagenen Fix auf der Bereitstellungsseite angezeigt.

Was Orbit erkennt	Was es bedeutet	Fix
Missing module	Ein Import verweist auf ein Paket, das nicht installiert ist	Fügen Sie das Paket zu `package.json` hinzu und committen Sie es, oder beheben Sie den Tippfehler im Importpfad
`ERESOLVE` conflict	npm kann eine Peer Dependency nicht erfüllen	Beheben Sie den Konflikt in `package.json`, oder fügen Sie `--legacy-peer-deps` zu Ihrem Installationsbefehl in den Einstellungen hinzu
TypeScript error	Typprüfung ist während des Builds fehlgeschlagen	Beheben Sie die aufgelisteten Fehler. Bei Typenproblemen von Drittanbietern: `skipLibCheck: true` in `tsconfig.json`
Out of memory	Der Build hat den RAM des Build-Computers überschritten	Fügen Sie `NODE_OPTIONS=--max-old-space-size=2048` als Umgebungsvariable hinzu, oder wechseln Sie zu einem Plan mit einem größeren Build-Computer
Build disk full	Der Build hat seine Festplatte gefüllt	Suchen Sie nach einem unerwartet großen `node_modules` oder Artefakt, oder wechseln Sie zu einem Plan mit einer größeren Build-Festplatte
Build timed out	Der Build hat die 30-Minuten-Abbruchgrenze erreicht	Aktivieren Sie Build-Cache, reduzieren Sie die Bundle-Größe, oder finden Sie heraus, was hängenbleibt
Package not found (404)	Eine Abhängigkeit existiert nicht unter diesem Namen oder dieser Version	Überprüfen Sie `package.json` auf Tippfehler, oder bestätigen Sie, dass das Paket veröffentlicht ist
ESLint errors	Lint-Fehler haben den Build blockiert	Beheben Sie sie, oder stoppen Sie, dass Lint den Build in Ihrer Framework-Konfiguration fehlschlagen lässt
Syntax error	Quelle kann nicht analysiert werden	Fehlende Klammer, nicht geschlossene Zeichenkette oder Syntax, die Ihre Node-Version nicht unterstützt
File not found	Eine referenzierte Datei ist nicht im Repository	Bestätigen Sie, dass sie committet ist, und überprüfen Sie die Groß-/Kleinschreibung des Pfads
Lockfile out of date	Die Lockdatei stimmt nicht mit `package.json` überein	Führen Sie lokal die Installation des Paketmanagers durch und committen Sie die aktualisierte Lockdatei

Die Lockdatei-Nichtübereinstimmung ist der häufigste Fehler beim ersten Deployment und der verwirrlichste, weil er lokal nie auftritt. npm ci, yarn install --frozen-lockfile und pnpm install --frozen-lockfile weigern sich alle, fortzufahren, wenn die Lockdatei nicht mit package.json übereinstimmt. Generieren Sie die Lockdatei lokal neu und committen Sie sie.

Häufige Fehler nach Phase

Dependency Install schlägt fehl

Die Phase Install ist fehlgeschlagen.

Falscher Paketmanager. Orbit wählt npm, yarn oder pnpm aus Ihrer Lockdatei. Wenn mehr als eine Lockdatei committet ist, entspricht die Auswahl möglicherweise nicht der, die Sie erwarten. Löschen Sie die, die Sie nicht verwenden, oder setzen Sie Install command explizit in Settings.
Private Registry. Wenn eine Abhängigkeit aus einer privaten Registry kommt, muss das Auth-Token zur Build-Zeit als Umgebungsvariable verfügbar sein, und Ihre .npmrc muss es referenzieren.
Node.js-Versionskonflikt. Einige Pakete erfordern eine Mindest-Node-Version. Setzen Sie Node.js version in Settings auf die Hauptversionsnummer: 18, 20 oder 22.
Speicherplatz bei einem großen Monorepo. Verwenden Sie npm ci statt npm install, und erwägen Sie einen Plan mit einem größeren Build-Computer.

Build-Befehl schlägt fehl

Die Phase Build ist fehlgeschlagen.

TypeScript oder Lint-Fehler. Orbit führt Ihren Build-Befehl genau wie geschrieben aus. Wenn Ihr Build lokal fehlschlägt, schlägt er auch hier fehl.
Fehlende Build-Zeit-Umgebungsvariable. Eine Variable, die während des Builds gelesen wird, muss vor dem Build existieren, nicht nur zur Laufzeit. Fügen Sie sie auf der Registerkarte Env vars hinzu und stellen Sie erneut bereit. Eine Build-Zeit-Variable, die nach einer Bereitstellung hinzugefügt wird, gilt nicht rückwirkend für sie.
Falsches Root-Verzeichnis in einem Monorepo. Setzen Sie Root directory in Settings auf den Pfad der App, zum Beispiel apps/web.

Builds laufen ab

Builds werden nach 30 Minuten Wanduhrzeit in jedem Plan abgebrochen. Wenn Ihr Build konsistent dieser Zeit nahekommt:

Überprüfen Sie das Protokoll auf einen Prozess, der auf eine Eingabe wartet. Ein Build, der eine Eingabeaufforderung anzeigt, ist ein Build, der hängen bleibt.
Vermeiden Sie --legacy-peer-deps bei einem großen Abhängigkeitsbaum, es sei denn, Sie benötigen es.
Stellen Sie sicher, dass der Build-Cache verwendet wird. Die Pläne Liftoff und Apex enthalten ihn; die Bereitstellungsseite zeigt Cache hit oder Cold build.
Wechseln Sie zu einem Plan mit mehr Build-vCPU. Siehe Kapsule Orbit Plan-Limits.

Der Build startet nie

Eine Bereitstellung, die bei Queued steckenbleibt, wartet auf einen Build-Slot. Die Detailseite zeigt Ihre Position in der Warteschlange und wie viele Ihrer gleichzeitigen Build-Slots verwendet werden, und startet den Build automatisch, wenn einer freiwird. Launch und Liftoff ermöglichen einen gleichzeitigen Build; Apex ermöglicht drei.

Sie können alles, das über Ihr Konto läuft, in Kapsule Orbit und dann Queue sehen.

Wenn eine Bereitstellung in der Warteschlange sitzt und nichts anderes ausgeführt wird, wird sie wahrscheinlicher blockiert als in der Warteschlange. Überprüfen Sie folgende Punkte:

Awaiting approval, wenn Require approval for production aktiviert ist
Ein deploy lock für das Projekt
Ein deploy freeze schedule, das die aktuelle Zeit oder den aktuellen Tag blockiert
CI required checks, die auf Ihre Pipeline warten
Require staging success before production, das auf eine Staging-Bereitstellung desselben Commits wartet

Der Build wurde vollständig übersprungen

Wenn ein Push keine Bereitstellung erzeugt hat, wurde er wahrscheinlich absichtlich gefiltert:

Ignored paths: Jede Datei in dem Push stimmte mit einem Muster wie *.md oder docs/** überein
Branch ignore patterns: Der Branch stimmte mit etwas wie dependabot/* überein
Root directory: Nichts im Push berührte das Monorepo-Unterverzeichnis für dieses Projekt
Branch previews aus, und der Push war nicht für Production oder Staging

Build erfolgreich, aber die Website ist falsch

Ein grüner Build und eine defekte Website ist fast immer ein Konfigurationsproblem und kein Codeproblem.

404 auf jeder Seite. Das Output directory ist falsch: Kapsule Orbit veröffentlichte einen Ordner, der nicht Ihre Build-Ausgabe ist. Überprüfen Sie, was Ihr Build tatsächlich schreibt. Häufige Werte sind dist, .next, out, build und .output.

404 nur bei dynamischen Routen. Die App benötigt einen laufenden Server und wird als statische Dateien bereitgestellt. Aktivieren Sie Server mode in Settings unter Runtime. Dies ist erforderlich für Next.js mit SSR, Remix, Nuxt und alles andere, das keine statische Exportierung ist.

Assets 404 nach einer Bereitstellung, für Benutzer, die bereits auf der Website waren. Sie haben die alte Seite geladen und fordern alte Bundle-URLs an, die nicht mehr vorhanden sind. Aktivieren Sie Skew protection in Settings, das die Artefakte des vorherigen Builds für ein Aufbewahrungsfenster nach der Live-Bereitstellung einer neuen Bereitstellung verfügbar hält.

Umgebungsvariable ist zur Laufzeit undefined. Bestätigen Sie, dass der Bereich der Variable tatsächlich diese Umgebung abdeckt, und dass die Bereitstellung nach der Änderung stattgefunden hat. Die Bereitstellungsdetailseite listet genau auf, welche Schlüssel zur Build-Zeit eingespritzt wurden, und vergleicht sie mit Ihrer aktuellen Konfiguration.

Framework-spezifische Build-Einstellungen finden Sie unter Konfigurieren Ihres Build-Befehls und Ausgabeverzeichnisses.

Erneut versuchen

Auf der Seite mit der fehlgeschlagenen Bereitstellung:

Retry build führt denselben Commit erneut aus.
More retry options und dann Retry with cleared cache löschen zunächst den Build-Cache.

Sie können auch Kapsule Orbit für Sie erneut versuchen lassen. Build auto-retry in Settings ordnet fehlgeschlagene Builds erneut in die Warteschlange ein, die durch Infrastrukturfehler wie Netzwerkfehler oder Timeouts verursacht wurden, bis zu drei Mal. Es versucht absichtlich nicht, Codefehler erneut zu versuchen, daher führt ein Kompilierungs-, Lint- oder Testfehler niemals zu einer Schleife.

Das erneute Versuchen mit gelöschtem Cache löscht den zwischengespeicherten node_modules für die Umgebung und kann nicht rückgängig gemacht werden. Der nächste Build danach wird langsam sein. Das ist der Sinn, aber tun Sie es nicht reflexartig bei einem großen Monorepo.

Verhindern, dass ein fehlerhafter Build Benutzer erreicht

Wenn eine Bereitstellung bereits live ist und etwas gebrochen hat, führen Sie einen Rollback durch, anstatt zu versuchen, unter Druck voranzukommen. Rollback fördert ein bereits erstelltes Artefakt und dauert Sekunden. Siehe Rolling Back a Deployment.

Um weitere Bereitstellungen während der Untersuchung zu stoppen, klicken Sie auf Lock deploys für das Projekt. Push-basierte Bereitstellungen werden dann übersprungen, bis Sie entsperren, während manuelle Bereitstellungen weiterhin funktionieren, damit Sie den Fix ausliefern können.

Sie können auch Kapsule Orbit dies automatisch tun lassen: Auto-rollback on failure stellt die letzte fehlerfreie Bereitstellung wieder her, wenn eine Production-Bereitstellung fehlschlägt, und ein Health check-Pfad stellt sie wieder her, wenn die neue Bereitstellung nicht innerhalb von 15 Sekunden mit einem 2xx antwortet.

Noch immer festgefahren

Wenn das Protokoll einfach mit keiner Fehlermeldung endet, wurde der Build-Prozess höchstwahrscheinlich beendet: Speichererschöpfung oder die Build-Maschine wurde zurückgefordert. Versuchen Sie es einmal erneut. Wenn es auf die gleiche Weise zweimal fehlschlägt, öffnen Sie ein Ticket von KPanel oder senden Sie eine E-Mail an support@kapsulehost.com und fügen Sie die auf der Detailseite angezeigte Bereitstellungs-ID ein.