Cấu hình cầu nối Chrome cho Artisan

Tổng quan nhanh

ChromeRendererConfig là một value object bất biến, final readonly, có năm tham số trong hàm khởi tạo. Hãy dùng nó làm điểm cấu hình duy nhất cho cầu nối.

Bề mặt API

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

Nguồn: src/Artisan/ChromeRendererConfig.php.

Tùy chọn

Tùy chọn	Kiểu	Mặc định	Tác dụng
chromeBinaryPath	?string	null	Đường dẫn tuyệt đối đến tệp nhị phân Chrome/Chromium. null sẽ dùng cơ chế tự động phát hiện mặc định của chrome-php/chrome.
renderTimeout	int	30	Số giây tối đa cho một lần kết xuất. Giá trị này vừa được dùng làm thời gian chờ khi tải nội dung của setHtml, vừa làm sendSyncDefaultTimeout của Chrome DevTools Protocol (CDP) (truyền cho Chrome theo mili giây — renderTimeout * 1000).
defaultCss	string	''	Cascading Style Sheets (CSS) được chèn vào tài liệu bao bọc trước phần nội dung của người dùng. Mọi chuỗi </style> đều bị loại bỏ trước khi chèn (biện pháp phòng vệ chống thoát khỏi khối style).
maxHtmlSize	int	5_000_000	Độ dài đầu vào Hypertext Markup Language (HTML) tối đa, tính bằng byte. Đầu vào vượt quá giới hạn này sẽ phát sinh ngoại lệ trước khi liên hệ với Chrome.
noSandbox	bool	false	Khi true, Chrome sẽ khởi chạy với hộp cát của hệ điều hành (OS) bị tắt. Đây là lối thoát chỉ dành cho container, cùng đánh đổi bảo mật đã được ghi rõ.

Các bài kiểm thử xác nhận phép chuyển đổi thời gian chờ sang mili giây và độ chính xác của các cờ khởi chạy Chrome trong tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand và ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Khởi tạo từ một mảng

Dùng ChromeRendererConfig::fromArray() để ánh xạ một mảng dạng snake-case trong các tệp cấu hình theo kiểu 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,
]);

Các khóa không được đặt sẽ dùng giá trị mặc định của hàm khởi tạo. Khóa chrome_binary chỉ được áp dụng khi giá trị của khóa là một chuỗi không rỗng. Nguồn: ChromeRendererConfig::fromArray().

Các cờ khởi chạy Chrome cố định

BrowserPool luôn khởi chạy Chrome với các cờ này, bất kể cấu hình như thế nào:

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

Ngoài ra còn có headless: true, keepAlive: true, windowSize: [1200, 800], và noSandbox lấy từ cấu hình. Người dùng không thể tinh chỉnh các giá trị này; đây là các giá trị mặc định nhằm tăng cường bảo mật và độ ổn định. Một bài kiểm thử xác nhận đúng tập hợp lẫn số lượng (8 cờ tùy chỉnh) trong tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Chọn giá trị

• renderTimeout — đặt cao hơn thời gian kết xuất của tài liệu chậm nhất mà bạn dự kiến. Một lần quá thời gian chờ sẽ được báo dưới dạng ChromeRenderException. Thời gian chờ dài trên các đường xử lý phục vụ người dùng sẽ tạo ra bề mặt tấn công từ chối dịch vụ; hãy kết hợp thời gian chờ rộng rãi với hạn mức yêu cầu ở tầng trên. Trang /integrations/artisan/security-and-operations/ bàn về cách bảo vệ ranh giới và các biện pháp kiểm soát tình trạng cạn kiệt tài nguyên đối với đầu vào không đáng tin cậy. Trang đó trích dẫn Application Security Verification Standard (ASVS) của Open Worldwide Application Security Project (OWASP) và Common Weakness Enumeration (CWE) Top 25 năm 2025.
• maxHtmlSize — giữ giá trị mặc định, trừ khi một khối lượng công việc đã biết cần nhiều hơn. Giới hạn này là tuyến phòng thủ đầu tiên chống lại đầu vào gây cạn kiệt tài nguyên; nâng nó lên sẽ mở rộng bề mặt tấn công đó.
• defaultCss — dùng cho phông chữ và reset kiểu. Giá trị này không phải là hộp cát; nó được nối vào khối <style> của tài liệu bao bọc sau khi loại bỏ </style>.
• noSandbox — giữ ở false khi chạy ngoài container. Xem /integrations/artisan/security-and-operations/ để biết ý nghĩa chính xác và các giới hạn của việc tắt sandbox.

Trường hợp đặc biệt & điểm cần lưu ý

• ChromeRendererConfig là readonly; hãy tạo thực thể mới để thay đổi một giá trị. Không có setter.
• renderTimeout là một int tính bằng giây; không biểu diễn được độ chính xác dưới một giây.
• Nếu một giá trị defaultCss chứa </style> (bất kể chữ hoa/thường), các thẻ đóng đó sẽ bị loại bỏ trước khi tài liệu được lắp ráp (được xác nhận bởi ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Hãy tính đến điều này nếu bạn tạo template CSS.

Lưu ý về bảo mật

noSandbox và maxHtmlSize có liên quan đến bảo mật. Trang /integrations/artisan/security-and-operations/ trình bày bối cảnh đe dọa liên quan đến chúng và nêu rõ hộp cát Chrome bảo vệ những gì, cũng như không bảo vệ những gì. Trang này ghi lại bề mặt; trang đó ghi lại các ranh giới.

Xem thêm

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