安装 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 会自动解析 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

这会构建渲染器，并在不启动 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/。

另请参阅

/integrations/artisan/overview/——概述
/integrations/artisan/configuration/——配置
/integrations/artisan/quickstart/——快速上手
/integrations/artisan/chrome-renderer-setup/——Chrome 渲染器设置
/integrations/artisan/security-and-operations/——安全与运维