Khắc phục sự cố Artisan

Tổng quan nhanh

Mọi lỗi của cầu nối đều xuất hiện dưới dạng một ngoại lệ có kiểu rõ ràng. Hãy đối chiếu ngoại lệ và thông báo với bảng bên dưới. Mỗi hàng trỏ đến kiểm tra trong mã nguồn đã phát sinh lỗi đó, nhờ vậy bạn có thể xử lý nguyên nhân thay vì chỉ xử lý triệu chứng.

Chẩn đoán theo ngoại lệ

`ChromeNotAvailableException`

chrome-php/chrome is not installed. Install it via: composer require chrome-php/chrome:^1.15

Thư viện client Chrome DevTools Protocol (CDP) không có trong autoloader. BrowserPool::getBrowser() phát sinh ngoại lệ này trước khi Chrome khởi chạy. Hãy chạy lệnh cài đặt. Trường hợp này khác với việc thiếu tệp nhị phân: kiểm tra thư viện và kiểm tra tệp nhị phân diễn ra ở các giai đoạn riêng biệt.

`ChromeRenderException` — khởi chạy hoặc hết thời gian chờ

Chrome renderer failed: <cause>

Chrome không khởi động được, hết thời gian chờ hoặc bị treo. Ngoại lệ trước đó chứa nguyên nhân gốc. Hãy kiểm tra các nguyên nhân thường gặp sau:

Không tìm thấy tệp nhị phân / không thể thực thi. Hãy xác minh bằng chromium --headless --dump-dom about:blank. Đặt chrome_binary thành đường dẫn tuyệt đối.
Sandbox không khởi tạo được (trong container). Nguyên nhân đề cập đến sandbox hoặc namespace. Hãy dùng container hỗ trợ sandbox khi có thể, hoặc đặt no_sandbox: true sau khi bạn đọc /integrations/artisan/security-and-operations/.
Hết thời gian chờ. Một tài liệu nặng đã vượt quá render_timeout. Hãy tăng thời gian chờ cho khối lượng công việc đó, hoặc giảm độ phức tạp của tài liệu. Trên một luồng hướng đến người dùng, hãy cân nhắc đánh đổi với nguy cơ từ chối dịch vụ.
Thiếu thư viện dùng chung. Chrome thoát ngay lập tức. Hãy cài đặt các phụ thuộc của Chrome cho bản phân phối của bạn.

`ChromeRenderException` — đầu ra rỗng

Chrome printToPDF returned empty data

Chrome đã khởi động, nhưng printToPDF trả về không byte nào. Nguyên nhân thường gặp là đầu vào không tạo ra khung hiển thị nào, chẳng hạn body rỗng hoặc nội dung được đặt là display:none, hoặc Chrome bị treo trong lúc in. Hãy xác nhận rằng đầu vào Hypertext Markup Language (HTML) kết xuất được một khung hiển thị. Hãy kiểm tra áp lực bộ nhớ trên máy chủ.

`RuntimeException` — đầu vào bị từ chối trước Chrome

Thông báo chứa	Nguyên nhân	Cách khắc phục
`exceeds maximum allowed size`	HTML vượt quá `maxHtmlSize`	Giảm đầu vào hoặc tăng `max_html_size` (mở rộng bề mặt cạn kiệt tài nguyên)
`oversized base64 data URI`	Data Uniform Resource Identifier (URI) base64 nội tuyến ≥ 13 MB	Thu nhỏ tài nguyên được nhúng; tham chiếu một hình ảnh nhỏ hơn
`forbidden meta refresh redirect`	`<meta http-equiv="refresh">` xuất hiện	Xóa thẻ này; đây là một vector điều hướng server-side request forgery (SSRF) và luôn bị từ chối

Các lỗi này đến từ ChromeSecurityPolicy::validate() và phát sinh trước khi liên hệ với Chrome, nên việc bao phủ chúng trong kiểm thử diễn ra nhanh và ít tốn kém.

`PdfParseException`

Page <n> has no content stream

Chrome đã tạo ra một tệp Portable Document Format (PDF) mà bộ phân tích không trích xuất được trang nào. Trường hợp này hiếm gặp và thường cho thấy đầu ra Chrome bị lỗi định dạng, hoặc phiên bản Chrome có cấu trúc không như dự kiến. Hãy ghi lại phiên bản Chrome và đầu vào. Hãy xác minh rằng tệp nhị phân là một bản dựng Chrome/Chromium được hỗ trợ.

Tài nguyên từ xa hiển thị trống

Đây không phải là lỗi. Cầu nối chặn mọi lượt tải tài nguyên con bằng Content Security Policy (CSP) default-src 'none' và lệnh chặn CDP setBlockedURLs('*'). <img>, stylesheet, phông chữ, script và iframe từ xa đều không tải. Hãy nhúng tài nguyên dưới dạng URI data:, và nhúng Cascading Style Sheets (CSS) qua defaultCss hoặc <style>. Xem mô hình mạng tại /integrations/artisan/security-and-operations/.

Nội dung bị cắt ở phía dưới

Tài liệu tràn sang trang Chrome thứ hai, còn cầu nối chỉ nhập trang 0. Có thể vùng đệm tự động vừa khít quá nhỏ cho phần reflow cao bất thường, hoặc chiều cao chỉ định tường minh quá nhỏ. Hãy đặt chiều cao tường minh vừa với nội dung, hoặc bỏ chiều cao tường minh để dùng chế độ tự động vừa khít cùng vùng đệm an toàn của chế độ đó. Xem cách xử lý chiều cao tại /integrations/artisan/production-usage/.

Độ trễ tăng vọt sau mỗi ~100 lần kết xuất

Đây là điều bình thường. BrowserPool khởi động lại Chrome sau mỗi 100 lần kết xuất để giới hạn bộ nhớ. Một dòng nhật ký ở mức notice ghi lại lần khởi động lại và số lần kết xuất. Hãy xem đây là chi phí định kỳ đã biết trong các mục tiêu mức dịch vụ (SLO), không phải sự cố. Tần suất khởi động lại cao hơn mức mỗi 100 lần kết xuất có nghĩa là tài liệu nặng hơn dự kiến.

Bộ nhớ tăng dần trong một lô dài

BrowserPool giới hạn mức tăng bằng cách khởi động lại sau 100 lần kết xuất, nhưng một worker chạy rất lâu vẫn có thể tích lũy bộ nhớ. Hãy gọi close() giữa các lô lớn để tái sử dụng Chrome sớm, và chạy worker dưới một giới hạn bộ nhớ của máy chủ.

Danh sách kiểm tra chẩn đoán

Hãy tái hiện bằng một đoạn HTML tối thiểu, ổn định để tách vấn đề đầu vào khỏi vấn đề môi trường.
Hãy chạy chromium --headless --dump-dom about:blank trên máy chủ với tư cách người dùng worker.
Hãy chèn một logger PHP Standards Recommendation 3 (PSR-3) và đọc các dòng info/notice, bao gồm đường dẫn tệp nhị phân và số lần khởi động lại.
Hãy xác nhận đã cài đặt chrome-php/chrome: BrowserPool::getBrowser() sẽ không ném ChromeNotAvailableException khi nó khả dụng.
Hãy kiểm tra ngoại lệ trước đó của ngoại lệ này để tìm nguyên nhân Chrome bên dưới.

Xem thêm

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