Uw buildopdracht en uitvoermap configureren

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…

Uw Orbit-project correct laten bouwen komt neer op een handvol velden in Settings: installatiecommando, buildcommando, uitvoermap, rootmap en Node.js-versie. Als deze leeg zijn gelaten, worden ze automatisch gedetecteerd, en de meeste problemen bij de eerste implementatie komen voort uit een automatisch gedetecteerde waarde die niet overeenkomt met wat uw framework daadwerkelijk schrijft.

Waar u de instellingen vindt

Open uw project in Orbit, ga naar het tabblad Settings en zoek de kaart Build settings.

Veld	Wat het doet	Tijdelijke aanduiding als leeg
Installatiecommando	Hoe afhankelijkheden worden geïnstalleerd vóór de build	`npm ci (auto-detected)`
Buildcommando	Het commando dat uw uitvoer produceert	`npm run build (auto-detected)`
Uitvoermap	De map die Orbit na de build publiceert	`dist (auto-detected)`
Rootmap	Voor monorepo's, de subdirectory met uw app	`/ (monorepo subdirectory)`
Node.js-versie	De grote Node-versie om mee te bouwen en uit te voeren	Platform default

Laat elk veld leeg om Orbit automatisch te laten detecteren. Klik op Save op de kaart Build settings om toe te passen.

Kaart Build settings in Orbit-projectinstellingen

Het wijzigen van een build-instelling wijzigt niet de implementatie die momenteel live is. De nieuwe instelling geldt vanaf de volgende implementatie. Implementeer opnieuw na opslaan, anders lijkt er niets te zijn gebeurd.

Framework-standaardinstellingen

Next.js

Next.js heeft twee modi in Orbit, en het kiezen van de verkeerde is de meest voorkomende fout bij de eerste implementatie.

Statische export (output: 'export' in next.config.js):

Buildcommando: npm run build
Uitvoermap: out
Servermodus: uit

Servermodus (SSR of ISR), wat de meeste Next.js-apps zijn:

Zet Server mode aan in Settings, onder Runtime
Buildcommando: npm run build
Uitvoermap: .next

Zonder servermodus ingeschakeld wordt een server-weergegeven Next.js-app gepubliceerd als statische bestanden. De startpagina wordt meestal geladen en elke dynamische route geeft 404. Als dat uw symptoom is, is dit uw oorzaak: schakel servermodus in en implementeer opnieuw voordat u iets anders wijzigt.

Astro

De uitvoermap van Astro is dist in elke modus. Wat verandert is of u servermodus nodig hebt.

output: 'static', de standaard: uitvoermap dist, servermodus uit
output: 'server' of output: 'hybrid': uitvoermap dist, servermodus aan
Buildcommando: npm run build, of astro build

Vite (React, Vue, Svelte)

Buildcommando: npm run build, of vite build
Uitvoermap: dist

Vite schrijft altijd naar dist tenzij u build.outDir in vite.config.ts hebt overschreven. Stel in dat geval de uitvoermap in om dit aan te passen.

SvelteKit

Buildcommando: npm run build
Uitvoermap: build

Of u servermodus nodig hebt, hangt af van uw adapter: een statische adapter niet, een Node-adapter wel.

Nuxt 3

Buildcommando: npm run build
Uitvoermap: .output
Servermodus: aan

Remix

Buildcommando: npm run build
Uitvoermap: build
Servermodus: aan

Express of een gewone Node API

Buildcommando: npm run build
Uitvoermap: dist
Servermodus: aan

Servermodus voert npm start na de build uit, dus zorg ervoor dat uw start-script bestaat en de server start.

Create React App

Create React App is stroomopwaarts afgeschaft en is niet geschikt voor een nieuw project, maar bestaande projecten bouwen prima.

Buildcommando: npm run build
Uitvoermap: build

Gewone HTML of een statische site-generator

Laat het installatiecommando leeg als er geen package.json is
Laat het buildcommando leeg om de repository als zodanig te publiceren, of stel het commando van uw generator in
Uitvoermap: . voor de repositorybasis, of welke map de generator ook schrijft

Node.js-versie

Voer alleen het major versienummer in: 18, 20 of 22. De hint van het veld zegt dit expliciet. Iets anders, zoals 20.11.0 of v20, is niet wat dit veld verwacht.

De versie geldt voor de build en, wanneer servermodus aan is, ook voor de runtime.

Zet de versie vast in plaats van op de standaardwaarde te vertrouwen. Een afhankelijkheid die een nieuwere Node nodig heeft, mislukt tijdens de installatie met een fout die zelden "verkeerde Node-versie" zegt en het vaststellen van de versie elimineert deze klasse van fouten volledig.

