Risoluzione dei problemi di Artisan

In breve

Ogni errore del bridge si manifesta come un’eccezione tipizzata. Associare l’eccezione e il messaggio alla tabella seguente. Ogni riga indica il controllo esatto nel sorgente, così da correggere la causa e non il sintomo.

Diagnostica per eccezione

`ChromeNotAvailableException`

chrome-php/chrome is not installed. Install it via: composer require chrome-php/chrome:^1.15

La libreria client CDP non è presente nell’autoloader. BrowserPool::getBrowser() genera questa eccezione prima di qualsiasi avvio di Chrome. Eseguire il comando di installazione indicato. Questo caso è distinto da un binario mancante: il controllo della libreria e il controllo del binario avvengono in fasi separate.

`ChromeRenderException` — avvio o timeout

Chrome renderer failed: <cause>

Chrome non è riuscito ad avviarsi, ha raggiunto il timeout o si è arrestato in modo anomalo. L’eccezione precedente contiene la causa originale. Cause comuni:

Binario non trovato / non eseguibile. Verificare con chromium --headless --dump-dom about:blank. Impostare chrome_binary sul percorso assoluto.
Impossibile inizializzare il sandbox (container). La causa menziona il sandbox o il namespace. Predisporre un container che supporti il sandbox (opzione preferita) oppure impostare no_sandbox: true dopo aver letto /integrations/artisan/security-and-operations/.
Timeout. Un documento pesante ha superato render_timeout. Aumentare il timeout per quel carico di lavoro o ridurre il documento; valutare il compromesso rispetto al denial-of-service su un percorso esposto agli utenti.
Librerie condivise mancanti. Chrome termina immediatamente. Installare l’insieme di dipendenze di Chrome richiesto dalla distribuzione.

`ChromeRenderException` — output vuoto

Chrome printToPDF returned empty data

Chrome si è avviato e printToPDF ha restituito zero byte. La causa abituale è un input che non produce nessun box renderizzato (body vuoto, tutto il contenuto display:none), oppure un arresto anomalo di Chrome durante la stampa. Verificare che l’HTML venga renderizzato in un box visibile. Controllare la pressione sulla memoria dell’host.

`RuntimeException` — input rifiutato prima di Chrome

Il messaggio contiene	Causa	Soluzione
`exceeds maximum allowed size`	HTML oltre `maxHtmlSize`	Ridurre l’input o aumentare `max_html_size` (amplia la superficie di esaurimento delle risorse)
`oversized base64 data URI`	base64 inline ≥ 13 MB	Ridurre l’asset incorporato; fare riferimento a un’immagine più piccola
`forbidden meta refresh redirect`	`<meta http-equiv="refresh">` presente	Rimuovere il tag; è un vettore di navigazione SSRF e viene sempre rifiutato

Questi casi provengono da ChromeSecurityPolicy::validate() e si attivano prima di contattare Chrome, quindi sono rapidi ed economici da riprodurre nei test.

`PdfParseException`

Page <n> has no content stream

Chrome ha prodotto un PDF da cui il parser non è riuscito a estrarre una pagina. È un caso raro e indica un output di Chrome malformato o una versione di Chrome che produce una struttura imprevista. Raccogliere la versione di Chrome e l’input. Verificare che il binario sia una build di Chrome/Chromium supportata.

Gli asset remoti vengono renderizzati vuoti

Non si tratta di un bug. Il bridge blocca ogni fetch di sottorisorse (CSP default-src 'none' più un blocco CDP setBlockedURLs('*')). <img> remoti, fogli di stile, font, script e iframe non vengono caricati. Incorporare gli asset come URI data: e inserire il CSS inline tramite defaultCss o <style>. Consultare il modello di rete in /integrations/artisan/security-and-operations/.

Contenuto tagliato in fondo

Il documento ha superato lo spazio disponibile ed è finito su una seconda pagina di Chrome, mentre il bridge ha importato solo la pagina 0. Il buffer di adattamento automatico era troppo piccolo per un reflow insolitamente alto, oppure un’altezza esplicita era troppo ridotta. Fornire un’altezza esplicita dimensionata in base al contenuto, oppure rimuovere l’altezza esplicita per usare l’adattamento automatico con il relativo buffer di sicurezza. Consultare la gestione dell’altezza in /integrations/artisan/production-usage/.

Picco di latenza ogni ~100 rendering

È un comportamento previsto. BrowserPool riavvia Chrome ogni 100 rendering per limitare la memoria. Una riga di log di livello notice registra il riavvio insieme al numero di rendering. Considerarlo un costo periodico noto negli SLO, non un incidente. Una frequenza di riavvio superiore a ogni 100 rendering indica documenti più pesanti del previsto.

La memoria cresce durante un batch lungo

BrowserPool limita la crescita con il riavvio ogni 100 rendering, ma un worker molto longevo può comunque accumulare memoria. Chiamare close() tra batch di grandi dimensioni per riciclare anticipatamente il processo di Chrome ed eseguire il worker con un limite di memoria dell’host.

Elenco di controllo diagnostico

Riprodurre con un frammento HTML affidabile e minimale per isolare l’input dall’ambiente.
Eseguire chromium --headless --dump-dom about:blank sull’host, usando l’utente del worker.
Iniettare un logger PSR-3 e leggere le righe info/notice (percorso del binario, conteggio dei riavvii).
Verificare che chrome-php/chrome sia installato: è installato se BrowserPool::getBrowser() non genera ChromeNotAvailableException.
Controllare l’eccezione precedente per individuare la causa sottostante di Chrome.

Vedere anche

/integrations/artisan/install/
/integrations/artisan/configuration/
/integrations/artisan/security-and-operations/
/integrations/artisan/chrome-renderer-setup/
/integrations/artisan/production-usage/