Hướng dẫn

Tổng quan nhanh

Phần Hướng dẫn giúp bạn kết nối NextPDF với môi trường chạy mã của mình. Tab này bắt đầu bằng danh sách kiểm tra vận hành production, rồi trình bày năm nhóm theo thứ tự áp dụng: tích hợp framework và bộ kết xuất, server NextPDF Connect, Python SDK, cách viết tiện ích mở rộng cho engine và khắc phục sự cố. Mỗi mục bên dưới bắt đầu bằng một trang trung tâm, rồi liệt kê những trang bạn sẽ dùng thường xuyên nhất.

Để có các công thức theo từng tác vụ có thể sao chép, hãy dùng Cookbook. Để xem các bề mặt Application Programming Interface (API) đã được kiểm chứng và ma trận hỗ trợ, hãy dùng Tài liệu tham khảo.

Tích hợp

Tám gói này kết nối engine lõi với các framework, bộ kết xuất trình duyệt, dịch vụ edge, công cụ build và các lộ trình di chuyển từ hệ thống cũ. Mỗi mục dành cho một gói đều theo cùng một cấu trúc hướng dẫn thống nhất — tổng quan, cài đặt, bắt đầu nhanh, cấu hình, API, hướng dẫn cho nhà phát triển, sử dụng trong môi trường production, bảo mật và khắc phục sự cố — vì vậy sau khi đã nắm được một gói, bạn có thể đọc các phần còn lại dễ dàng.

Trang	Dùng cho
Tích hợp	Bản đồ các tiện ích mở rộng và hướng dẫn lựa chọn. Hãy đọc trang này trước để chọn gói phù hợp.
Chỉ mục API cho tích hợp	Chỉ mục cho biết trang API của tiện ích mở rộng nào bao phủ từng bề mặt framework, bộ kết xuất, transport và công cụ build.
NextPDF cho Laravel	Bộ chuyển đổi cho framework Laravel.
NextPDF cho Symfony	Bộ chuyển đổi cho framework Symfony.
NextPDF cho CodeIgniter	Bộ chuyển đổi cho framework CodeIgniter.
NextPDF Artisan	Cầu nối đến bộ kết xuất Chrome để kết xuất HTML với chất lượng trình duyệt.
NextPDF Cloudflare	Lộ trình triển khai tại edge trên Cloudflare.
NextPDF Gotenberg	Cầu nối đến bộ kết xuất Gotenberg.
Khả năng tương thích với TCPDF	Lớp tương thích cho các codebase đang chuyển khỏi TCPDF.
NextPDF Backport Builder	Công cụ build nhắm tới các runtime PHP cũ hơn.

NextPDF Connect

Gói nextpdf/server chạy engine dưới dạng một dịch vụ hoạt động lâu dài: một registry công cụ có tính tất định, được cung cấp qua Model Context Protocol (MCP), Representational State Transfer (REST) và gRPC, đặt sau một cổng phê duyệt có con người tham gia dành cho các công cụ rủi ro cao.

Trang	Dùng cho
NextPDF Connect	Trang trung tâm của mục: khái niệm, cấu hình và vận hành server.
Tổng quan về Connect	Ranh giới của gói và ba transport.
Bắt đầu nhanh với Connect	Lần bắt tay MCP đầu tiên có thể chạy được, cùng yêu cầu kết xuất REST tương ứng.
Cấu hình NextPDF Connect	Tệp YAML cho MCP và các biến môi trường `NEXTPDF_*`.
Tài liệu tham chiếu API NextPDF Connect	Tất cả công cụ đã đăng ký, ký hiệu gRPC, mục mô hình lỗi và giới hạn tần suất.
Triển khai NextPDF Connect	Các profile worker RoadRunner, Docker và kho lưu trữ dùng Redis.
Bảo mật và vận hành Connect	Xác thực, bảo mật transport và mô hình mối đe dọa.

Mỗi transport đều có trang tham chiếu riêng.

