Artisan Chrome 橋接器設定

快速概覽

ChromeRendererConfig 是不可變的 final readonly 值物件，包含五個建構子參數。它是橋接器唯一的組態介面。

API 介面

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

來源：src/Artisan/ChromeRendererConfig.php。

選項

選項	型別	預設值	效果
`chromeBinaryPath`	`?string`	`null`	指向 Chrome/Chromium 執行檔的絕對路徑。若為 `null`，則交由 `chrome-php/chrome` 的自動偵測預設值處理。
`renderTimeout`	`int`	`30`	單次繪製允許的最長秒數。它同時作為 `setHtml` 的內容載入逾時值，以及 CDP 的 `sendSyncDefaultTimeout`（以毫秒傳給 Chrome——`renderTimeout * 1000`）。
`defaultCss`	`string`	`''`	在使用者片段之前注入包裝文件的 CSS。注入前會先移除 `</style>` 序列（防止樣式跳脫攻擊）。
`maxHtmlSize`	`int`	`5_000_000`	HTML 輸入允許的最大長度（以位元組計）。超過此上限的輸入，會在連接 Chrome 之前先拋出例外。
`noSandbox`	`bool`	`false`	設為 `true` 時，Chrome 會在停用作業系統沙箱的狀態下啟動。這是僅供容器環境使用的應急選項，且帶有已載明的安全性代價。

逾時轉換成毫秒的計算，以及 Chrome 確切的啟動旗標，皆由 tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand 與 ::getBrowserCreatesAndReusesInstanceWithExpectedOptions 加以驗證。

從陣列建構

針對 Framework（框架）風格的組態檔，ChromeRendererConfig::fromArray() 會對映 snake-case 陣列：

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

未設定的鍵會沿用建構子的預設值。chrome_binary 只有在值為非空字串時才會套用。來源：ChromeRendererConfig::fromArray()。

固定的 Chrome 啟動旗標

BrowserPool 一律使用下列旗標啟動 Chrome，且不受組態設定影響：

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

再加上 headless: true、keepAlive: true、windowSize: [1200, 800]，以及來自組態的 noSandbox。這些旗標不開放使用者調整；它們是用於加固與提升穩定性的預設值。確切的旗標集合與數量（8 個自訂旗標）由 tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu 加以驗證。

選擇設定值

renderTimeout：設定為高於預期最慢文件所需的時間。逾時會以 ChromeRenderException 的形式呈現。在面向使用者的路徑上設定過長的逾時，會形成阻斷服務攻擊面；請為寬鬆的逾時搭配上游請求預算。針對不受信任輸入的邊界保護與資源耗盡控制，於 /integrations/artisan/security-and-operations/ 一節討論。該頁引用了 OWASP ASVS 與 2025 CWE Top 25。
maxHtmlSize：除非有已知工作負載需要更大值，否則請保留預設值。此上限是抵禦資源耗盡型輸入的第一道防線；調高它會擴大該攻擊面。
defaultCss：用於設定字型與重置樣式。它不是沙箱；它會被串接進包裝文件的 <style> 區塊中，而這是在移除 </style> 之後才發生。
noSandbox：在容器之外請維持 false。關於停用沙箱的確切意涵與限制，請見 /integrations/artisan/security-and-operations/ 一節。

邊界情況與陷阱

ChromeRendererConfig 是 readonly；若要變更某個值，請建構一個新實例。它沒有 setter。
renderTimeout 是以秒為單位的 int；無法表示次秒級的精度。
若某個 defaultCss 值含有 </style>（不分大小寫），這些結尾標籤會在組裝文件前先被移除（由 ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss 加以驗證）。如果你使用範本產生 CSS，請預先將這點納入考量。

安全性注意事項

noSandbox 與 maxHtmlSize 都與安全性相關。它們的威脅情境，以及 Chrome 沙箱能保護什麼、不能保護什麼的明確說明，皆在 /integrations/artisan/security-and-operations/ 一節。本頁說明介面；該頁說明邊界。

另請參閱

安裝指南：/integrations/artisan/install/
快速上手：/integrations/artisan/quickstart/
Chrome 繪製器設定：/integrations/artisan/chrome-renderer-setup/
安全性與維運：/integrations/artisan/security-and-operations/
生產環境使用：/integrations/artisan/production-usage/