用 Composer 安装并认证私有的 NextPDF 商业版包

概览

NextPDF 的高级版包 —— nextpdf/pro、nextpdf/enterprise 以及 nextpdf/premium 元包 —— 并未发布在公开的 Packagist 索引上。它们存放在与你账户绑定的私有 Composer 仓库中，因此在你告诉 Composer 两件事之前，一条普通的 composer require nextpdf/premium 是找不到它们的：仓库在哪里，以及如何向它认证。

本页承接许可与激活之后的内容。一旦你拥有凭据，只需配置一次 Composer，安装包，再进行验证即可。这里的一切都是标准的 Composer 行为，没有任何一项是 NextPDF 专有的工具。请像对待 API 密钥那样对待你的仓库令牌，正如许可页面对待已签名的许可信封那样：把它排除在公开的版本控制之外。

你的凭据从何而来

你的私有仓库 URL、用户名和令牌是在你获得许可之后签发的 —— 无论是通过我们的 Merchant of Record 购买，还是通过开始评估 —— 来自 许可门户。关于购买路径、双合同模型（购买与许可），以及计费问题和产品问题各应联系谁，请参阅 购买与许可。

1. 高级版包存放在哪里

你的许可门户会为安装签发两样东西：

• 一个私有 Composer 仓库 URL —— 提供高级版包的经过认证的端点。
• 该端点使用的用户名和令牌（一对 HTTP Basic 凭据）。

凡是本页出现仓库主机的地方，请替换为你许可门户提供的仓库 URL。凡是出现用户名或令牌的地方，请替换为签发给你账户的凭据。NextPDF 不会发布单一的共享 URL；端点和凭据都是你订阅所特有的。

2. 把私有仓库加入 composer.json

在你的项目根目录运行一条命令，把仓库告诉 Composer：

composer config repositories.nextpdf composer https://repo.example.com/nextpdf

把 https://repo.example.com/nextpdf 替换为门户提供的 URL。composer 仓库类型让 Composer 指向一个 Composer 格式的索引（一个 packages.json），这正是私有包端点所提供的内容。

该命令会把一个 repositories 块写入 composer.json。你也可以手动添加：

{
    "repositories": {
        "nextpdf": {
            "type": "composer",
            "url": "https://repo.example.com/nextpdf"
        }
    }
}

仓库定义不是密钥 —— 它只是标明一个位置，所以可以安全地提交。你必须保护的是下一步中的凭据。

3. 用三种标准方法之一进行认证

Composer 会从多个位置读取某个主机的 HTTP Basic 凭据。选择与你安装环境相匹配的方法。

方法 A —— auth.json（本地开发）

对于开发者机器，把凭据存放在与 composer.json 相邻的 auth.json 文件中。以你仓库 URL 的主机作为键：

composer config --auth http-basic.repo.example.com your-username your-token

这会创建（或更新）一个项目本地的 auth.json：

{
    "http-basic": {
        "repo.example.com": {
            "username": "your-username",
            "password": "your-token"
        }
    }
}

主机键（repo.example.com）必须与仓库 URL 中的主机完全一致 —— Composer 是按主机把凭据匹配到请求上的。

方法 B —— COMPOSER_AUTH 环境变量（CI/CD）

在持续集成中，你通常不希望磁盘上有文件。Composer 会从 COMPOSER_AUTH 环境变量读取相同的凭据，其值是一个与 auth.json 结构相同的 JSON 字符串：

export COMPOSER_AUTH='{"http-basic":{"repo.example.com":{"username":"your-username","password":"your-token"}}}'
composer install

从你 CI 提供方的密钥存储（掩码变量、secret 或 vault 绑定）注入 COMPOSER_AUTH，这样令牌就绝不会出现在流水线定义或构建日志中。

方法 C —— 全局按用户的认证（共享工作站）

若要为当前用户认证每一个项目而不使用逐项目文件，把凭据写入 Composer 的全局 auth.json：

composer config --global --auth http-basic.repo.example.com your-username your-token

这会把凭据存放在你的 Composer 主目录下 （COMPOSER_HOME，例如 ~/.composer/auth.json 或 ~/.config/composer/auth.json）。 它会应用到你以该用户身份构建的所有项目，因此当某个凭据应仅限于一个项目或流水线时，优先使用方法 A 或 B。

4. 把凭据排除在版本控制之外

仓库 URL 可以安全提交；令牌则不行。两条规则能让密钥远离你的历史记录：

