Configurazione del comando di compilazione e della directory di output

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…

Configurazione del comando di build e della directory di output

Per fare in modo che Orbit compili correttamente il tuo progetto è sufficiente configurare alcuni campi in Settings: comando di installazione, comando di compilazione, directory di output, directory radice e versione di Node.js. Se lasciati vuoti vengono rilevati automaticamente, e la maggior parte dei problemi al primo deploy derivano da un valore rilevato automaticamente che non corrisponde a quello che il tuo framework scrive effettivamente.

Dove trovare le impostazioni

Apri il tuo progetto in Orbit, accedi alla scheda Settings, e trova la scheda Build settings.

Field	What it does	Placeholder when blank
Install command	Come vengono installate le dipendenze prima del build	`npm ci (auto-detected)`
Build command	Il comando che produce il tuo output	`npm run build (auto-detected)`
Output directory	La cartella che Orbit pubblica dopo il build	`dist (auto-detected)`
Root directory	Per i monorepo, la sottodirectory che contiene la tua app	`/ (monorepo subdirectory)`
Node.js version	La versione principale di Node da usare per il build e l'esecuzione	Platform default

Lascia vuoti i campi per consentire a Orbit di rilevare automaticamente. Fai clic su Salva sulla scheda Impostazioni build per applicare.

Build settings card in Orbit project settings

Changing a build setting does not change the deployment that is currently live. The new setting applies from the next deployment. Redeploy after saving, or nothing will appear to have happened.

Impostazioni predefinite dei framework

Next.js

Next.js ha due modalità in Orbit, e scegliere quella sbagliata è l'errore più comune al primo deployment.

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

Comando di compilazione: npm run build
Directory di output: out
Modalità server: off

Modalità server (SSR o ISR), che riguarda la maggior parte delle app Next.js:

Attiva la modalità Server in Impostazioni, sotto Runtime
Comando di compilazione: npm run build
Directory di output: .next

Without server mode enabled, a server-rendered Next.js app is published as static files. The home page will usually load and every dynamic route will 404. If that is your symptom, this is your cause: turn on server mode and redeploy before changing anything else.

Astro

La cartella di output di Astro è dist in ogni modalità. Quello che cambia è se hai bisogno della modalità server.

output: 'static', l'impostazione predefinita: directory di output dist, modalità server disattivata
output: 'server' o output: 'hybrid': directory di output dist, modalità server attivata
Comando di compilazione: npm run build, oppure astro build

Vite (React, Vue, Svelte)

Comando di compilazione: npm run build, oppure vite build
Directory di output: dist

Vite scrive sempre in dist a meno che tu non abbia sovrascritto build.outDir in vite.config.ts. Se lo hai fatto, imposta la directory di output in modo che corrisponda.

SvelteKit

Comando di compilazione: npm run build
Cartella di output: build

Se hai bisogno della modalità server dipende dal tuo adattatore: un adattatore statico non la richiede, mentre un adattatore Node sì.

Nuxt 3

Comando di build: npm run build
Directory di output: .output
Modalità server: on

Remix

Comando di build: npm run build
Directory di output: build
Modalità server: attiva

Express o una plain Node API

Comando di build: npm run build
Directory di output: dist
Modalità server: attiva

La modalità server esegue npm start dopo la compilazione, quindi assicurati che il tuo script start esista e avvii il server.

Create React App

Create React App è deprecato upstream e non è una buona scelta per un nuovo progetto, ma i progetti esistenti si compilano correttamente.

Comando di compilazione: npm run build
Directory di output: build

Plain HTML o un generatore di siti statici

Lascia vuoto il comando di installazione se non esiste package.json
Lascia vuoto il comando di compilazione per pubblicare il repository così com'è, oppure imposta il comando del tuo generatore
Directory di output: . per la radice del repository, oppure qualsiasi cartella in cui il generatore scrive

Versione di Node.js

Inserisci solo il numero di versione principale: 18, 20 o 22. Il suggerimento del campo lo dice esplicitamente. Qualsiasi altra cosa, come 20.11.0 o v20, non è quello che questo campo si aspetta.

La versione si applica alla build e, quando la modalità server è attiva, anche al runtime.

Pin the version rather than relying on the default. A dependency that needs a newer Node fails during install with an error that rarely says "wrong Node version" in so many words, and pinning removes that class of failure entirely.

