配置 NextPDF Laravel 包

概览

config/nextpdf.php 由 php artisan vendor:publish --tag=nextpdf-config 发布。每个键都有环境变量回退与硬编码默认值。本页逐项记录每个键，并与包内 config/nextpdf.php 的呈现保持完全一致。

安装

php artisan vendor:publish --tag=nextpdf-config

provider 还会把包默认值合并到 nextpdf 配置键之下，这个合并会在 register() 期间完成。因此即使尚未发布配置，未设置的键也会回退到下列数值。

概念总览

大多数环境变量既接受 NEXTPDF_* 名称，也接受旧版 TCPDF_* 名称。旧版前缀在 UPGRADE.md 记载的过渡期内受支持；新部署应使用 NEXTPDF_* 形式。配置文件会按以下顺序解析数值：环境变量 → 已发布文件值 → 包默认值。

API 接口 — 配置键

文件布局

键	环境变量（主要）	默认值	作用
page_format	NEXTPDF_PAGE_FORMAT	A4	默认页面格式（A4、A3、A5、Letter、Legal、Tabloid）
orientation	NEXTPDF_ORIENTATION	P	纵向（P）或横向（L）
unit	NEXTPDF_UNIT	mm	度量单位（pt、mm、cm、in）
defaults.creator	NEXTPDF_CREATOR	NextPDF	文档创建者元数据；应用于 PdfDocumentInterface 绑定
defaults.author	NEXTPDF_AUTHOR	（空）	作者元数据；仅在非空值时应用
defaults.language	NEXTPDF_LANG	en	文档语言；应用于文档绑定
defaults.margin_top / _right / _bottom / _left	—	10	默认边距
defaults.font_family	—	dejavusans	默认字体系列
defaults.font_size	—	12	默认字体大小
defaults.trim_box	—	null	以点为单位的 TrimBox [left, bottom, right, top]，或 null
defaults.bleed_box	—	null	以点为单位的 BleedBox [left, bottom, right, top]，或 null

provider 会把 defaults.creator、defaults.language，以及（已设置时）defaults.author 应用到每份新解析出的文档上。当 defaults.author 的值为空时，会跳过该分支。

归档与颜色

键	环境变量（主要）	默认值	作用
pdfa	NEXTPDF_PDFA	null	PDF/A 归档等级（null、4、4e、4f）。非 null 时会在文档绑定上启用 PDF/A，并需要 nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	放置额外 TrueType 字体的目录；驱动字体注册表的搜索路径
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	已解析字体与临时文件的缓存目录
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	RGB ICC 配置文件路径；PDF/A 模式下必需
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	用于印刷工作流的可选 CMYK ICC 配置文件
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	在字体缓存上使用 flock，以防并行 queue worker 写入时造成损坏

将 pdfa 设为非 null 值需要 Premium 方案。若没有 nextpdf/premium，在设置了 pdfa 的情况下解析文档绑定会因 PDF/A 版本类型抛出 class-not-found 错误。本页不说明 Premium 归档行为；请参阅 Premium 文档。

Worker 内存（长生命周期运行时）

键	环境变量（主要）	默认值	作用
preload_fonts	—	[]	在 worker 启动时解析的绝对字体文件路径列表。字体注册表会在预热后锁定
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	以 MB 为单位的 LRU 图像缓存预算。0 会停用缓存。provider 层不强制任何上限

图像缓存预算没有 provider 强制的上限。请使用容器内存限制或 php.inimemory_limit 来约束它。配置文件建议在实践中以 256 MB 作为最大值。

数字签名（Premium）

键	环境变量（主要）	默认值	作用
signature.enabled	NEXTPDF_SIGN_ENABLED	false	当值为 false（或证书为空）时，SignerInterface 会解析为 null
signature.certificate	NEXTPDF_SIGN_CERT	null	签名证书路径
signature.private_key	NEXTPDF_SIGN_KEY	null	私钥路径
signature.password	NEXTPDF_SIGN_PASSWORD	（空）	密钥口令
signature.extra_certs	—	[]	中间 CA 证书路径
signature.level	NEXTPDF_SIGN_LEVEL	B-B	传给签名器的 PAdES baseline 等级

