Fehlerbehebung für Artisan

Auf einen Blick

Jeder Fehler der Brücke zeigt sich als typisierte Ausnahme. Ordnen Sie Ausnahme und Meldung der Tabelle unten zu. Jede Zeile verweist auf die genaue Quellprüfung, sodass Sie die Ursache beheben und nicht nur das Symptom.

Diagnose nach Ausnahme

`ChromeNotAvailableException`

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

Die CDP-Client-Bibliothek ist im Autoloader nicht verfügbar. BrowserPool::getBrowser() löst dies aus, bevor Chrome überhaupt gestartet wird. Führen Sie den Installationsbefehl aus. Das unterscheidet sich von einer fehlenden Binärdatei: Die Bibliotheksprüfung und die Binärprüfung sind getrennte Stufen.

`ChromeRenderException` — Start oder Zeitüberschreitung

Chrome renderer failed: <cause>

Chrome konnte nicht starten, lief in eine Zeitüberschreitung oder ist abgestürzt. Die vorhergehende Ausnahme enthält die ursprüngliche Ursache. Häufige Ursachen:

Binärdatei nicht gefunden / nicht ausführbar. Prüfen Sie das mit chromium --headless --dump-dom about:blank. Setzen Sie chrome_binary auf den absoluten Pfad.
Die Sandbox kann nicht initialisiert werden (Container). Die Ursache nennt die Sandbox oder den Namespace. Stellen Sie einen Sandbox-fähigen Container bereit (bevorzugt), oder setzen Sie no_sandbox: true, nachdem Sie /integrations/artisan/security-and-operations/. gelesen haben.
Zeitüberschreitung. Ein großes Dokument hat render_timeout überschritten. Erhöhen Sie die Zeitüberschreitung für diese Last oder verkleinern Sie das Dokument; wägen Sie den Denial-of-Service-Kompromiss auf einem nutzerseitigen Pfad ab.
Fehlende gemeinsam genutzte Bibliotheken. Chrome beendet sich sofort. Installieren Sie den Chrome-Abhängigkeitssatz der Distribution.

`ChromeRenderException` — leere Ausgabe

Chrome printToPDF returned empty data

Chrome ist gestartet, und printToPDF hat null Bytes zurückgegeben. Die übliche Ursache ist eine Eingabe, die keine gerenderte Box erzeugt (leerer Body, gesamter Inhalt display:none), oder ein Chrome-Absturz während des Druckvorgangs. Stellen Sie sicher, dass das HTML zu einer sichtbaren Box rendert. Prüfen Sie den Speicherdruck des Hosts.

`RuntimeException` — Eingabe vor Chrome abgewiesen

Meldung enthält	Ursache	Behebung
`exceeds maximum allowed size`	HTML über `maxHtmlSize`	Reduzieren Sie die Eingabe oder erhöhen Sie `max_html_size` (vergrößert die Angriffsfläche für Ressourcenerschöpfung)
`oversized base64 data URI`	Inline-base64 ≥ 13 MB	Verkleinern Sie das eingebettete Asset; verweisen Sie auf ein kleineres Bild
`forbidden meta refresh redirect`	`<meta http-equiv="refresh">` vorhanden	Entfernen Sie das Tag; es ist ein SSRF-Navigationsvektor und wird immer abgewiesen

Diese Prüfungen stammen aus ChromeSecurityPolicy::validate() und greifen, bevor Chrome kontaktiert wird. Sie sind daher in Tests schnell und kostengünstig erreichbar.

`PdfParseException`

Page <n> has no content stream

Chrome hat ein PDF erzeugt, aus dem der Parser keine Seite extrahieren konnte. Das ist selten und deutet auf eine fehlerhafte Chrome-Ausgabe oder auf eine Chrome-Version hin, die eine unerwartete Struktur erzeugt. Erfassen Sie die Chrome-Version und die Eingabe. Stellen Sie sicher, dass die Binärdatei ein unterstützter Chrome-/Chromium-Build ist.

Remote-Assets werden leer gerendert

Das ist kein Fehler. Die Brücke blockiert jeden Subressourcen-Abruf (CSP default-src 'none' plus ein CDP-setBlockedURLs('*')-Block). Remote-<img>, Stylesheets, Schriftarten, Skripte und iframes werden nicht geladen. Betten Sie Assets als data:-URIs ein und binden Sie CSS inline über defaultCss oder <style> ein. Siehe das Netzwerkmodell unter /integrations/artisan/security-and-operations/.

Inhalt am unteren Rand abgeschnitten

Das Dokument lief auf eine zweite Chrome-Seite über, und die Brücke hat nur Seite 0 importiert. Entweder war der Auto-Fit-Puffer für ungewöhnlich starken Umbruch zu klein, oder eine explizite Höhe war zu knapp bemessen. Geben Sie eine explizite Höhe an, die auf den Inhalt zugeschnitten ist, oder entfernen Sie die explizite Höhe, um Auto-Fit mit seinem Sicherheitspuffer zu nutzen. Siehe die Höhenbehandlung unter /integrations/artisan/production-usage/.

Latenzspitze alle ~100 Renderings

Das ist zu erwarten. BrowserPool startet Chrome alle 100 Renderings neu, um die Speichernutzung zu begrenzen. Eine Logzeile auf notice-Ebene protokolliert den Neustart mit der Render-Anzahl. Behandeln Sie das in SLOs als bekannte periodische Kosten, nicht als Vorfall. Eine höhere Neustartrate als alle 100 Renderings weist auf schwerere Dokumente als erwartet hin.

Speicher wächst über einen langen Batch

BrowserPool begrenzt das Wachstum durch den Neustart alle 100 Renderings, aber ein sehr langlebiger Worker kann dennoch Speicher akkumulieren. Rufen Sie close() zwischen großen Batches auf, um den Chrome-Prozess früh zu recyceln, und betreiben Sie den Worker unter einem Host-Speicherlimit.

Diagnose-Checkliste

Reproduzieren Sie den Fehler mit einem minimalen, vertrauenswürdigen HTML-Fragment, um die Eingabe von der Umgebung zu isolieren.
Führen Sie chromium --headless --dump-dom about:blank auf dem Host als Worker-Benutzer aus.
Injizieren Sie einen PSR-3-Logger und lesen Sie die info-/notice-Zeilen (Binärpfad, Neustartanzahl).
Bestätigen Sie, dass chrome-php/chrome installiert ist: Es ist installiert, wenn BrowserPool::getBrowser() keine ChromeNotAvailableException auslöst.
Prüfen Sie die vorhergehende Ausnahme auf die zugrunde liegende Chrome-Ursache.

Siehe auch

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