Pemecahan masalah Artisan

Sekilas pandang

Setiap kegagalan bridge muncul sebagai exception bertipe tertentu. Cocokkan exception dan pesannya dengan tabel di bawah ini. Setiap baris mengarah ke pemeriksaan sumber yang memicunya, sehingga Anda dapat memperbaiki penyebabnya, bukan sekadar gejalanya.

Diagnosis berdasarkan exception

`ChromeNotAvailableException`

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

Pustaka klien Chrome DevTools Protocol (CDP) tidak tersedia di autoloader. BrowserPool::getBrowser() memicu exception ini sebelum Chrome diluncurkan. Jalankan perintah pemasangan tersebut. Ini berbeda dari binary yang hilang: pemeriksaan pustaka dan pemeriksaan binary berjalan pada tahap yang terpisah.

`ChromeRenderException` — peluncuran atau timeout

Chrome renderer failed: <cause>

Chrome tidak dapat dimulai, mengalami timeout, atau crash. Exception sebelumnya berisi penyebab aslinya. Periksa penyebab umum berikut:

Binary tidak ditemukan / tidak dapat dieksekusi. Verifikasi dengan chromium --headless --dump-dom about:blank. Atur chrome_binary ke jalur absolutnya.
Sandbox tidak dapat diinisialisasi (kontainer). Penyebabnya menyebutkan sandbox atau namespace. Gunakan kontainer yang mendukung sandbox jika memungkinkan, atau atur no_sandbox: true setelah Anda membaca /integrations/artisan/security-and-operations/.
Timeout. Dokumen yang berat melampaui render_timeout. Naikkan timeout untuk beban kerja tersebut, atau kurangi ukuran dokumen. Pada jalur yang langsung diakses pengguna, pertimbangkan trade-off denial-of-service.
Pustaka bersama yang hilang. Chrome langsung berhenti. Pasang kumpulan dependensi Chrome untuk distribusi Anda.

`ChromeRenderException` — keluaran kosong

Chrome printToPDF returned empty data

Chrome berhasil dimulai, tetapi printToPDF mengembalikan nol byte. Penyebab umum adalah input yang tidak menghasilkan kotak yang dirender, seperti body kosong atau konten yang diatur ke display:none, atau Chrome yang crash saat mencetak. Pastikan input Hypertext Markup Language (HTML) dirender menjadi kotak yang terlihat. Periksa juga tekanan memori host.

`RuntimeException` — input ditolak sebelum Chrome

Pesan berisi	Penyebab	Perbaikan
`exceeds maximum allowed size`	HTML melampaui `maxHtmlSize`	Kurangi input atau naikkan `max_html_size` (memperluas permukaan resource-exhaustion)
`oversized base64 data URI`	Data Uniform Resource Identifier (URI) base64 sebaris ≥ 13 MB	Perkecil aset yang disematkan; rujuk gambar yang lebih kecil
`forbidden meta refresh redirect`	`<meta http-equiv="refresh">` ada	Hapus tag tersebut; ini adalah vektor navigasi server-side request forgery (SSRF) dan selalu ditolak

Kesalahan ini berasal dari ChromeSecurityPolicy::validate() dan dipicu sebelum Chrome dihubungi, sehingga cepat dan murah untuk dicakup oleh pengujian.

`PdfParseException`

Page <n> has no content stream

Chrome menghasilkan berkas Portable Document Format (PDF) yang halamannya tidak dapat diekstrak oleh parser. Kasus ini jarang terjadi dan biasanya menunjukkan keluaran Chrome yang rusak atau versi Chrome dengan struktur yang tidak terduga. Catat versi Chrome dan inputnya. Verifikasi bahwa binary tersebut merupakan build Chrome/Chromium yang didukung.

Aset jarak jauh tampil kosong

Ini bukan bug. Bridge memblokir semua pengambilan subresource dengan Content Security Policy (CSP) default-src 'none' dan pemblokiran CDP setBlockedURLs('*'). <img>, stylesheet, font, skrip, dan iframe jarak jauh tidak dimuat. Sematkan aset sebagai URI data:, dan sematkan Cascading Style Sheets (CSS) melalui defaultCss atau <style>. Lihat model jaringan di /integrations/artisan/security-and-operations/.

Konten terpotong di bagian bawah

Dokumen meluap ke halaman Chrome kedua, sementara bridge hanya mengimpor halaman 0. Penyebabnya bisa berupa buffer auto-fit yang terlalu kecil untuk reflow yang sangat tinggi, atau tinggi eksplisit yang ditetapkan terlalu kecil. Tetapkan tinggi eksplisit yang sesuai dengan ukuran konten, atau hapus tinggi eksplisit untuk menggunakan auto-fit dengan buffer pengamannya. Lihat penanganan tinggi di /integrations/artisan/production-usage/.

Lonjakan latensi setiap ~100 render

Ini sesuai harapan. BrowserPool memulai ulang Chrome setiap 100 render untuk membatasi memori. Sebuah baris log setingkat notice mencatat proses memulai ulang dan jumlah render. Anggap hal ini sebagai biaya periodik yang sudah diketahui dalam service-level objective (SLO), bukan sebuah insiden. Jika proses memulai ulang terjadi lebih sering daripada setiap 100 render, berarti dokumennya lebih berat daripada perkiraan.

Memori tumbuh selama batch yang panjang

BrowserPool membatasi pertumbuhan dengan memulai ulang Chrome setiap 100 render, tetapi worker yang berjalan sangat lama masih dapat mengakumulasi memori. Panggil close() di antara batch besar untuk mendaur ulang Chrome lebih awal, dan jalankan worker dengan batas memori host.

Daftar periksa diagnostik

Reproduksi masalah dengan fragmen HTML tepercaya yang minimal untuk memisahkan masalah input dari masalah lingkungan.
Jalankan chromium --headless --dump-dom about:blank pada host sebagai pengguna worker.
Injeksikan logger PHP Standards Recommendation 3 (PSR-3) dan baca baris info/notice, termasuk jalur binary dan jumlah proses memulai ulang.
Pastikan chrome-php/chrome terpasang: BrowserPool::getBrowser() tidak akan melemparkan ChromeNotAvailableException ketika tersedia.
Periksa exception sebelumnya pada exception tersebut untuk menemukan penyebab Chrome yang mendasarinya.

Lihat juga

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