Trang	Dùng cho
Transport MCP	Khung JSON-RPC 2.0 qua đầu vào chuẩn và đầu ra chuẩn.
Transport REST	Hợp đồng OpenAPI 3.1, xác thực bearer và các route phân cấp.
Transport gRPC	Dịch vụ `nextpdf.connect.v1`, server streaming và xác thực qua metadata.

Python SDK

Cung cấp khả năng trích xuất PDF sẵn sàng cho trích dẫn cho các ứng dụng Python, agent và dòng lệnh, dựa trên một endpoint NextPDF Connect.

Trang	Dùng cho
Python SDK	Trang trung tâm của mục cho gói Python `nextpdf`.
Tổng quan Python SDK	SDK làm gì và kết nối với Connect ra sao.
Bắt đầu nhanh với Python SDK	Cài đặt bằng `pip install nextpdf` và trỏ một client đến server của bạn.
Tài liệu tham khảo API Python SDK	Các lớp client, phương thức và kết quả có kiểu.
Python CLI	Giao diện dòng lệnh cho các quy trình trích xuất.
Máy chủ MCP dành cho Python	Cung cấp SDK cho các agent giao tiếp bằng MCP.

Mở rộng engine

Service Provider Interface (SPI) công khai cho phép bạn bổ sung khả năng mà không cần fork: các hợp đồng cho phông chữ, engine bố cục, trình lắng nghe sự kiện và back end ký; mỗi hợp đồng đều đi kèm cam kết ổn định rõ ràng.

Trang	Dùng cho
Viết phần mở rộng	Những phần bạn có thể mở rộng và cam kết ổn định đi kèm.
Quy tắc ổn định SPI	Hợp đồng tương thích ngược mà tiện ích mở rộng của bạn có thể dựa vào.
Phông chữ tùy chỉnh: hợp đồng FontRegistry	Đăng ký và phát hành phông chữ của riêng bạn.
Công cụ bố cục tùy chỉnh và can thiệp văn bản	Thay thế hoặc can thiệp hành vi bố cục.
Trình kích hoạt hành động và trình lắng nghe sự kiện	Quan sát và phản ứng với vòng đời tài liệu.
Hợp đồng nhà cung cấp KMS	Cung cấp khóa từ Key Management Service (KMS) của riêng bạn.

Khắc phục sự cố

Các mục dẫn bạn từ triệu chứng đến cách xử lý, dựa trên hệ phân loại ngoại lệ của chính engine. Hãy bắt đầu từ những gì bạn quan sát được, thay vì tên một lớp.

Trang	Dùng cho
Khắc phục sự cố	Trung tâm kho kiến thức: cách các mục được tổ chức và nơi nên bắt đầu.
Khắc phục sự cố: phông chữ và gắn thẻ	Lỗi nhúng phông chữ và gắn thẻ cấu trúc.
Khắc phục sự cố: mã hóa và cờ quyền	Lỗi mã hóa, mật khẩu và quyền.
Khắc phục sự cố: bộ nhớ và hiệu năng	Trần bộ nhớ và các vấn đề về thông lượng.
Khắc phục sự cố kiểm tra hợp lệ PDF/A và PDF/UA	Lỗi kiểm tra hợp lệ liên quan đến lưu trữ và khả năng tiếp cận.
Khắc phục sự cố: chữ ký và dấu thời gian	Lỗi kiểm tra hợp lệ chữ ký và dấu thời gian.

Xem thêm

Cookbook — các công thức theo từng tác vụ cho PHP, Connect và tích hợp.
Tài liệu tham khảo — các bề mặt API đã được kiểm chứng, ma trận hỗ trợ và tài liệu tham chiếu lỗi.
Di chuyển sang NextPDF — chuyển khỏi thư viện PDF khác, trong tab Bắt đầu.
Bên trong NextPDF — các bài viết Insider_ về lý do engine hoạt động như vậy.