Konfigurieren Sie Ihren Build-Befehl und Ausgabeverzeichnis

Getting Orbit to build your project correctly comes down to a handful of fields in Settings: install command, build command, output directory, root directory and Node.js version. Left blank they are…

Erste Schritte mit Ihrem Build-Befehl und Ausgabeverzeichnis

Das Konfigurieren von Orbit zum korrekten Erstellen Ihres Projekts hängt von einer Handvoll Feldern in Einstellungen ab: Installationsbefehl, Build-Befehl, Ausgabeverzeichnis, Stammverzeichnis und Node.js-Version. Wenn sie leer gelassen werden, werden sie automatisch erkannt, und die meisten Probleme bei der ersten Bereitstellung entstehen durch einen automatisch erkannten Wert, der nicht dem entspricht, was Ihr Framework tatsächlich schreibt.

Wo Sie die Einstellungen finden

Öffnen Sie Ihr Projekt in Orbit, gehen Sie zur Registerkarte Einstellungen und finden Sie die Karte Build-Einstellungen.

Feld	Funktion	Platzhalter wenn leer
Installationsbefehl	Wie Abhängigkeiten vor dem Build installiert werden	`npm ci (auto-detected)`
Build-Befehl	Der Befehl, der Ihre Ausgabe erzeugt	`npm run build (auto-detected)`
Ausgabeverzeichnis	Der Ordner, den Orbit nach dem Build veröffentlicht	`dist (auto-detected)`
Stammverzeichnis	Für Monorepos das Unterverzeichnis mit Ihrer App	`/ (monorepo subdirectory)`
Node.js-Version	Die Hauptversion von Node für Build und Ausführung	Plattformstandard

Lassen Sie jedes Feld leer, um Orbit automatisch zu erkennen. Klicken Sie auf Speichern in der Karte Build-Einstellungen, um die Änderungen anzuwenden.

Build-Einstellungen-Karte in den Orbit-Projekteinstellungen

Das Ändern einer Build-Einstellung ändert nicht die Bereitstellung, die derzeit aktiv ist. Die neue Einstellung gilt ab der nächsten Bereitstellung. Stellen Sie nach dem Speichern erneut bereit, oder es wird keine Änderung zu sehen sein.

Framework-Standards

Next.js

Next.js hat zwei Modi in Orbit, und die Auswahl des falschen ist der häufigste Fehler bei der ersten Bereitstellung.

Statischer Export (output: 'export' in next.config.js):

Build-Befehl: npm run build
Ausgabeverzeichnis: out
Servermodus: aus

Servermodus (SSR oder ISR), was für die meisten Next.js-Apps gilt:

Aktivieren Sie Servermodus in Einstellungen unter Laufzeit
Build-Befehl: npm run build
Ausgabeverzeichnis: .next

Ohne aktivierten Servermodus wird eine serverseitig gerenderte Next.js-App als statische Dateien veröffentlicht. Die Startseite wird normalerweise geladen und jede dynamische Route zeigt einen 404-Fehler. Wenn das Ihr Problem ist, ist das die Ursache: Aktivieren Sie den Servermodus und stellen Sie erneut bereit, bevor Sie etwas anderes ändern.

Astro

Der Ausgabeordner von Astro ist dist in jedem Modus. Was sich ändert, ist, ob Sie den Servermodus benötigen.

output: 'static', der Standard: Ausgabeverzeichnis dist, Servermodus aus
output: 'server' oder output: 'hybrid': Ausgabeverzeichnis dist, Servermodus an
Build-Befehl: npm run build, oder astro build

Vite (React, Vue, Svelte)

Build-Befehl: npm run build, oder vite build
Ausgabeverzeichnis: dist

Vite schreibt immer zu dist, sofern Sie build.outDir in vite.config.ts nicht überschrieben haben. Falls Sie dies getan haben, setzen Sie das Ausgabeverzeichnis entsprechend.

SvelteKit

Build-Befehl: npm run build
Ausgabeverzeichnis: build

Ob Sie den Servermodus benötigen, hängt von Ihrem Adapter ab: Ein statischer Adapter benötigt ihn nicht, ein Node-Adapter benötigt ihn.

Nuxt 3

Build-Befehl: npm run build
Ausgabeverzeichnis: .output
Servermodus: an

Remix

Build-Befehl: npm run build
Ausgabeverzeichnis: build
Servermodus: an

Express oder eine einfache Node-API

Build-Befehl: npm run build
Ausgabeverzeichnis: dist
Servermodus: an

Der Servermodus führt npm start nach dem Build aus, daher stellen Sie sicher, dass Ihr start Skript vorhanden ist und den Server startet.

Create React App

Create React App ist in der ursprünglichen Version veraltet und ist keine gute Wahl für ein neues Projekt, aber vorhandene funktionieren einwandfrei.

Build-Befehl: npm run build
Ausgabeverzeichnis: build

Einfaches HTML oder ein statischer Site-Generator

Lassen Sie den Installationsbefehl leer, wenn kein package.json vorhanden ist
Lassen Sie den Build-Befehl leer, um das Repository unverändert zu veröffentlichen, oder setzen Sie den Befehl Ihres Generators
Ausgabeverzeichnis: . für das Repository-Root oder den Ordner, in den der Generator schreibt

Node.js-Version

Geben Sie nur die Hauptversionsnummer ein: 18, 20 oder 22. Der Feld-Hinweis sagt dies ausdrücklich. Alles andere, wie 20.11.0 oder v20, ist nicht das, was dieses Feld erwartet.

