为 NextPDF 商业版配置 ionCube Loader

快速概览

部分 NextPDF 商业发行版以 ionCube 编码 的 PHP 形式交付，因此在代码运行之前，必须先在你的 PHP 运行时中安装相匹配的 ionCube Loader。这适用于：

NextPDF Pro 与 Enterprise 试用构建，以及
NextPDF Pro 正式（付费）构建。

至于 NextPDF Enterprise 正式交付，其打包机制取决于你的协议。请遵循你许可条款中的交付说明，而不要假定某种特定运行时；参见许可与激活。

本页是一份实用的配置指南：ionCube 是什么、如何安装并验证 Loader、付费的 ionCube 编码 Pro 构建的许可文件应放在何处、如何在容器中运行，以及如何修复常见故障。受支持的 PHP 版本为 8.4，你安装的 Loader 必须与该运行时完全匹配。

ionCube 是什么以及 NextPDF 为何使用它

ionCube 是一款商业 PHP 编码器，搭配一个名为 ionCube Loader 的免费运行时组件。该 Loader 是一个 PHP（Zend）扩展。当 PHP 启动时，Loader 允许编码后的文件被解码并执行；若没有它，编码文件无法运行，PHP 会改为报告一个 loader 错误。

NextPDF 使用 ionCube 编码来保护专有的商业源代码，同时仍然交付可安装的 PHP，让你像部署运行任何其他 Composer 软件包一样去部署运行它。编码不会改变你调用库的方式——你的应用程序面向的仍是同一组公开契约——它只是额外要求运行时中存在该 Loader。

要获取 Loader 下载以及权威的、针对具体版本的说明，请使用 ioncube.com 上的供应商文档（ionCube Loader 文档与安装指南）。本页只涵盖 NextPDF 特有的配置；至于 Loader 本身，供应商才是权威来源。

前置要求

请在每个维度上都安装与你的 PHP 运行时相匹配的 ionCube Loader。其中任何一项不匹配，都是最常见的故障原因：

维度	必须匹配
PHP 版本	8.4（NextPDF 商业版要求 `>=8.4 <9.0`）。
操作系统	Loader 安装包所针对的操作系统（Linux、Windows、macOS）。
架构	主机的 CPU 架构，通常为 64 位（`x86-64` 或 `aarch64`）。
线程安全	非线程安全（NTS）或线程安全（ZTS），与你的 PHP 构建相匹配。

除了 Loader，你还需要：

通过 Composer 安装的 NextPDF 商业软件包——nextpdf/pro、nextpdf/enterprise，或 nextpdf/premium 元包。
对于付费构建，你的 许可文件。对于付费的 ionCube 编码 Pro 构建，请参见下文的许可文件放置。

要查看你当前的构建取值，请运行 php -i（或调用 phpinfo()），并检查 PHP Version、Architecture 与 Thread Safety 这几行。在大多数 CLI 与 PHP-FPM 部署中，线程安全是禁用的（NTS）；某些平台上的经典 Apache mod_php 则是 ZTS。请下载与这些确切取值对应的 Loader 安装包。

安装 Loader

下面的步骤是大致流程。文件的确切名称以及当前安装包的目录布局，请以 ioncube.com 上的 ionCube Loader 文档为准。

下载与你的环境相匹配的 Loader 安装包（PHP 8.4、你的操作系统、架构以及 NTS/ZTS）。该安装包为每个 PHP 版本与线程安全变体各包含一个 loader 文件。
把 loader 文件放入 PHP 扩展目录。 使用 php -i 报告的 extension_dir。在 Linux/macOS 上文件为 ioncube_loader_<os>_8.4.so（ZTS 构建使用 ..._8.4_ts.so）；在 Windows 上则为 ioncube_loader_win_8.4.dll（或 ..._ts.dll ZTS 变体）。
在 php.ini 中将其注册为 zend_extension。 ionCube Loader 必须作为 zend_extension 加载，而非普通的 extension，并且应当先于其他扩展加载。请添加一行，使用 loader 文件的绝对路径：
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
在 Windows 上，使用指向 .dll 的完整路径：
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
如果你的平台使用 conf.d 风格的包含目录，请把这一行放入一个会被较早读取的文件（例如 00-ioncube.ini），以便 Loader 先于其他扩展初始化。
重启 PHP 运行时。 重启 PHP-FPM、你的 Web 服务器（Apache/Nginx），或者直接重新运行 CLI——以实际运行你的应用程序的为准。长驻进程在重启之前会一直沿用旧配置。

验证

在尝试加载 NextPDF 之前，先确认 Loader 已激活。

首先，检查 PHP 版本横幅。当 Loader 已安装时，php -v 会追加一行写明它：

php -v

PHP 8.4.x (cli) ...
    with Zend OPcache v8.4.x, ...
    with the ionCube PHP Loader ...

短语 “with the ionCube PHP Loader” 即表示 Loader 已为该运行时激活。对于 Web（FPM / mod_php）部署，仅靠 CLI 横幅还不够——该运行时可能使用不同的 php.ini。请用一个由 Web 服务器提供的小脚本来确认 Web 运行时：

<?php
// loader-check.php — delete after verifying.
var_dump(extension_loaded('ionCube Loader'));
phpinfo(); // The output includes an "ionCube PHP Loader" section when active.

最后，确认某个 NextPDF 商业类确实能通过 Composer 的自动加载器加载。这能证明编码代码可以端到端运行：

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