此处说明的 Core 包不随附签名器实现；SignerInterface 绑定会解析为 null，直到 nextpdf/premium 提供签名器为止。安装 Premium 后，level: B-B 会生成 PAdES B-B baseline 签名。更高的 PAdES baseline 取决于已配置的时间戳认证机构和 Premium 能力；本页不说明这些等级。

时间戳认证机构

键	环境变量（主要）	默认值	作用
tsa.url	NEXTPDF_TSA_URL	null	TSA endpoint。为空时，TsaClient 会解析为 null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	（空）	TSA HTTP 认证凭据
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	用于 TSA mTLS 的客户端证书/密钥
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	PSR-18 客户端的 HTTP 超时秒数
tsa.pinned_public_keys	—	[]	Base64 SHA-256 SPKI pin（RFC 7469）。留空会停用 pinning
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	当 TSA 出示未 pin 的 SPKI 时发出警告
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	允许对 TSA 使用明文 HTTP。生产环境请保持 false

OCSP 响应缓存

键	环境变量（主要）	默认值	作用
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	在验证期间缓存 OCSP 响应
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	以秒为单位的缓存 TTL
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	缓存目录；null 会让缓存仅保留在内存中

队列

键	环境变量（主要）	默认值	作用
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	队列连接；null 会使用默认连接
queue.queue	NEXTPDF_QUEUE_NAME	pdf	队列名称；GeneratePdfJob 会被推送到该队列
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	以秒为单位的每个作业超时时间

Chrome CDP renderer（渲染器）（Artisan 扩展）

键	环境变量（主要）	默认值	作用
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	环境变量值或未设置	Chrome/Chromium 可执行文件路径
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	以秒为单位的渲染超时
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	（空）	注入到已渲染 HTML 中的默认 CSS
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	禁用 Chrome sandbox
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	以字节为单位的 HTML 输入大小上限

只有当存在 Chrome browser-factory 类（即 nextpdf/artisan 扩展）时，artisan 区段才会应用到文档绑定。若不存在，则跳过此区段。

代码示例 — 生产环境

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

边界情况与陷阱

• signature.enabled = true 与空的 signature.certificate 搭配时，仍会把 SignerInterface 解析为 null；两者都必须设置。
• tsa.url = null 会强制 TsaClient 为 null，即使其他 tsa.* 键已填入也一样。
• signature.level = null 会让签名器回退到 PAdES B-B。
• image_cache_mb 设为 null（而不是 0）会回退到 50 MB 默认值；0 则会显式停用缓存。
• 旧版 TCPDF_* 环境变量仍可读取，但已弃用；请迁移到 NEXTPDF_*。

效能

读取配置是 O(1) 数组访问。preload_fonts 会在 worker 启动时执行一次性 O(f) 解析，以换取更低的首次请求延迟。较大的 image_cache_mb 能减少重复的图像解码，但代价是更多内存常驻于进程中。

安全性注意事项

tsa.allow_insecure_http 会削弱时间戳的信任度，在生产环境中必须保持 false。TSA URL 只应来自受信任的配置；若通过管理接口对外暴露，请使用 egress 防火墙或 DNS 策略来缓解请求伪造。请参阅 /integrations/laravel/security-and-operations/.

符合性

没有规范性标准规定配置文件的结构；所有键都会对照所记载修订版中的包内 config/nextpdf.php 进行验证。签名等级语义由 Premium 管理，不在本 Core 页面的范围内。

商业脉络

安装了 nextpdf/premium 时，signature 与 tsa 区段会驱动 Premium 签名。这是可选的 Enterprise 能力；此处说明的 Core 包无需任何代码变更即可使用该能力。请参阅 https://nextpdf.dev/get-license/?intent=laravel-signing。

另请参阅

• /integrations/laravel/install/ — 发布配置文件
• /integrations/laravel/production-usage/ — 在实际控制器中应用配置
• /integrations/laravel/security-and-operations/ — 强化 TSA 与队列设置
• /integrations/laravel/boot-and-discovery/ — 每个键驱动的绑定