Die Version gilt für den Build und, wenn der Servermodus aktiviert ist, auch für die Laufzeit.

Legen Sie die Version fest, anstatt sich auf den Standard zu verlassen. Eine Abhängigkeit, die eine neuere Node-Version benötigt, schlägt während der Installation fehl. Das Festlegen der Version beseitigt diese Fehlerklasse vollständig.

Monorepos

Setzen Sie Stammverzeichnis auf den Pfad Ihrer App, zum Beispiel apps/web. Orbit wechselt in dieses Verzeichnis, bevor es Ihre Installationsund Build-Befehle ausführt, und das Ausgabeverzeichnis ist dann relativ dazu.

Der Feld-Hinweis beschreibt das zweite, nützlichere Verhalten: Commits, die nur Dateien außerhalb dieses Pfads ändern, werden automatisch übersprungen. Ein Monorepo mit vier Orbit-Projekten erstellt nur die Apps neu, die ein Commit tatsächlich betroffen hat, was Zeit und Build-Minuten spart.

Jede Umgebung kann das Stammverzeichnis unabhängig überschreiben, unter Staging: Build-Überschreibungen in Einstellungen, was nützlich ist, wenn Staging einen anderen Workspace erstellt.

Staging-Überschreibungen

Wenn Ihr Projekt eine Staging-Umgebung hat, zeigen die Einstellungen einen Abschnitt Staging: Build-Überschreibungen mit denselben Feldern. Jedes Feld, das dort leer gelassen wird, erbt den Projektwert, daher können Sie beispielsweise nur den Build-Befehl für Staging zu npm run build:staging ändern und alles andere unverändert lassen.

Staging hat eigene verwandte Einstellungen in der Nähe: einen Branch, ein Zugangspasswort, eine IP-Zulassungsliste, automatisches Rollback bei Fehler und einen Schalter Produktionsumgebungsvariablen erben.

Build-Cache

Orbit speichert node_modules zwischen Builds auf den Plänen Liftoff und Apex. Die Seite mit den Bereitstellungsdetails zeigt Cache-Treffer oder Kalter Build zusammen mit der Dauer der Installationsphase, damit Sie sehen können, welchen Wert der Cache für Ihr Projekt hat.

Um eine vollständige Neuinstallation zu erzwingen, öffnen Sie Einstellungen, klicken Sie auf Build-Cache löschen und bestätigen Sie.

Das Löschen des Build-Cache kann nicht rückgängig gemacht werden, und die nächste Bereitstellung für jede Umgebung führt eine vollständige Installation von Grund auf durch. Bei einem großen Monorepo ist das ein langsamer Build, daher tun Sie es absichtlich und nicht reflexartig.

Häufige Probleme

"Build erfolgreich, aber die Website zeigt einen 404." Das Ausgabeverzeichnis ist falsch: Orbit hat einen Ordner veröffentlicht, der nicht Ihre Build-Ausgabe ist. Überprüfen Sie, welchen Ordner Ihr Build tatsächlich erstellt. Vite schreibt dist, Next.js statischer Export schreibt out, Next.js Servermodus verwendet .next, Create React App und Remix schreiben build, Nuxt schreibt .output.

"404 nur auf dynamischen Routen, die Startseite ist in Ordnung." Der Servermodus ist auf einer App deaktiviert, die ihn benötigt. Siehe den Abschnitt Next.js oben.

"Modul nicht gefunden" bei der ersten Bereitstellung. Entweder ist der Installationsschritt nicht ausgeführt worden, oder er wurde mit einem anderen Paketmanager ausgeführt als dem, den Sie lokal verwenden. Setzen Sie den Installationsbefehl explizit: npm ci, yarn install --frozen-lockfile, oder pnpm install --frozen-lockfile. Überprüfen Sie auch, dass Sie genau eine Sperrdatei committed haben: Wenn sowohl package-lock.json als auch yarn.lock im Repository sind, ist der erkannte Paketmanager möglicherweise nicht der, den Sie erwarten.

"Sperrdatei veraltet." npm ci und die Äquivalente mit gefrorener Sperrdatei weigern sich zu laufen, wenn die Sperrdatei nicht mit package.json übereinstimmt. Führen Sie lokal Ihren Paketmanager install aus und committen Sie die neu generierte Sperrdatei. Dies ist der häufigste Fehler bei der ersten Bereitstellung und tritt lokal nie auf, was genau der Grund dafür ist, dass es verwirrend ist.

"Nur eine App in meinem Monorepo wird bereitgestellt." Das ist das Stammverzeichnis, das seine Arbeit tut. Jede App benötigt ihr eigenes Orbit-Projekt mit ihrem eigenen Stammverzeichnis.

"Falsche Node.js-Version." Setzen Sie das Feld "Node.js-Version" nur auf die Hauptversionsnummer.

Der Build läuft aus Speicher oder füllt die Festplatte. Beide sind Planlimits auf der Build-Maschine: Launch erhält 1 vCPU, 1 GB RAM und 4 GB Festplatte; Liftoff erhält 2, 2 GB und 8 GB; Apex erhält 4, 4 GB und 16 GB. Das Hinzufügen von NODE_OPTIONS=--max-old-space-size=2048 als Umgebungsvariable hilft nur bis zur tatsächlichen RAM-Größe der Maschine. Siehe Orbit-Plan-Limits.