Orbit
Risoluzione dei problemi di build non riusciti
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…
Risoluzione dei problemi di build non riuscite
Quando una build di Kapsule Orbit non riesce, la pagina dei dettagli della distribuzione fornisce il registro completo più un riepilogo degli errori categorizzati e una correzione suggerita. Questa guida illustra come leggere quella pagina, gli errori che Kapsule Orbit riconosce per nome, quelli che non riconosce e cosa fare quando una build ha successo ma il sito è ancora sbagliato.
Lettura dell'errore
- Apri il tuo progetto in Kapsule Orbit.
- Apri la scheda Deployments.
- Fai clic sulla distribuzione con stato Failed.
- Leggi prima il riepilogo degli errori sopra il registro, poi il registro stesso.
Kapsule Orbit assegna a ogni errore una categoria: Out of memory, Compile error, Test failure, Lint error, Install error, Network error, Timeout o Unknown error. La categoria ti dice quale parte della pipeline guardare prima di leggere una singola riga del registro.
Esiste anche un pulsante Get AI diagnosis. Legge le ultime 120 righe del registro insieme al framework rilevato e alla categoria di errore e restituisce una spiegazione in linguaggio semplice.
La diagnosi è etichettata come AI-generated, verify before acting. Considerala come un ottimo indicatore della riga corretta del registro, non come un'autorità sulla tua base di codice. Leggi la riga a cui si riferisce prima di apportare modifiche.
Se la build non è mai iniziata e rimane bloccata su Queued, passa alla sezione sulle build in coda di seguito.
Errori che Kapsule Orbit riconosce per nome
Questi vengono forniti con una correzione suggerita specifica sulla pagina di distribuzione.
| Cosa rileva Kapsule Orbit | Cosa significa | Correzione |
|---|---|---|
| Missing module | Un import punta a un pacchetto che non è installato | Aggiungi il pacchetto a package.json e commitalo, oppure correggi il refuso nel percorso di import |
ERESOLVE conflict | npm non può soddisfare una peer dependency | Risolvi il conflitto in package.json, oppure aggiungi --legacy-peer-deps al tuo comando di installazione in Settings |
| TypeScript error | Il type checking non è riuscito durante la build | Correggi gli errori elencati. Per i problemi di tipo di terze parti, skipLibCheck: true in tsconfig.json |
| Out of memory | La build ha superato la RAM della macchina di build | Aggiungi NODE_OPTIONS=--max-old-space-size=2048 come variabile di ambiente, oppure passa a un piano con una macchina di build più grande |
| Build disk full | La build ha riempito il disco | Cerca un node_modules o un artefatto inaspettatamente grande, oppure passa a un piano con un disco di build più grande |
| Build timed out | La build ha raggiunto l'interruzione di 30 minuti | Abilita la cache di build, riduci la dimensione del bundle, o trova cosa è bloccato |
| Package not found (404) | Una dipendenza non esiste con quel nome o versione | Controlla package.json per un refuso, oppure conferma che il pacchetto è pubblicato |
| ESLint errors | Gli errori di lint hanno bloccato la build | Correggili, oppure interrompi il fatto che il lint blocchi la build nella configurazione del tuo framework |
| Syntax error | Sorgente non analizzabile | Bracket mancante, stringa non chiusa, o sintassi non supportata dalla tua versione di Node |
| File not found | Un file referenziato non è nel repository | Conferma che sia stato committato e controlla il case del percorso |
| Lockfile out of date | Il lockfile non corrisponde a package.json | Esegui localmente l'installazione del tuo package manager e committa il lockfile aggiornato |
La mancata corrispondenza del lockfile è il singolo errore di primo deployment più comune e il più confuso, perché non accade mai localmente. npm ci, yarn install --frozen-lockfile e pnpm install --frozen-lockfile si rifiutano di procedere quando il lockfile non concorda con package.json. Rigenera il lockfile localmente e committa.
Errori comuni per fase
Installazione della dipendenza non riuscita
La fase Install ha restituito un errore.
- Package manager sbagliato. Kapsule Orbit seleziona npm, yarn o pnpm dal tuo lockfile. Se è stato committato più di un lockfile, la scelta potrebbe non essere quella che ti aspetti. Elimina quelli che non stai usando, oppure imposta il comando Install command esplicitamente in Settings.
- Registro privato. Se una dipendenza proviene da un registro privato, il token di autenticazione deve essere disponibile al momento della build come variabile di ambiente, e il tuo
.npmrcdeve farvi riferimento. - Mancata corrispondenza della versione di Node.js. Alcuni pacchetti richiedono una versione minima di Node. Imposta Node.js version in Settings al numero di versione principale:
18,20o22. - Out of memory su un monorepo grande. Usa
npm cianzichénpm install, e considera un piano con una macchina di build più grande.
Il comando di build non riesce
La fase Build ha restituito un errore.
- Errori TypeScript o lint. Kapsule Orbit esegue il tuo comando di build esattamente come scritto. Se la tua build non riesce localmente, non riesce qui.
- Variabile di ambiente di build-time mancante. Una variabile letta durante la build deve esistere prima che la build venga eseguita, non solo in fase di runtime. Aggiungila nella scheda Env vars e ripubblica. Una variabile di build-time aggiunta dopo una distribuzione non si applica retroattivamente ad essa.
- Directory radice sbagliata in un monorepo. Imposta Root directory in Settings al percorso dell'app, ad esempio
apps/web.
Build scade
Le build vengono interrotte a 30 minuti di tempo wall-clock su tutti i piani. Se la tua si avvicina costantemente a questo limite:
- Controllare il log per un processo in attesa di input. Una build che richiede input è una build che si blocca.
- Evitare
--legacy-peer-depssu un grande albero di dipendenze a meno che non sia necessario. - Assicurarsi che la cache di build sia in uso. I piani Liftoff e Apex la includono; la pagina di distribuzione mostra Cache hit o Cold build.
- Passare a un piano con più vCPU di build. Vedere Limiti dei piani Orbit.
La Build Non Si Avvia Mai
Una distribuzione bloccata su Queued è in attesa di uno slot di build. La pagina dei dettagli mostra la posizione nella coda e quanti degli slot di build concorrenti sono in uso, e avvia automaticamente la build quando uno si libera. Launch e Liftoff consentono una build concorrente; Apex ne consente tre.
È possibile visualizzare tutto in elaborazione nell'account su Orbit, quindi Queue.
Se una distribuzione rimane in coda senza nulla in esecuzione, è più probabile che sia bloccata piuttosto che in coda. Verificare:
- Awaiting approval, se Require approval for production è attivo
- Un deploy lock sul progetto
- Una deploy freeze schedule che blocca l'ora o il giorno corrente
- CI required checks in attesa della pipeline
- Require staging success before production in attesa di una distribuzione di staging dello stesso commit
La Build È Stata Saltata Interamente
Se un push non ha prodotto alcuna distribuzione, è stato probabilmente filtrato di proposito:
- Ignored paths: ogni file nel push corrisponde a un pattern come
*.mdodocs/** - Branch ignore patterns: il branch corrisponde a qualcosa come
dependabot/* - Root directory: nulla nel push ha toccato la sottodirectory monorepo per questo progetto
- Branch previews disattivato e il push non era per la produzione o staging
Build Riuscita Ma il Sito È Sbagliato
Una build verde e un sito rotto è quasi sempre un problema di configurazione piuttosto che un problema di codice.
404 in ogni pagina. La Output directory è sbagliata: Orbit ha pubblicato una cartella che non è l'output della build. Controllare cosa scrive effettivamente la build. I valori comuni sono dist, .next, out, build e .output.
404 solo su rotte dinamiche. L'app ha bisogno di un server in esecuzione ed è servita come file statici. Attivare Server mode in Settings sotto Runtime. Questo è necessario per Next.js con SSR, Remix, Nuxt e tutto ciò che non è un'esportazione statica.
Assets 404 dopo una distribuzione, per gli utenti che erano già sul sito. Hanno caricato la vecchia pagina e stanno richiedendo URL di bundle vecchi che non esistono più. Attivare Skew protection in Settings, che mantiene disponibili gli artefatti della build precedente per una finestra di conservazione dopo che una nuova distribuzione viene pubblicata.
La variabile di ambiente è indefinita in fase di runtime. Confermare che l'ambito della variabile copra effettivamente questo ambiente e che la distribuzione sia successiva al cambiamento. La pagina dei dettagli della distribuzione elenca esattamente quali chiavi sono state iniettate al momento della build e le confronta con la configurazione corrente.
Le impostazioni di build specifiche del framework sono in Configurazione del comando di build e della directory di output.
Riprovare
Nella pagina della distribuzione fallita:
- Retry build esegue di nuovo lo stesso commit.
- More retry options, quindi Retry with cleared cache, elimina prima la cache di build.
È anche possibile fare in modo che Orbit riprovi automaticamente. Build auto-retry in Settings rimette in coda le build non riuscite causate da errori infrastrutturali come un guasto di rete o un timeout, fino a tre volte. Deliberatamente non ritenta gli errori di codice, quindi un errore di compilazione, lint o test non crea mai un ciclo.
Riprovare con una cache cancellata elimina il node_modules memorizzato nella cache per l'ambiente e non può essere annullato. La build successiva sarà lenta. Questo è lo scopo, ma non farlo riflettivamente su un grande monorepo.
Impedire a una Build Errata di Raggiungere gli Utenti
Se una distribuzione è già stata pubblicata e ha rotto qualcosa, eseguire il rollback invece di cercare di aggiustare velocemente sotto pressione. Il rollback promuove un artefatto già costruito e richiede secondi. Vedere Rolling Back a Deployment.
Per interrompere ulteriori distribuzioni mentre esamini la situazione, fai clic su Lock deploys sul progetto. Le distribuzioni attivate da push vengono quindi saltate finché non sblocchi, mentre le distribuzioni manuali funzionano comunque per poter inviare la correzione.
È anche possibile fare in modo che Orbit lo faccia automaticamente: Auto-rollback on failure ripristina l'ultima distribuzione integra quando una distribuzione in produzione non riesce, e un percorso Health check la ripristina quando la nuova distribuzione non risponde con un 2xx entro 15 secondi.
Ancora Bloccato
Se il log termina semplicemente senza messaggio di errore, il processo di build è stato molto probabilmente interrotto: memoria insufficiente o la macchina di build è stata reclamata. Riprovare una volta. Se fallisce nello stesso modo due volte, apri un ticket da KPanel o invia un'email a support@kapsulehost.com e includi l'ID di distribuzione mostrato nella pagina dei dettagli.