Orbit
Framework e Runtime supportati in Orbit
Orbit builds any project that installs with npm, yarn or pnpm and produces a folder of files or a Node.js server, and it detects the framework and package manager for you so most projects deploy…
Orbit compila qualsiasi progetto che si installa con npm, yarn o pnpm e produce una cartella di file o un server Node.js. Orbit rileva il framework e il gestore di pacchetti per te, così la maggior parte dei progetti viene distribuita senza alcuna configurazione di build. Questa guida spiega cosa viene rilevato, le impostazioni necessarie per ogni framework comune, quando devi attivare la modalità server e come scegliere una versione di Node.js.
Cosa Orbit Rileva Automaticamente
Quando una build viene eseguita, Orbit registra quello che ha trovato e te lo mostra:
- Framework, nella pagina di dettaglio della distribuzione e come badge sulle carte di distribuzione nella panoramica del progetto.
- Gestore di pacchetti, scelto dal tuo lockfile:
package-lock.jsonfornisce npm,yarn.lockfornisce yarn,pnpm-lock.yamlfornisce pnpm.
Le impostazioni di build in Settings sono tutte facoltative. Lascia un campo vuoto e il suo placeholder ti dice cosa verrà utilizzato invece: Install command mostra npm ci (auto-detected), Build command mostra npm run build (auto-detected), e Output directory mostra dist (auto-detected).
Esegui il commit di esattamente un lockfile. Se sia package-lock.json che yarn.lock si trovano nel repository, il gestore di pacchetti che Orbit sceglie potrebbe non essere quello che usi localmente, e otterrai un'installazione che si comporta diversamente dalla tua macchina senza una ragione visibile. Elimina quello che non stai utilizzando.
Impostazioni Per Framework
Questi sono i valori necessari per ogni framework. Dove Orbit fornisce un modello di avvio per il framework, il modello utilizza esattamente queste impostazioni.
| Framework | Comando di build | Cartella di output | Modalità server |
|---|---|---|---|
| Next.js, esportazione statica | npm run build | out | Off |
| Next.js, SSR o ISR | npm run build | .next | On |
| Astro, statico | astro build | dist | Off |
| Astro, server o ibrido | astro build | dist | On |
| Vite (React, Vue, Svelte) | npm run build | dist | Off |
| SvelteKit | npm run build | build | Dipende dall'adapter |
| Nuxt 3 | npm run build | .output | On |
| Remix | npm run build | build | On |
| Express o una semplice API Node | npm run build | dist | On |
| Create React App | npm run build | build | Off |
| HTML semplice o generatore statico | lascia vuoto, o il comando del tuo generatore | . o la cartella in cui scrive | Off |
Vite scrive sempre in dist a meno che tu non abbia impostato build.outDir in vite.config.ts. La cartella di output di Astro è dist in ogni modalità. Quello che cambia tra le modalità è se hai bisogno della modalità server, non dove i file finiscono.
Modalità Server
La modalità server è un'opzione in Settings, sotto Runtime. Quando è attivata, Orbit mantiene viva la macchina di build eseguendo npm start dopo ogni distribuzione invece di servire una cartella di file statici.
Attivala per Next.js con SSR, Remix, Nuxt, un'API Express e qualsiasi altra cosa che non sia un'esportazione statica. Lasciarla disattivata per una build veramente statica.
Si applica dalla prossima distribuzione, non a quella attualmente in diretta.
Il sintomo classico di una modalità server mancante è un sito in cui la home page si carica perfettamente e ogni route dinamica restituisce un 404. La build è riuscita, i file sono stati pubblicati, e semplicemente non c'è alcun server in esecuzione per rispondere alle route. Se è quello che stai vedendo, attiva la modalità server e ridistribuisci prima di cambiare qualsiasi altra cosa.
Versione Node.js
Imposta Node.js version in Settings sotto Build settings. Inserisci il numero di versione principale solamente: 18, 20 o 22. Lascialo vuoto per utilizzare l'impostazione predefinita della piattaforma.
La versione si applica sia alla build che, quando la modalità server è attivata, al runtime.
Fissa la versione esplicitamente piuttosto che affidarti all'impostazione predefinita. Una dipendenza che richiede un Node più recente dell'impostazione predefinita fa fallire l'installazione con un errore che non dice ovviamente così, e il pinning rimuove un'intera classe di errori di build "ha funzionato ieri".
Monorepo
Imposta Root directory sulla sottodirectory contenente l'app, ad esempio apps/web. Orbit cambia in quella directory prima di eseguire i comandi di installazione e build.
Fa anche qualcosa che vuoi ma potresti non aspettarti: i push che cambiano solo file al di fuori di quel percorso vengono saltati automaticamente. Un monorepo con quattro progetti Orbit quindi ricostruisce solo le app che un commit ha effettivamente toccato.
Ogni ambiente può ignorare la root directory separatamente, sotto Staging: build overrides in Settings, il che è utile quando lo staging compila un workspace diverso.
Impostazioni di Build Personalizzate
Ignora qualsiasi cosa in Settings, sotto Build settings:
| Campo | Esempio | Note |
|---|---|---|
| Install command | npm ci | O yarn install --frozen-lockfile, pnpm install --frozen-lockfile |
| Build command | npm run build:prod | Esegui esattamente come scritto |
| Output directory | dist/client | La cartella pubblicata dopo la build |
| Root directory | apps/frontend | Sottodirectory monorepo |
| Node.js version | 20 | Solo versione principale |
Vuoto significa rilevamento automatico. Fai clic su Save sulla scheda Build settings per applicare.
Staging può ignorare uno qualsiasi di questi indipendentemente, nella sezione Staging: build overrides. Un campo lasciato vuoto lì eredita il valore a livello di progetto, così puoi cambiare solo il comando di build per lo staging e lasciare tutto il resto invariato.
Cache di Build
Orbit memorizza nella cache node_modules tra le build nei piani Liftoff e Apex. Quando la cache viene utilizzata, la distribuzione mostra un badge Cache hit e la fase di installazione è molto più breve. Una build senza di essa mostra Cold build.
Per forzare una reinstallazione completa, apri Settings, quindi Clear build cache, e conferma. La prossima distribuzione per ogni ambiente esegue un'installazione completa da zero. Questo non può essere annullato, e la build dopo sarà lenta.
Risorse della Macchina di Build
La dimensione della macchina di build dipende dal tuo piano, il che è importante per le build di grandi dimensioni:
| Piano | vCPU | RAM | Disco | Limite di tempo |
|---|---|---|---|---|
| Launch | 1 | 1 GB | 4 GB | 30 minuti |
| Liftoff | 2 | 2 GB | 8 GB | 30 minuti |
| Apex | 4 | 4 GB | 16 GB | 30 minuti |
Una build che esaurisce la memoria o riempie il disco fallisce con quella categoria di errore indicata nella pagina di distribuzione. Aumentare NODE_OPTIONS=--max-old-space-size aiuta solo fino alla RAM effettiva della macchina.
Iniziare da un Modello
Se desideri una distribuzione funzionante prima di avere un repository, utilizza un modello di avvio. Su New project, passa da Import Git Repo a Start from Template e scegline uno: Next.js con shadcn/ui, un sito di marketing Astro, Remix Indie Stack, uno starter SvelteKit, un'app Nuxt 3 minima, o un'API REST Express. Orbit copia il modello, applica le giuste impostazioni di build, e lo distribuisce.
Letture Correlate
- Configurazione del Comando di Build e della Cartella di Output per i dettagli per-framework e gli errori comuni
- Risoluzione dei Problemi di Build Non Riuscite
- Limiti del Piano Orbit