// A premium class resolves only when the Loader can decode the package.
var_dump(class_exists(\NextPDF\Pro\Document\PdfPortfolio::class));

如果 php -v 写明了 Loader、Web 端 phpinfo() 显示出 ionCube 部分，并且商业类能够解析，那么 Loader 就已正确配置。

许可文件放置（付费的 ionCube 编码 Pro 构建）

ionCube 采用一种简单的许可模型：编码代码会在运行时检查 许可文件，当该文件缺失、不可读或已过期时拒绝运行。这适用于 付费的 ionCube 编码 Pro 构建——对它而言，你需要把购买所提供的许可文件放在运行时能够找到的位置。

这套 ionCube 许可文件机制专属于 ionCube 编码构建。本页并不假定 NextPDF Enterprise 正式交付是经 ionCube 编码的；它的打包与许可处理由你的许可条款约束——参见许可与激活。

确切路径因环境而异，因此这里只作一般性说明：

把许可文件放在你的 NextPDF 交付说明所指定的位置——通常与编码软件包并列，或放在应用程序可读取的目录中。请确保 PHP 进程用户拥有读取权限。
除非说明要求，否则不要重命名该文件；loader 会按一个特定名称查找它。
在容器与只读部署中，请将许可文件挂载或复制到镜像里，或放到运行时可见的、可写且可读的路径中（参见 Docker 与容器）。

该许可文件在运行时层面约束激活；它与应用程序层面的许可（用于选定你的版本与功能）是相互独立的。至于条款、期限以及你的订阅授予的内容，请参见许可与激活与你的许可协议——本页并不定义许可条款。

故障排查

”Loader not installed” / “Failed loading … ioncube_loader”

Loader 在运行该代码的运行时中未激活，或者路径有误。请重新检查 zend_extension 这一行是否以绝对路径指向一个存在的文件、你是否重启了运行时，以及你是否用 php -v / phpinfo() 验证的是 同一个 运行时（CLI 还是 FPM）。出现 Failed loading 消息通常意味着文件存在但与 PHP 构建不匹配（参见下一条）。

PHP 版本、NTS/ZTS 或架构不匹配

为不同 PHP 版本、线程安全模式或架构构建的 Loader 将无法加载。请从 php -i 确认 PHP Version、Thread Safety 与 Architecture，然后安装与之匹配的 NTS/ZTS 及位数、面向 PHP 8.4 的 Loader 文件。8.4 与 8.4_ts（或 _ts.dll）这个后缀就是线程安全选择器——用错它是常见失误。

Loader 加载顺序

ionCube Loader 必须是一个 zend_extension，并且应当先于其他扩展初始化。如果你看到有关 Loader 在其他扩展之后加载的警告，请把它的 zend_extension 行移到更靠前的位置——或者在 conf.d 布局下，给它的包含文件取一个排序靠前的名称（例如 00-ioncube.ini）。

CLI、FPM 与 Web 服务器使用不同的 php.ini 文件

PHP 通常为 CLI 加载的 php.ini 与为 PHP-FPM 或 mod_php 加载的并不相同。只配置 CLI 会让 Web 运行时缺少 Loader（反之亦然）。运行 php --ini 查看 CLI 使用的是哪个文件，并在 Web 端 phpinfo() 的输出中检查 Loaded Configuration File 这一行。请把 zend_extension 行添加到 每一个 运行 NextPDF 的 php.ini 中，并重启各个运行时。

找不到许可文件或许可文件已过期

对于付费的 ionCube 编码 Pro 构建，许可文件缺失、不可读或已过期都会让编码代码停止运行。请核实该文件是否位于预期位置、PHP 进程用户是否能读取它，以及它是否尚未过期。续期与期限相关问题，请参见许可与激活与你的许可协议。

与 OPcache 的交互

OPcache 会缓存已编译的脚本，但 ionCube 编码的文件是由 Loader 在运行时解码的。如果你更改了 Loader 或其配置后，运行时仍表现得仿佛它不存在，请重启 PHP 运行时（这会清空 OPcache），而不要依赖热重载。请保持 ionCube 的 zend_extension 处于注册状态，使其先于 OPcache 加载；两者可以共存，php -v 应当会同时列出二者。

Docker 与容器

在容器化部署中，请把 Loader 安装 在镜像里，并确保它与 容器的 PHP 构建相匹配——而不是你主机的。基础镜像固定了 PHP 版本、操作系统、架构与线程安全模式，因此请下载与这些取值对应的 Loader 安装包。

一次典型的镜像构建：

从一个 PHP 8.4 基础镜像开始（注意它是 NTS 还是 ZTS——官方的 php:8.4-cli / 8.4-fpm / 8.4-apache 标签是 NTS，而包含 zts 的标签是线程安全的；请相应地选择 Loader）。
把相匹配的 ionCube Loader 文件加入镜像的 extension_dir。
把 zend_extension=... 行写入镜像的 php.ini（或一个 conf.d 包含文件）。
对于付费的 ionCube 编码 Pro 构建，请通过把许可文件复制进镜像、或在运行时挂载到容器可读取的路径中来提供它。

由于 Loader 已构建进镜像，同一个容器在任何地方都会以相同方式运行。如果之后你升级了基础镜像的 PHP，请把 Loader 文件替换为与新运行时相匹配的构建。