ضبط جسر Chrome في Artisan

لمحة سريعة

يمثّل 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 ومهلة sendSyncDefaultTimeout في بروتوكول ⁨Chrome DevTools⁩‏ (⁨CDP⁩) (تُمرَّر إلى ⁨Chrome⁩ بالميلي ثانية — renderTimeout * 1000).
defaultCss	string	''	صفحات الأنماط المتراصة (⁨CSS⁩) التي تُحقَن في المستند المُغلَّف قبل جزء المستخدم. تُزال تسلسلات </style> قبل الحقن (دفاعًا ضد الخروج من كتلة الأنماط).
maxHtmlSize	int	5_000_000	الحد الأقصى لطول مُدخَل لغة ترميز النص التشعبي (⁨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/⁩ حماية الحدود وضوابط استنزاف الموارد للمُدخَلات غير الموثوقة. تستشهد تلك الصفحة بمعيار التحقق من أمان التطبيقات (⁨ASVS⁩) الصادر عن المشروع العالمي المفتوح لأمان التطبيقات (⁨OWASP⁩) وبقائمة أبرز 25 من تعداد نقاط الضعف الشائعة (⁨CWE⁩) لعام 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/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/security-and-operations/
• /integrations/artisan/production-usage/