使用 Composer 安裝並驗證私有的 NextPDF premium 套件

概覽

NextPDF premium 套件——nextpdf/pro、nextpdf/enterprise 與 nextpdf/premium 統合套件——並未發佈到公開的 Packagist 索引。它們存放在一個與你帳戶綁定的私有 Composer 儲存庫中，因此單純的 composer require nextpdf/premium 在你告訴 Composer 兩件事之前都無法找到它們：儲存庫在哪裡，以及如何對它進行驗證。

本頁承接 授權與啟用 之後的內容。一旦你取得憑證，便設定 Composer 一次、安裝該套件並驗證它。這裡的一切都是標準的 Composer 行為，沒有任何 NextPDF 專屬工具。請將你的儲存庫權杖視同 API key，就如同授權頁面對待已簽署的授權封套一樣：讓它遠離公開的版本控制。

你的憑證從何而來

你的私有儲存庫 URL、使用者名稱與權杖，會在你取得授權之後核發——無論是透過我們的登錄商家購買，或是開始一次評估——核發來源為授權入口網站。關於購買流程、雙合約模式（購買與授權之分），以及帳務問題與產品協助分別該聯絡誰，請參閱購買與授權。

1. premium 套件存放在哪裡

你的授權入口網站會為安裝核發兩樣東西：

• 一個私有 Composer 儲存庫 URL——提供 premium 套件的已驗證端點。
• 一組使用者名稱與權杖（一對 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），這正是私有套件端點所提供的內容。

該指令會在 composer.json 中寫入一個 repositories 區塊。你也可以手動加入：

{
    "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 供應商的祕密存放區（遮罩變數、祕密或 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 key 一樣。

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 已解析該私有套件，且其 autoloader 可運作。先針對你 require 的版本執行 composer show <installed-package> 來確認套件已安裝——例如 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 會乾淨地重建 autoloader，讓該套件的類別可被探索：

composer dump-autoload

作為一項選用的程式碼層級檢查，你可以確認你已安裝版本中的某個類別能被 autoload。請勿臆測類別名稱：開啟你所安裝版本的 API 參考，挑選任何一個有記載的公開類別，然後測試它是否能解析。要尋找的類別取決於你的版本——某個版本隨附的類別在另一個版本中可能並不存在，而單一類別能 autoload 只證明該版本存在，並不代表每個版本都已安裝。

<?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），或者它連上了索引，但找不到符合的可安裝套件或版本。請確認這個專案的 composer.json 中存在 repositories.nextpdf 區塊，帶有 "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
• 選擇你的路徑
• 授權入口網站