Monorepo's

Stel Root directory in op het pad van uw app, bijvoorbeeld apps/web. Orbit gaat in die directory voordat het uw installatie- en buildcommando's uitvoert, en de uitvoermap is dan relatief daaraan.

De hint van het veld schetst het tweede, meer bruikbare gedrag: verschuivingen die alleen bestanden buiten dat pad veranderen worden automatisch overgeslagen. Een monorepo met vier Orbit-projecten bouwt alleen de apps die een commit daadwerkelijk heeft aangeraakt, wat zowel tijd als buildminuten bespaart.

Elke omgeving kan de rootmap onafhankelijk overschrijven, onder Staging: build overrides in Settings, wat handig is wanneer staging een ander werkgebied bouwt.

Staging-overschrijvingen

Als uw project een staging-omgeving heeft, toont Settings een sectie Staging: build overrides met dezelfde velden. Elk veld dat daar leeg is gelaten, erft de waarde op projectniveau, dus u kunt bijvoorbeeld alleen het buildcommando voor staging wijzigen in npm run build:staging en alles ander met rust laten.

Staging heeft eigen gerelateerde instellingen in de buurt: een branch, een toegangswachtwoord, een IP-allowlist, automatisch terugdraaien bij falen en een Inherit production env vars-schakelaar.

Build-cache

Orbit plaatst node_modules tussen builds in cache op de Liftoff en Apex-plannen. De pagina met implementatiedetails toont Cache hit of Cold build, samen met de duur van de installatiefase, zodat u kunt zien wat de cache voor uw project waard is.

Om een volledige herinstallatie af te dwingen, opent u Settings, klikt u op Clear build cache en bevestigt u dit.

Het wissen van de build-cache kan niet ongedaan worden gemaakt, en de volgende implementatie voor elke omgeving voert een volledige installatie helemaal opnieuw uit. Bij een grote monorepo is dat een langzame build, dus doe het opzettelijk in plaats van als reflex.

Veelvoorkomende valkuilen

"Build geslaagd maar de site toont een 404." De uitvoermap is fout: Orbit heeft een map gepubliceerd die niet uw build-uitvoer is. Controleer welke map uw build daadwerkelijk maakt. Vite schrijft naar dist, Next.js statische export schrijft naar out, Next.js servermodus gebruikt .next, Create React App en Remix schrijven naar build, Nuxt schrijft naar .output.

"404 alleen op dynamische routes, de startpagina is prima." Servermodus is uit op een app die het nodig heeft. Zie de Next.js-sectie hierboven.

"Module niet gevonden" bij de eerste implementatie. Ofwel de installatiestap is niet uitgevoerd, ofwel is deze uitgevoerd met een ander pakketbeheer dan degene die u lokaal gebruikt. Stel het installatiecommando expliciet in: npm ci, yarn install --frozen-lockfile of pnpm install --frozen-lockfile. Controleer ook of u exact één lockfile hebt gecommit: als zowel package-lock.json als yarn.lock in de repository staan, is het gedetecteerde pakketbeheer mogelijk niet degene die u verwacht.

"Lockfile verouderd." npm ci en de frozen-lockfile-equivalenten weigeren uit te voeren wanneer de lockfile niet overeenkomt met package.json. Voer uw pakketbeheer lokaal uit en commit de opnieuw gegenereerde lockfile. Dit is de meest voorkomende eerste implementatiefout en deze reproduceert zich nooit lokaal, wat precies de reden is waarom dit verwarrend is.

"Slechts één app in mijn monorepo wordt geïmplementeerd." Dat is de rootmap die zijn werk doet. Elke app heeft zijn eigen Orbit-project met zijn eigen rootmap nodig.

"Verkeerde Node.js-versie." Stel het veld Node.js-versie in op alleen het major versienummer.

De build loopt vast te lopen voor geheugen of vult de schijf. Beide zijn planlimieten op de buildmachine: Launch krijgt 1 vCPU, 1 GB RAM en 4 GB schijf; Liftoff krijgt 2, 2 GB en 8 GB; Apex krijgt 4, 4 GB en 16 GB. Het toevoegen van NODE_OPTIONS=--max-old-space-size=2048 als omgevingsvariabele helpt alleen tot aan het werkelijke RAM van de machine. Zie Orbit Plan Limits.

Gerelateerde informatie

Ondersteunde frameworks en runtimes in Orbit
Mislukte builds oplossen
Omgevingsvariabelen voor buildtime-configuratie