安裝指南¶

本頁涵蓋所有 NextPDF 套件的安裝方式。開源套件透過標準 packagist.org 取得；商業套件（Pro、Enterprise）則需透過 packagist.com 並配合 授權金鑰。

前置需求¶

在安裝任何 NextPDF 套件之前，請確認環境符合以下需求：

Backport 相容性：若你的環境為 PHP 8.1 或 7.4，請勿直接安裝 nextpdf/core。 改用 nextpdf/backport 套件，它提供完整的降版相容層。 詳見 PHP 相容性說明。

開源套件安裝（packagist.org）{#open-source-packages}¶

所有 LGPL-3.0 授權的套件均可直接從 packagist.org 安裝，無需任何額外認證。

僅安裝 Core¶

composer require nextpdf/core

安裝 Core + 框架整合¶

composer require nextpdf/laravel

composer require nextpdf/symfony

composer require nextpdf/codeigniter

安裝渲染橋接套件¶

composer require nextpdf/artisan

composer require nextpdf/gotenberg

composer require nextpdf/cloudflare

安裝整合套件¶

# MCP Server (AI Agent 工具)
composer require nextpdf/mcp-server

# TCPDF 相容層（遷移用）
composer require nextpdf/tcpdf-compat

# Backport（PHP 7.4 / 8.1 環境）
composer require nextpdf/backport

商業套件安裝（packagist.com）¶

nextpdf/pro 與 nextpdf/enterprise 為商業授權套件，透過 Packagist.com 的私有 Composer Repository 提供。

購買授權後，你將收到一組 PACKAGIST_TOKEN（格式為 username:token）。 如尚未購買，請聯繫業務取得試用授權。

步驟一：設定 auth.json¶

將你的授權金鑰加入 Composer 的認證設定。請勿將 auth.json 提交至版本控制系統。

# 全域設定（推薦，適用於開發機）
composer config --global --auth http-basic.repo.packagist.com \
    YOUR_PACKAGIST_USERNAME \
    YOUR_PACKAGIST_TOKEN

或手動編輯 ~/.composer/auth.json（全域）或專案根目錄的 auth.json：

{
    "http-basic": {
        "repo.packagist.com": {
            "username": "YOUR_PACKAGIST_USERNAME",
            "password": "YOUR_PACKAGIST_TOKEN"
        }
    }
}

CI/CD 環境：請將 PACKAGIST_TOKEN 儲存為 GitHub Actions Secret， 並在 workflow 中動態設定：

- name: Configure Composer credentials
  run: |
    composer config --auth http-basic.repo.packagist.com \
      "${{ secrets.PACKAGIST_USERNAME }}" \
      "${{ secrets.PACKAGIST_TOKEN }}"

步驟二：加入私有 Repository¶

composer config repositories.packagist-com \
    composer \
    https://repo.packagist.com/nextpdf-labs/

這會在你的 composer.json 中新增以下區塊：

{
    "repositories": {
        "packagist-com": {
            "type": "composer",
            "url": "https://repo.packagist.com/nextpdf-labs/"
        }
    }
}

步驟三：安裝商業套件¶

composer require nextpdf/core nextpdf/pro

composer require nextpdf/core nextpdf/pro nextpdf/enterprise

composer require nextpdf/laravel nextpdf/pro

composer require nextpdf/symfony nextpdf/pro nextpdf/enterprise

完整 composer.json 範例¶

以下是生產環境建議的完整 composer.json 設定（Laravel + Enterprise 組合）：

{
    "name": "your-org/your-app",
    "require": {
        "php": "^8.5",
        "nextpdf/laravel": "^2.0",
        "nextpdf/pro": "^2.0",
        "nextpdf/enterprise": "^2.0"
    },
    "repositories": {
        "packagist-com": {
            "type": "composer",
            "url": "https://repo.packagist.com/nextpdf-labs/"
        }
    },
    "config": {
        "preferred-install": "dist",
        "sort-packages": true,
        "allow-plugins": {
            "php-http/discovery": true
        }
    }
}

執行安裝：

composer install --no-dev --optimize-autoloader

重要：composer.lock 必須提交至版本控制系統，以確保 CI/CD 環境使用相同的依賴版本。 請勿將 composer.lock 加入 .gitignore。

Docker 快速啟動（含 Spectrum Sidecar）{#docker-spectrum}¶

Spectrum 加速器以獨立 Sidecar 程序方式執行，透過 Unix Socket 或 TCP 與 PHP 通訊。

docker-compose.yml 範例¶

version: "3.9"

services:
  app:
    image: php:8.5-fpm
    environment:
      SPECTRUM_SOCKET: "tcp://spectrum:9000"
      SPECTRUM_ENABLED: "true"
    depends_on:
      - spectrum
    volumes:
      - .:/var/www/html

  spectrum:
    image: ghcr.io/nextpdf-labs/spectrum:latest
    environment:
      SPECTRUM_LISTEN: "0.0.0.0:9000"
      SPECTRUM_WORKERS: "4"
      SPECTRUM_LOG_LEVEL: "info"
    ports:
      - "9000:9000"
    restart: unless-stopped

啟動服務¶

docker compose up -d

驗證 Spectrum 連線¶

<?php

declare(strict_types=1);

use NextPDF\Core\Accelerator\SpectrumClient;

$client = SpectrumClient::fromEnv(); // 讀取 SPECTRUM_SOCKET 環境變數
$status = $client->ping();

echo $status->isHealthy() ? 'Spectrum OK' : 'Spectrum unavailable';

降級行為：若 Spectrum sidecar 無法連線，SpectrumClient 的電路斷路器（circuit breaker） 在連續 3 次失敗後會自動切換至純 PHP 實作，確保服務不中斷。

驗證安裝¶

安裝完成後，執行以下指令確認所有套件正常載入：

# 驗證 Composer 設定
composer validate --strict

# 確認 NextPDF 套件已安裝
composer show nextpdf/*

# 執行核心測試套件（開發環境）
composer test

預期輸出（composer show nextpdf/*）：

nextpdf/core        2.x.x   PDF 2.0 Engine for Modern PHP
nextpdf/laravel     2.x.x   Laravel integration for NextPDF
nextpdf/pro         2.x.x   NextPDF Pro — Charts, PAdES, PDF/A-4

下一步¶

• 快速開始（5 分鐘） — 立即產生你的第一份 PDF
• Laravel 快速開始
• Symfony 快速開始
• CodeIgniter 快速開始
• PHP 相容性說明 — PHP 7.4 / 8.1 Backport 使用方式
• 架構說明 — 了解 NextPDF 的內部設計