การกำหนดค่าบริดจ์ Artisan Chrome

ภาพรวมโดยย่อ

ChromeRendererConfig เป็น value object แบบ 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 และ sendSyncDefaultTimeout ของ Chrome DevTools Protocol (CDP) (ส่งให้ Chrome เป็นมิลลิวินาที — renderTimeout * 1000)
defaultCss	string	''	Cascading Style Sheets (CSS) ที่แทรกเข้าไปในเอกสารที่ห่อไว้ก่อนส่วนเนื้อหาของผู้ใช้ ลำดับ </style> จะถูกตัดออกก่อนแทรก (เพื่อป้องกันการหลุดออกจากบล็อก style)
maxHtmlSize	int	5_000_000	ความยาวสูงสุดของอินพุต Hypertext Markup Language (HTML) เป็นไบต์ อินพุตที่เกินค่านี้จะโยนข้อยกเว้นก่อนติดต่อ Chrome
noSandbox	bool	false	เมื่อเป็น true Chrome จะเริ่มทำงานโดยปิดใช้งานแซนด์บ็อกซ์ของระบบปฏิบัติการ (OS) เป็นทางออกฉุกเฉินสำหรับใช้ในคอนเทนเนอร์เท่านั้น พร้อมต้นทุนด้านความปลอดภัยที่ระบุไว้ในเอกสาร

การทดสอบยืนยันการแปลงไทม์เอาต์เป็นมิลลิวินาที และยืนยันแฟล็กสำหรับเปิด 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/ กล่าวถึงการป้องกันขอบเขตและการควบคุมไม่ให้ทรัพยากรถูกใช้จนหมดสำหรับอินพุตที่ไม่น่าเชื่อถือ หน้าดังกล่าวอ้างอิง Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) และ Common Weakness Enumeration (CWE) Top 25 ปี 2025
• maxHtmlSize — คงค่าเริ่มต้นไว้ เว้นแต่ภาระงานที่ทราบแน่ชัดว่าต้องใช้มากกว่านั้น ขีดจำกัดนี้เป็นแนวป้องกันด่านแรกต่ออินพุตที่ทำให้ทรัพยากรถูกใช้จนหมด การเพิ่มค่านี้จะขยายพื้นผิวดังกล่าว
• defaultCss — ใช้สำหรับฟอนต์และการรีเซ็ต ค่านี้ไม่ใช่แซนด์บ็อกซ์ และจะถูกต่อเข้าไปในบล็อก <style> ของเอกสารที่ห่อไว้หลังจากตัด </style> ออกแล้ว
• noSandbox — คงไว้เป็น false เมื่อใช้งานนอกคอนเทนเนอร์ ดู /integrations/artisan/security-and-operations/ สำหรับความหมายที่แม่นยำและข้อจำกัดของการปิดใช้งาน

กรณีขอบและข้อควรระวัง

• ChromeRendererConfig เป็น readonly หากต้องการเปลี่ยนค่า ให้สร้างอินสแตนซ์ใหม่ ไม่มีเซตเตอร์
• renderTimeout เป็น int หน่วยเป็นวินาที จึงไม่สามารถแสดงความละเอียดในระดับต่ำกว่าวินาทีได้
• หากค่า defaultCss มี </style> (ไม่ว่าตัวพิมพ์ใด) แท็กปิดเหล่านั้นจะถูกนำออกก่อนประกอบเอกสาร (ยืนยันโดย ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss) หากสร้าง CSS จากเทมเพลต ควรวางแผนรองรับพฤติกรรมนี้

หมายเหตุด้านความปลอดภัย

noSandbox และ maxHtmlSize เกี่ยวข้องกับความปลอดภัย หน้า /integrations/artisan/security-and-operations/ ครอบคลุมบริบทภัยคุกคามของค่าเหล่านี้ และระบุอย่างชัดเจนว่าแซนด์บ็อกซ์ของ Chrome ป้องกันอะไรและไม่ป้องกันอะไร หน้านี้อธิบายพื้นผิว ส่วนหน้าดังกล่าวอธิบายขอบเขต

ดูเพิ่มเติม

• การติดตั้ง (/integrations/artisan/install/)
• เริ่มต้นใช้งาน (/integrations/artisan/quickstart/)
• การตั้งค่าเรนเดอร์เรอร์ Chrome (/integrations/artisan/chrome-renderer-setup/)
• ความปลอดภัยและการดำเนินงาน (/integrations/artisan/security-and-operations/)
• การใช้งานจริง (/integrations/artisan/production-usage/)