在发行流程中运行 backport 构建器

构建工具，而非运行时依赖。本页说明如何操作用于生成 backport 的发行流程。此流程在 CI 中运行；绝不会在下游应用程序中运行。

概览

生产环境路径使用两个工作流。0-ci.yml 会为任一长期分支上的每项变更把关。build.yml 负责生成并发行分发包，由来源发行触发。两者均对照 .github/workflows/ 加以验证。

CI 把关

在推送至 PHP74 与 PHP81，以及针对它们发起 pull request 时，0-ci.yml 会运行。它包含三个按顺序运行的作业：

PHPStan（构建工具）——composer analyse，针对 rector/rules 与 scripts 运行 level 10。
PHPUnit（Rector 规则）——composer test，也就是三条自定义规则的 fixture 测试套件。
构建试运行——composer build:dry，只有前两个作业通过后才会运行。

受信任的事件会在自托管 PHP runner 上运行。来自 fork 的 pull request 与 Dependabot 会在配置了 PHP 8.5 的 GitHub 托管 runner 上运行。请对照 0-ci.yml 验证（即 runs-on 表达式与条件式 setup-php 步骤）。双分支模型会通过各分支各自的 pull request，分别为同时触及两个目标的变更把关。

发行流程

build.yml 是生产构建工作流。它会在类型为 source-release 的 repository_dispatch 事件发生时触发，也可以通过附带标签输入的 workflow_dispatch 手动触发。版本标签驱动整个流程。版本号采用基于已声明公开 API 的 MAJOR.MINOR.PATCH（Semantic Versioning 2.0.0 §2）。

PHP 8.1 通道

build-php81——检出构建工具，配置 PHP 8.5，安装构建依赖，在发行标签处克隆来源仓库，运行 scripts/build.php，将 runner 切换至 PHP 8.1，在 PHP 8.1 上对 output/src 执行语法检查，随后以 --no-dev 安装生成的包。输出会作为制品上传。
validate-php81——下载制品，并在 PHP 8.1、8.2、8.3 与 8.4 的矩阵中安装与测试。
release-php81——下载制品，提交生成的树并打标签，将其打包成 zip（排除 vendor/ 与 .git/），然后发布附带该归档文件的 GitHub release。

PHP 7.4 通道

build-php74——在 PHP74 分支上检出构建工具，配置 PHP 8.5，仅克隆标签处的核心来源仓库，运行 scripts/build.php --target=php74，切换至 PHP 7.4，并在 PHP 7.4 上对输出执行语法检查。
validate-php74——在 PHP 7.4 与 8.0 的矩阵中安装与测试。
release-php74——将仅含核心的输出打包成 zip，并作为第二个归档文件附加到同一个 release。

请对照 build.yml 的作业定义与矩阵验证。

这两个通道共用同一个 GitHub release。PHP 8.1 通道负责创建它，PHP 7.4 通道则将自己的归档文件附加到同一个标签。搭配 cancel-in-progress: false 的 concurrency 组 backport-build 会将构建串行化，使两次来源发行不会相互竞争。

操作流程

触发构建

当来源组织发布 release 时，构建通常会自动触发。若要手动重新构建特定标签，请以标签输入派发 build.yml（例如 v2.0.0）。派发令牌是 secrets.BACKPORT_TRIGGER_TOKEN，用于授权克隆来源仓库。请对照 build.yml 验证（workflow_dispatch.inputs.tag、GH_TOKEN）。

解读失败的构建

构建脚本会在第一个失败阶段停止，并打印该阶段的名称和错误。这五个阶段分别是合并、Rector、composer.json 生成、资产复制和验证。若构建后的语法检查步骤失败，表示 Rector 生成了目标运行时会拒绝的输出。该步骤就是保护该发行的把关点。请在 /integrations/backport/troubleshooting/. 中将失败对应到其成因。

会发布哪些内容

该 release 会附加压缩成 zip 的分发归档文件。此包以版本标签形式发布，而非以分支形式发布。使用者会从该发行渠道安装 nextpdf/backport（并按需选用 nextpdf/backport-pro）。该归档文件排除 vendor/ 与 .git/。请对照 build.yml 验证（zip -r ... -x '*/vendor/*' '*/.git/*'）。

为输出设置版本

生成的 composer.json 会带有命令行传入的版本（--version，或去除开头 v 后的派发标签）。Pro 包会将 nextpdf/backport 锁定在相符的 major.minor caret 约束上。请对照 scripts/adjust-composer.php 验证（majorMinor()、generateProComposer()）。请让来源发行标签与 backport 版本保持一致，以确保 replace 映射表一致。

后续

/integrations/backport/security-and-operations/ —— 该流程的信任边界与供应链态势。
/integrations/backport/troubleshooting/ —— 按阶段划分的失败参考。