Monorepo

Impostare Root directory al percorso della tua app, ad esempio apps/web. Orbit accede a quella directory prima di eseguire i comandi di installazione e build, e la directory di output è quindi relativa ad essa.

L'hint del campo illustra il secondo comportamento, più utile: i push che modificano solo file al di fuori di quel percorso vengono saltati automaticamente. Un monorepo con quattro progetti Orbit ricostruisce solo le app che un commit ha effettivamente toccato, il che consente di risparmiare sia tempo che minuti di build.

Ogni ambiente può sovrascrivere la directory radice indipendentemente, sotto Staging: build overrides in Settings, il che è utile quando staging crea build da un workspace diverso.

Override per staging

Se il tuo progetto dispone di un ambiente di staging, Impostazioni mostra una sezione Staging: build overrides con gli stessi campi. Qualsiasi campo lasciato vuoto eredita il valore a livello di progetto, quindi puoi modificare solo il comando di build per lo staging, ad esempio in npm run build:staging, e lasciare tutto il resto invariato.

La gestione temporanea (staging) ha le proprie impostazioni correlate nelle vicinanze: un ramo, una password di accesso, una lista di indirizzi IP consentiti, il rollback automatico in caso di errore e un interruttore Eredita variabili di ambiente di produzione.

Cache del build

Orbit memorizza nella cache node_modules tra i build sui piani Liftoff e Apex. La pagina dei dettagli di distribuzione mostra Cache hit o Cold build, insieme alla durata della fase di installazione, in modo da poter vedere il valore della cache nel tuo progetto.

Per forzare una reinstallazione completa, apri Settings, fai clic su Clear build cache e conferma.

Clearing the build cache cannot be undone, and the next deployment for every environment runs a full install from scratch. On a large monorepo that is a slow build, so do it deliberately rather than as a reflex.

Problemi comuni

"Build riuscito ma il sito mostra un 404." La directory di output è sbagliata: Orbit ha pubblicato una cartella che non è il tuo output di build. Controlla quale cartella crea effettivamente il tuo build. Vite scrive dist, Next.js static export scrive out, Next.js server mode utilizza .next, Create React App e Remix scrivono build, Nuxt scrive .output.

"Errore 404 solo sulle rotte dinamiche, la home page funziona correttamente." La modalità server è disattivata su un'app che la richiede. Vedi la sezione Next.js qui sopra.

"Modulo non trovato" al primo deploy. O il passaggio di installazione non è stato eseguito, oppure è stato eseguito con un gestore di pacchetti diverso da quello che usi localmente. Imposta il comando di installazione in modo esplicito: npm ci, yarn install --frozen-lockfile, o pnpm install --frozen-lockfile. Verifica inoltre di aver eseguito il commit di esattamente un file di lock: se sia package-lock.json che yarn.lock sono nel repository, il gestore di pacchetti rilevato potrebbe non essere quello che ti aspetti.

"Lockfile non aggiornato." npm ci e gli equivalenti frozen-lockfile si rifiutano di eseguire quando il lockfile non corrisponde a package.json. Esegui il comando install del tuo gestore di pacchetti localmente e fai il commit del lockfile rigenerato. Questo è l'errore più comune nel primo deploy e non si riproduce mai localmente, il che è esattamente il motivo per cui è confusionario.

"Solo un'app nel mio monorepo è in fase di distribuzione." Questa è la directory radice che svolge il suo lavoro. Ogni app ha bisogno del proprio progetto Orbit con la propria directory radice.

"Versione Node.js errata." Impostare il campo della versione Node.js solo al numero di versione principale.

La build esaurisce la memoria o riempie il disco. Entrambi sono limiti del piano sulla macchina di build: Launch dispone di 1 vCPU, 1 GB di RAM e 4 GB di disco; Liftoff dispone di 2, 2 GB e 8 GB; Apex dispone di 4, 4 GB e 16 GB. Aggiungere NODE_OPTIONS=--max-old-space-size=2048 come variabile di ambiente aiuta solo fino alla RAM effettiva della macchina. Consultare Limiti del Piano Orbit.

Approfondimenti correlati

Framework e Runtime supportati in Orbit
Risoluzione dei problemi di build non riuscite
Variabili di ambiente per la configurazione al momento della build