• 忽略本地认证文件。 把 auth.json 加入 .gitignore，这样项目本地的凭据就绝不会被提交：

  /auth.json

• 在 CI/CD 中注入令牌。 从流水线的密钥存储提供 COMPOSER_AUTH（方法 B），而不是把 auth.json 提交进仓库或把它烘焙进容器镜像层。

如果令牌曾被提交或打印，请通过你的许可门户轮换它 —— 把它当作已泄露来处理，正如你对待泄露的 API 密钥那样。

5. 安装并验证

在仓库和凭据就位后，require 你许可所授权的版本：

# Pick the package for your entitlement:
composer require nextpdf/pro
# or
composer require nextpdf/enterprise
# or the metapackage, which the licensing page uses:
composer require nextpdf/premium

如果你的项目倾向于显式约束，可以固定一个主版本 —— 例如 composer require nextpdf/pro:^3，与 Pro 模块页面所用的约束一致。

验证 Composer 已解析出该私有包，并且其自动加载器可用。首先运行 composer show <installed-package> 确认包已安装 —— 对你所 require 的版本而言，例如 composer show nextpdf/pro、composer show nextpdf/enterprise 或 composer show nextpdf/premium：

# Use the package name you actually required:
composer show nextpdf/pro
# or
composer show nextpdf/enterprise
# or
composer show nextpdf/premium

如果 composer show 报告了该包及其版本，说明私有包已解析成功。随后重新运行 composer dump-autoload 会干净地重新生成自动加载器，使该包的类可被发现：

composer dump-autoload

作为可选的代码级检查，你可以确认你所安装版本中的某个类能够自动加载。不要臆测类名：打开你所安装版本的 API 参考，挑选任意一个有文档记录的公开类，然后测试它能否解析。要查找的类取决于你的版本 —— 某个版本附带的类在另一个版本中可能并不存在，而单个类能自动加载，只能证明那个版本存在，并不能证明每个版本都已安装。

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

// Replace the placeholder with a documented public class from YOUR edition's
// API reference. Do not hardcode a class from a different edition.
$class = 'Your\\Installed\\Edition\\DocumentedClass';
var_dump(class_exists($class));

安装包与激活它并不是一回事。仅有包本身并不会授予 Pro 或 Enterprise 能力 —— 你所激活的已签名许可才会选定生效的版本。成功安装后，请按照许可与激活放置并激活许可信封，对于 ionCube 编码的构建，还需设置 ionCube Loader。

排查

401 Unauthorized 或 403 Forbidden

Composer 已到达仓库，但凭据被拒绝或权限不足。请确认 auth.json / COMPOSER_AUTH 中的主机键与仓库主机完全一致（不带协议、不带路径、不带尾部斜杠），用户名和令牌是最新的，并且令牌未在你的门户中过期或被轮换。401 指向错误或缺失的凭据；403 指向一个有效凭据，但其权限范围并不包含你所请求的包或版本 —— 请检查你的订阅是否授权了你正在 require 的包名。

找不到包 / “could not find a matching version”

这通常意味着 Composer 没有使用或到达私有索引（所以它只搜索了公开的 Packagist），或者它到达了索引但没有找到与之匹配的可安装的包或版本。请确认 repositories.nextpdf 块存在于这个项目的 composer.json 中，且带有 "type": "composer" 和正确的 URL，并且你 require 的是确切的包名（nextpdf/pro、 nextpdf/enterprise 或 nextpdf/premium）。运行 composer config repositories 打印出 Composer 所看到的内容。URL 中的拼写错误或缺失的仓库块是常见原因，但也要检查你的版本约束是否匹配某个已发布的版本，你项目的 PHP 平台要求（以及 minimum-stability）是否允许该包，以及你的令牌权限是否确实覆盖了你正在 require 的包。

令牌本地可用但在 CI 中失败

本地的 auth.json 在 runner 上并不存在。从你的 CI 密钥存储设置 COMPOSER_AUTH（方法 B），而不是依赖某个文件，并确保该变量在 composer install 运行之前就已导出。在容器化构建中，在构建时传入该密钥，而不要把它持久化进某个镜像层。

错误的主机键

凭据是按主机匹配的。如果仓库 URL 是 https://repo.example.com/nextpdf，那么键必须是 repo.example.com —— 而不是完整 URL，也不是某个子路径。键不匹配会使 Composer 以未认证的方式发送请求，这会表现为 401。

参见

• 许可与激活
• 设置 ionCube Loader
• NextPDF Premium
• 选择你的路径
• 许可门户