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 验证。

从数组构造

对于框架风格的配置文件，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。关于禁用 Chrome 沙箱的确切含义与限制，请见 /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/