Konfiguracja mostka Chrome w Artisan

W skrócie

ChromeRendererConfig to niezmienny obiekt wartości final readonly z pięcioma parametrami konstruktora. Używaj go jako jedynej powierzchni konfiguracyjnej mostka.

Interfejs API

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

Źródło: src/Artisan/ChromeRendererConfig.php.

Opcje

Opcja	Typ	Wartość domyślna	Działanie
chromeBinaryPath	?string	null	Ścieżka bezwzględna do pliku wykonywalnego Chrome/Chromium. Przy wartości null używane jest domyślne automatyczne wykrywanie w chrome-php/chrome.
renderTimeout	int	30	Maksymalny czas, w sekundach, przeznaczony na pojedyncze renderowanie. Stosowany zarówno jako limit czasu ładowania treści w setHtml, jak i jako parametr sendSyncDefaultTimeout protokołu Chrome DevTools Protocol (CDP) (przekazywany do Chrome w milisekundach — renderTimeout * 1000).
defaultCss	string	''	Arkusze CSS wstrzykiwane do opakowanego dokumentu przed fragmentem użytkownika. Sekwencje </style> są usuwane przed wstrzyknięciem (ochrona przed wyjściem z bloku stylów).
maxHtmlSize	int	5_000_000	Maksymalna długość danych wejściowych Hypertext Markup Language (HTML) w bajtach. Dane wejściowe przekraczające tę wartość powodują zgłoszenie wyjątku, zanim nastąpi kontakt z Chrome.
noSandbox	bool	false	Gdy ma wartość true, uruchamia Chrome z wyłączoną piaskownicą systemu operacyjnego (OS). Awaryjne obejście przeznaczone wyłącznie do kontenerów, z udokumentowanym kosztem bezpieczeństwa.

Testy sprawdzają konwersję limitu czasu na milisekundy oraz dokładne flagi uruchomieniowe Chrome w tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand oraz ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Tworzenie z tablicy

Użyj ChromeRendererConfig::fromArray(), aby zmapować tablicę w notacji snake-case z plików konfiguracyjnych typowych dla frameworków:

$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,
]);

Nieustawione klucze przyjmują wartości domyślne konstruktora. Klucz chrome_binary jest używany tylko wtedy, gdy jego wartość jest niepustym ciągiem znaków. Źródło: ChromeRendererConfig::fromArray().

Stałe flagi uruchomieniowe Chrome

BrowserPool zawsze uruchamia Chrome z następującymi flagami, niezależnie od konfiguracji:

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

oraz headless: true, keepAlive: true, windowSize: [1200, 800] i noSandbox z konfiguracji. Wartości tych nie można dostosowywać; służą jako domyślne ustawienia wzmacniające bezpieczeństwo i stabilność. Test sprawdza dokładny zestaw i liczbę (8 niestandardowych flag) w tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Dobór wartości

• renderTimeout — ustaw wartość wyższą niż czas potrzebny na najwolniejszy spodziewany dokument. Przekroczenie limitu czasu skutkuje ChromeRenderException. Długie limity czasu na ścieżkach dostępnych dla użytkowników zwiększają powierzchnię ataku typu odmowa usługi; połącz wysoki limit czasu z nadrzędnym budżetem żądań. Strona /integrations/artisan/security-and-operations/ omawia zabezpieczenia granic oraz mechanizmy kontroli wyczerpania zasobów dla niezaufanych danych wejściowych. Tamta strona przywołuje Application Security Verification Standard (ASVS) projektu Open Worldwide Application Security Project (OWASP) oraz zestawienie Common Weakness Enumeration (CWE) Top 25 z 2025 roku.
• maxHtmlSize — pozostaw wartość domyślną, chyba że znane obciążenie wymaga więcej. Limit ten jest pierwszą linią obrony przed danymi wejściowymi wyczerpującymi zasoby; jego podniesienie powiększa tę powierzchnię ataku.
• defaultCss — używaj tej opcji do czcionek i resetów stylów. Wartość ta nie działa jak piaskownica; zostaje dołączona do bloku <style> opakowanego dokumentu po usunięciu </style>.
• noSandbox — poza kontenerami pozostaw wartość false. Dokładne znaczenie i ograniczenia wyłączenia piaskownicy opisano na stronie /integrations/artisan/security-and-operations/.

Przypadki brzegowe i pułapki

• ChromeRendererConfig jest oznaczony jako readonly; aby zmienić wartość, utwórz nowy egzemplarz. Nie istnieje metoda ustawiająca.
• renderTimeout jest wartością typu int wyrażoną w sekundach; nie obsługuje precyzji poniżej sekundy.
• Jeśli wartość defaultCss zawiera </style> (niezależnie od wielkości liter), te tagi zamykające są usuwane przed złożeniem dokumentu (co sprawdza ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Uwzględnij to, jeśli generujesz CSS z szablonów.

Uwagi dotyczące bezpieczeństwa

noSandbox i maxHtmlSize mają znaczenie dla bezpieczeństwa. Strona /integrations/artisan/security-and-operations/ omawia ich kontekst zagrożeń oraz wyraźnie określa, przed czym piaskownica Chrome chroni, a przed czym nie. Ta strona dokumentuje interfejs; tamta strona dokumentuje granicę bezpieczeństwa.

Zobacz także

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