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`이면 OS 샌드박스를 비활성화한 상태로 Chrome을 실행합니다. 문서화된 보안 비용을 수반하는 컨테이너 전용 비상 우회 수단입니다.

타임아웃이 밀리초로 변환되는 방식과 정확한 Chrome 실행 플래그는 tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand 및 ::getBrowserCreatesAndReusesInstanceWithExpectedOptions에 의해 검증됩니다.

배열로부터 생성하기

프레임워크 방식의 구성 파일에서는 ChromeRendererConfig::fromArray()가 스네이크 케이스 배열을 매핑합니다.

$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입니다. 값을 변경하려면 새 인스턴스를 생성하십시오. 세터는 없습니다.
renderTimeout은 초 단위 int입니다. 1초 미만의 정밀도는 표현할 수 없습니다.
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/