Probleemoplossing voor Artisan

In één oogopslag

Elke fout in de brug wordt gemeld als een getypeerde exception. Zoek de exception en het bericht op in de onderstaande tabel. Elke rij verwijst naar de broncontrole die de fout heeft veroorzaakt, zodat de oorzaak kan worden opgelost in plaats van alleen het symptoom.

Diagnose op basis van exception

`ChromeNotAvailableException`

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

De clientbibliotheek voor het Chrome DevTools Protocol (CDP) staat niet in de autoloader. BrowserPool::getBrowser() werpt deze exception op voordat Chrome wordt gestart. Voer het installatiecommando uit. Dit verschilt van een ontbrekende binary: de bibliotheekcontrole en de binary-controle worden in afzonderlijke fasen uitgevoerd.

`ChromeRenderException` — starten of time-out

Chrome renderer failed: <cause>

Chrome kon niet starten, liep tegen een time-out aan of crashte. De voorgaande exception bevat de oorspronkelijke oorzaak. Controleer deze veelvoorkomende oorzaken:

Binary niet gevonden of niet uitvoerbaar. Controleer dit met chromium --headless --dump-dom about:blank. Stel chrome_binary in op het absolute pad.
Sandbox kan niet initialiseren (containers). De oorzaak vermeldt de sandbox of namespace. Gebruik waar mogelijk een container die de sandbox ondersteunt, of stel no_sandbox: true in na het lezen van /integrations/artisan/security-and-operations/.
Time-out. Een zwaar document overschreed render_timeout. Verhoog de time-out voor die workload, of verklein het document. Weeg dit bij een gebruikersgericht pad af tegen denial-of-service.
Ontbrekende gedeelde bibliotheken. Chrome sluit onmiddellijk af. Installeer de set Chrome-afhankelijkheden voor de distributie.

`ChromeRenderException` — lege uitvoer

Chrome printToPDF returned empty data

Chrome is gestart, maar printToPDF leverde nul bytes op. De gebruikelijke oorzaak is invoer die geen gerenderde box oplevert, zoals een lege body of inhoud die op display:none is ingesteld, of een crash van Chrome tijdens het afdrukken. Bevestig dat de invoer in Hypertext Markup Language (HTML) als zichtbare box wordt gerenderd. Controleer de geheugendruk op de host.

`RuntimeException` — invoer geweigerd vóór Chrome

Bericht bevat	Oorzaak	Oplossing
`exceeds maximum allowed size`	HTML overschrijdt `maxHtmlSize`	Verklein de invoer of verhoog `max_html_size` (dit vergroot het aanvalsoppervlak voor resource-uitputting)
`oversized base64 data URI`	Inline base64-data-URI (Uniform Resource Identifier) ≥ 13 MB	Verklein de ingesloten asset; verwijs naar een kleinere afbeelding
`forbidden meta refresh redirect`	`<meta http-equiv="refresh">` aanwezig	Verwijder de tag; dit is een navigatievector voor server-side request forgery (SSRF) en wordt altijd geweigerd

Deze fouten zijn afkomstig van ChromeSecurityPolicy::validate() en treden op voordat Chrome wordt aangesproken, waardoor ze snel en goedkoop door tests zijn af te dekken.

`PdfParseException`

Page <n> has no content stream

Chrome heeft een Portable Document Format (PDF)-bestand geproduceerd waaruit de parser geen pagina kon extraheren. Dit komt zelden voor en wijst meestal op misvormde Chrome-uitvoer of een Chrome-versie met een onverwachte structuur. Leg de Chrome-versie en de invoer vast. Controleer of de binary een ondersteunde Chrome/Chromium-build is.

Externe assets worden leeg weergegeven

Dit is geen bug. De brug blokkeert elke ophaalactie voor subresources met Content Security Policy (CSP) default-src 'none' en een CDP-blokkering via setBlockedURLs('*'). Externe <img>, stylesheets, lettertypen, scripts en iframes worden niet geladen. Neem assets inline op als data:-URI’s en neem Cascading Style Sheets (CSS) inline op via defaultCss of <style>. Zie het netwerkmodel op /integrations/artisan/security-and-operations/.

Inhoud onderaan afgekapt

Het document liep over naar een tweede Chrome-pagina en de brug importeerde alleen pagina 0. De auto-fit-buffer was te klein voor een ongewoon hoge reflow, of een expliciete hoogte was te klein. Stel een expliciete hoogte in die op de inhoud is afgestemd, of verwijder de expliciete hoogte om auto-fit met de bijbehorende veiligheidsbuffer te gebruiken. Zie de afhandeling van hoogte op /integrations/artisan/production-usage/.

Latentiepiek om de ~100 renders

Dit is verwacht gedrag. BrowserPool herstart Chrome om de 100 renders om het geheugen te begrenzen. Een logregel op notice-niveau registreert de herstart en het aantal renders. Beschouw dit als een bekende periodieke kostenpost in service-level objectives (SLO’s), niet als een incident. Als Chrome vaker dan om de 100 renders wordt herstart, zijn de documenten zwaarder dan verwacht.

Geheugen groeit tijdens een lange batch

BrowserPool begrenst de groei door om de 100 renders te herstarten, maar een zeer langlevende worker kan toch geheugen ophopen. Roep close() aan tussen grote batches om Chrome vroegtijdig te recyclen, en draai de worker met een geheugenlimiet op de host.

Diagnostische checklist

Reproduceer het probleem met een minimaal, vertrouwd HTML-fragment om invoerproblemen van omgevingsproblemen te scheiden.
Voer chromium --headless --dump-dom about:blank uit op de host als de worker-gebruiker.
Injecteer een logger volgens PHP Standards Recommendation 3 (PSR-3) en lees de info/notice-regels, inclusief het binary-pad en het aantal herstarts.
Bevestig dat chrome-php/chrome is geïnstalleerd: BrowserPool::getBrowser() werpt geen ChromeNotAvailableException op wanneer het beschikbaar is.
Controleer de voorgaande exception in de exception op de onderliggende Chrome-oorzaak.

Zie ook

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