Konfigurasi jembatan Chrome Artisan

Sekilas

ChromeRendererConfig adalah objek nilai yang immutable dan final readonly, dengan lima parameter konstruktor. Gunakan objek ini sebagai satu-satunya antarmuka konfigurasi untuk jembatan tersebut.

Permukaan API

new ChromeRendererConfig(
    ?string $chromeBinaryPath = null,
    int     $renderTimeout    = 30,
    string  $defaultCss       = '',
    int     $maxHtmlSize      = 5_000_000,
    bool    $noSandbox        = false,
);

Sumber: src/Artisan/ChromeRendererConfig.php.

Opsi

Opsi	Tipe	Standar	Efek
chromeBinaryPath	?string	null	Jalur absolut ke biner Chrome/Chromium. null menggunakan nilai standar hasil deteksi otomatis dari chrome-php/chrome.
renderTimeout	int	30	Jumlah detik maksimum untuk satu kali render. Digunakan sebagai batas waktu pemuatan konten setHtml dan sendSyncDefaultTimeout Chrome DevTools Protocol (CDP) (diteruskan ke Chrome dalam milidetik — renderTimeout * 1000).
defaultCss	string	''	Cascading Style Sheets (CSS) yang disuntikkan ke dalam dokumen pembungkus sebelum fragmen pengguna. Urutan </style> dihapus sebelum penyuntikan (pertahanan terhadap style-break-out).
maxHtmlSize	int	5_000_000	Panjang masukan Hypertext Markup Language (HTML) maksimum dalam byte. Masukan yang melebihi batas ini akan memicu pengecualian sebelum Chrome dihubungi.
noSandbox	bool	false	Jika true, menjalankan Chrome dengan sandbox sistem operasi (OS)-nya dinonaktifkan. Jalur pengecualian khusus untuk kontainer, dengan biaya keamanan yang terdokumentasi.

Pengujian memastikan konversi batas waktu ke milidetik dan flag peluncuran Chrome yang tepat di tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand dan ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Membuat dari larik

Gunakan ChromeRendererConfig::fromArray() untuk memetakan larik bergaya snake-case dalam berkas konfigurasi bergaya framework:

$config = ChromeRendererConfig::fromArray([
    'chrome_binary'  => '/usr/bin/chromium',
    'render_timeout' => 45,
    'default_css'    => 'body { font-family: "Noto Sans TC", sans-serif; }',
    'max_html_size'  => 2_000_000,
    'no_sandbox'     => false,
]);

Kunci yang tidak disetel akan menggunakan nilai standar konstruktor. Kunci chrome_binary hanya berlaku jika nilainya berupa string yang tidak kosong. Sumber: ChromeRendererConfig::fromArray().

Flag peluncuran Chrome tetap

BrowserPool selalu menjalankan Chrome dengan flag berikut, terlepas dari konfigurasi:

--disable-gpu
--disable-dev-shm-usage
--disable-extensions
--disable-background-networking
--disable-translate
--disable-remote-fonts
--disable-domain-reliability
--no-first-run

ditambah dengan headless: true, keepAlive: true, windowSize: [1200, 800], dan noSandbox dari konfigurasi. Nilai-nilai ini tidak dapat disetel oleh pengguna; semuanya berfungsi sebagai nilai standar untuk pengerasan dan stabilitas. Sebuah pengujian memastikan kumpulan dan jumlah yang tepat (8 flag kustom) di tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Memilih nilai

• renderTimeout — setel lebih tinggi daripada waktu yang diperkirakan untuk dokumen paling lambat. Batas waktu yang terlampaui muncul sebagai ChromeRenderException. Batas waktu yang panjang pada jalur yang berhadapan dengan pengguna menciptakan permukaan denial-of-service; pasangkan batas waktu yang longgar dengan anggaran permintaan di hulu. Halaman /integrations/artisan/security-and-operations/ membahas perlindungan batas dan kontrol pengurasan sumber daya untuk masukan yang tidak tepercaya. Halaman tersebut mengutip Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) dan Common Weakness Enumeration (CWE) Top 25 tahun 2025.
• maxHtmlSize — pertahankan nilai standar kecuali jika beban kerja yang diketahui memerlukan lebih banyak. Batas ini adalah garis pertahanan pertama terhadap masukan yang menguras sumber daya; menaikkannya akan memperluas permukaan tersebut.
• defaultCss — gunakan untuk fon dan reset. Nilai ini bukan sandbox; nilainya digabungkan ke dalam blok <style> dokumen pembungkus setelah penghapusan </style>.
• noSandbox — biarkan tetap false di luar kontainer. Lihat /integrations/artisan/security-and-operations/ untuk memahami makna dan batasan yang tepat saat menonaktifkannya.

Kasus tepi & jebakan

• ChromeRendererConfig bersifat readonly; buat instance baru untuk mengubah suatu nilai. Tidak ada setter.
• renderTimeout adalah int dalam satuan detik; presisi di bawah satu detik tidak dapat direpresentasikan.
• Jika nilai defaultCss mengandung </style> (dengan huruf besar/kecil apa pun), tag penutup tersebut dihapus sebelum dokumen dirakit (dipastikan oleh ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Pertimbangkan hal ini saat Anda membuat templat CSS.

Catatan keamanan

noSandbox dan maxHtmlSize berkaitan dengan keamanan. Halaman /integrations/artisan/security-and-operations/ membahas konteks ancamannya dan menyatakan secara eksplisit apa yang dilindungi dan tidak dilindungi oleh sandbox Chrome. Halaman ini mendokumentasikan permukaan konfigurasinya; halaman tersebut mendokumentasikan batasnya.

Lihat juga

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