安裝 NextPDF Artisan

重點摘要

使用 Composer 安裝 nextpdf/artisan。安裝過程會一併引入執行期相依套件 chrome-php/chrome。接著，請確保 PHP 行程能存取 Chrome 或 Chromium 執行檔。

安裝

composer require nextpdf/artisan

此套件在 composer.json 中宣告下列限制條件：

需求項目	限制條件	說明
`php`	`>=8.4 <9.0`	僅限 PHP 8.4
`nextpdf/core`	`^3.0 \|\| ^5.2`	開源的 NextPDF 引擎
`chrome-php/chrome`	`^1.15`	CDP 用戶端函式庫；以遞移方式帶入
`psr/log`	`^3.0`	選用的 logger 注入點

Composer 會自動解析（resolve） chrome-php/chrome。Chrome 執行檔 屬於系統相依項，Composer 永遠不會替你安裝。

備妥 Chrome 執行檔

此橋接層需要一個可執行的 Chrome 或 Chromium。chrome-php/chrome 預設會從常見路徑自動偵測執行檔。若要固定使用明確路徑，請透過設定傳入；詳見 /integrations/artisan/configuration/ 以及專屬的 /integrations/artisan/chrome-renderer-setup/ 頁面。

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

在將執行檔接入應用程式之前，請先驗證它能以 headless（無頭）模式執行：

chromium --headless --dump-dom about:blank

執行成功會印出一份空白的 DOM 文件，並以 0 結束。非零的結束碼代表執行檔本身或其共享函式庫遺失。請先修正此問題再繼續，因為此橋接層會在繪製時以 ChromeRenderException 呈現同一個失敗。

驗證套件已接好

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

require __DIR__ . '/vendor/autoload.php';

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

這會建構 renderer（渲染器），並在不啟動 Chrome 的情況下讀回預設 HTML 安全性原則。它確認自動載入機制，以及 nextpdf/core 合約綁定都能成功解析。（此行為由 tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected 驗證。）

容器環境的安裝

在 Docker 中，若沒有額外的核心權限，Chrome 沙箱通常無法以 PID 1/root 身分啟動。此套件針對這種情境提供 noSandbox 開關。停用 Chrome 沙箱會帶來實質安全性代價。/integrations/artisan/security-and-operations/ 頁面與 /integrations/artisan/chrome-renderer-setup/ 都會記錄這項代價，並明確說明其限制。在讀完那一節之前，不要設定這個開關。

邊界情況與陷阱

chrome-php/chrome 存在但沒有執行檔。 Composer 會成功；但第一次繪製就會丟出 ChromeRenderException，並包覆啟動失敗。函式庫檢查與執行檔檢查是分開的。
chrome-php/chrome 不存在。 若把此函式庫從自動載入器中移除，BrowserPool::getBrowser() 會丟出 ChromeNotAvailableException，並附上確切的修復指令。（由 tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable 驗證。）
版本限制。 nextpdf/core: ^3.0 || ^5.2——Artisan 同時支援這兩條 core 主要版本線。請釘選你的應用程式所對應的 core 版本。

安全性須知

安裝此橋接層會將外部行程（Chrome）引入信任邊界內。在把任何繪製路徑暴露給使用者提供的 HTML 之前，請先檢閱 /integrations/artisan/security-and-operations/。