跳转到内容
NextPDF

NextPDF Backport Builder 快速入门

这是构建工具，并非运行时依赖包。本分步教程在维护者或持续集成（CI）主机上执行。下游项目使用的是这里产出的归档文件。这里的步骤绝不会在应用程序服务器上执行。

概览

标题为“概览”的章节

你会执行三件事。首先是试运行（dry-run），它会在不更改任何文件的情况下，证明整个流程已正确串接。接着是完整的 PHP 8.1 构建，然后是完整的 PHP 7.4 构建。每个步骤都只需一条命令。每条命令背后都是一个 Composer 脚本，或一次有文档记录的 scripts/build.php 调用。

先决条件

标题为“先决条件”的章节
  • 一台 PHP >=8.4 <9.0 的构建主机，并已安装构建依赖包（composer install，不加 --no-dev）。请参阅 /integrations/backport/install/.
  • 源代码仓库需检出在同一源代码根目录下的同级目录中。PHP 8.1 构建会读取 nextpdf、nextpdf-Artisan、nextpdf-compat-legacy、nextpdf-Laravel、nextpdf-Symfony、nextpdf-CodeIgniter，以及 nextpdf-Pro（供 Pro 使用）。PHP 7.4 构建只读取 nextpdf。已对照 scripts/merge-sources.php 验证。

步骤 1 — 试运行（dry-run）

标题为“步骤 1 — 试运行（dry-run）”的章节

试运行会以仅报告（report-only）模式执行每个阶段。合并阶段会列出它将复制的内容。Rector 会被声明，但不会实际执行。composer 生成、资产复制与验证阶段会打印各自准备执行的动作。不会写入任何内容。请先执行这一步，确认你的源代码配置与标志都正确，因为这是最快的检查方式。

Terminal window
composer build:dry

composer build:dry 会解析为 php scripts/build.php --dry-run。已对照 composer.jsonscripts 与 scripts/build.php 验证（即各阶段中的 dryRun 分支）。在默认标志下，目标是 php81，源代码根目录则为脚本默认值。如步骤 2 所示，这两者你都可以覆写。

如果试运行报告缺少某个源代码仓库，它会立即失败并指出该仓库的名称。继续之前，请先修正源代码配置 — 请参阅 /integrations/backport/troubleshooting/.

步骤 2 — 完整的 PHP 8.1 构建

标题为“步骤 2 — 完整的 PHP 8.1 构建”的章节

PHP 8.1 构建会按顺序执行数个步骤。它会合并 core，再加上各框架适配器与 tcpdf 兼容层。它会执行单趟（single-pass）的 Rector 配置。它会生成 nextpdf/backportcomposer.json。它会复制许可证、写入一份 CHANGELOG.md，并计算所生成的 PHP 文件数量。

Terminal window
php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

已对照 scripts/build.php CLI 入口点验证。五个阶段会按顺序执行：合并源代码、执行 Rector 降级、生成 composer.json、复制静态资产、验证输出。每个阶段成功时都会打印一个勾选符号。第一个失败的阶段会中止构建，并打印该阶段的错误。若要排除 Pro，请加上 --no-pro。

成功时，编排器会打印耗用时间与输出路径。纳入 Pro 时，它也会打印 Pro 的输出路径。输出目录随后会包含 src/、tests/、一份生成的 composer.json（其中声明了 replace 对应表与 polyfill 需求）、LICENSE，以及 CHANGELOG.md。

步骤 3 — 完整的 PHP 7.4 构建

标题为“步骤 3 — 完整的 PHP 7.4 构建”的章节

PHP 7.4 构建只包含 core，并执行两趟（two-pass）流程。这几趟分别是：enum 预处理、清除缓存、Rector 后修正，接着是完整降级。

Terminal window
php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

已对照 scripts/build.php 验证。在此，--target=php74 会强制只构建 core 并停用 Pro，而 runRector() 会选用两趟路径。所生成的 composer.json 带有 >=7.4 <8.1 这项限制，只替换 nextpdf/core，并在 8.2–8.5 的 polyfill 之上再加入 PHP 8.0 与 8.1 的 polyfill。

步骤 4 — 读取输出

标题为“步骤 4 — 读取输出”的章节

验证阶段会计算 output/src 中的 PHP 文件数量，若数量为零便会失败。它不会在本机执行语法检查，因为本机解释器是构建主机上的新版 PHP，而不是目标版本。它会打印用于对照真实目标运行时进行验证的 Docker 命令。已对照 scripts/build.php（validateOutput()）验证。

若要完整验证，请在目标 PHP 下执行语法检查。发行工作流程做的正是这件事。它会在 PHP 8.1（或 PHP 7.4）上对输出进行语法检查，接着在整个支持矩阵上安装并实际运行。请参阅 /integrations/backport/production-usage/.

你构建出了什么

标题为“你构建出了什么”的章节
产物由何者构建版本约束替换对象
nextpdf/backport（PHP 8.1）步骤 2>=8.1 <8.5core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro（PHP 8.1）步骤 2，当纳入 Pro 时>=8.1 <8.5nextpdf/pro
nextpdf/backport（PHP 7.4）步骤 3>=7.4 <8.1nextpdf/core

已对照 scripts/adjust-composer.php 验证。

后续步骤

标题为“后续步骤”的章节
  • /integrations/backport/production-usage/ — 将这套流程串接进事件驱动的发行工作流程。
  • /integrations/backport/configuration/ — 这些命令背后的规则与标志参考。
  • /integrations/backport/troubleshooting/ — 每一种阶段失败及其含义。