機器可讀安裝指令¶

本頁採用 AI 代理程式友善的結構化格式，說明 NextPDF 的安裝程序。格式設計以可解析性為優先，確保 AI 助理能準確提取並執行每個步驟。

安裝決策樹¶

DECISION: Which package to install?
├── CONDITION: Need basic PDF generation only
│   └── ACTION: Install nextpdf/core
├── CONDITION: Need charts, PAdES B-LTA, PDF/A-4
│   └── ACTION: Install nextpdf/pro (requires license)
├── CONDITION: Need HSM, ZUGFeRD, batch processing
│   └── ACTION: Install nextpdf/enterprise (requires license)
├── CONDITION: Using Laravel framework
│   └── ACTION: Install nextpdf/laravel (includes core)
├── CONDITION: Using Symfony framework
│   └── ACTION: Install nextpdf/symfony (includes core)
├── CONDITION: Using CodeIgniter 4
│   └── ACTION: Install nextpdf/codeigniter (includes core)
├── CONDITION: Migrating from TCPDF
│   └── ACTION: Install nextpdf/tcpdf-compat
└── CONDITION: Need AI/MCP integration
    └── ACTION: Install nextpdf/mcp-server

步驟一：前置條件檢查¶

# PREREQUISITE_CHECK:
prerequisites:
  - name: PHP
    command: "php --version"
    required_version: ">=8.5.0"
    error_if_missing: "PHP 8.5 or higher is required. Install from https://www.php.net/downloads"

  - name: Composer
    command: "composer --version"
    required_version: ">=2.7.0"
    error_if_missing: "Composer 2.7+ is required. Install from https://getcomposer.org/download/"

  - name: PHP extensions (core)
    command: "php -m"
    required_extensions:
      - mbstring
      - dom
      - simplexml
      - libxml
      - zlib
    optional_extensions:
      - gd
      - imagick
      - fileinfo
    error_if_missing: "Enable required PHP extensions in php.ini"

步驟二：安裝套件¶

Core（免費，LGPL-3.0）¶

# INSTALL_COMMAND: nextpdf/core
# DESCRIPTION: PDF 2.0 generation engine, no license required
composer require nextpdf/core

Laravel 整合¶

# INSTALL_COMMAND: nextpdf/laravel
# DESCRIPTION: Laravel Service Provider + Facade + Queue support
composer require nextpdf/laravel

# AUTO_DISCOVERY: Laravel auto-discovers the service provider
# MANUAL_REGISTRATION (if needed):
# Add to config/app.php providers array:
#   NextPDF\Laravel\NextPdfServiceProvider::class

Symfony 整合¶

# INSTALL_COMMAND: nextpdf/symfony
# DESCRIPTION: Symfony Bundle + DI + Messenger
composer require nextpdf/symfony

# BUNDLE_REGISTRATION: Add to config/bundles.php:
#   NextPDF\Symfony\NextPdfBundle::class => ['all' => true]

CodeIgniter 4 整合¶

# INSTALL_COMMAND: nextpdf/codeigniter
# DESCRIPTION: CodeIgniter 4 Services + Helper
composer require nextpdf/codeigniter

Pro（商業授權）¶

# INSTALL_COMMAND: nextpdf/pro
# DESCRIPTION: Charts, PAdES B-LTA, PDF/A-4, advanced PDF parsing
# REQUIRES: Commercial license key

# STEP 1: Configure private package repository
composer config repositories.nextpdf-pro composer https://packages.nextpdf.dev/pro

# STEP 2: Set authentication credentials
composer config http-basic.packages.nextpdf.dev license "${NEXTPDF_LICENSE_KEY}"

# STEP 3: Install the package
composer require nextpdf/pro

Enterprise（商業授權）¶

# INSTALL_COMMAND: nextpdf/enterprise
# DESCRIPTION: HSM signing, ZUGFeRD, batch processing, RAG pipeline
# REQUIRES: Enterprise license key (includes pro)

composer config repositories.nextpdf-enterprise composer https://packages.nextpdf.dev/enterprise
composer config http-basic.packages.nextpdf.dev license "${NEXTPDF_LICENSE_KEY}"
composer require nextpdf/enterprise

MCP Server¶

# INSTALL_COMMAND: nextpdf/mcp-server
# DESCRIPTION: MCP tools for AI agents (20 tools, tier-gated)
# INSTALL_MODE: global (recommended) or per-project

# Global installation (recommended for AI assistants):
composer global require nextpdf/mcp-server

# Verify installation:
nextpdf-mcp --version

# Start MCP server:
NEXTPDF_LICENSE_KEY="${NEXTPDF_LICENSE_KEY}" nextpdf-mcp serve

TCPDF 相容層（遷移用）¶

# INSTALL_COMMAND: nextpdf/tcpdf-compat
# DESCRIPTION: Drop-in TCPDF compatibility layer for zero-code migration
# NOTE: Temporary migration aid; plan to migrate to native NextPDF API
composer require nextpdf/tcpdf-compat

步驟三：安裝後驗證¶

# VERIFY_COMMAND: Basic functionality check
php -r "
require 'vendor/autoload.php';
use NextPDF\Core\Document;
\$doc = Document::createStandalone();
\$doc->addPage();
echo 'NextPDF Core OK: ' . \$doc->getVersion() . PHP_EOL;
"

# EXPECTED_OUTPUT: NextPDF Core OK: 2.0.0
# ERROR_IF: Class not found → autoloader not configured correctly
# ERROR_IF: Version mismatch → wrong package version installed

# VERIFY_COMMAND: MCP server check
nextpdf-mcp list-tools --format json | head -20
# EXPECTED_OUTPUT: JSON array of available tools
# ERROR_IF: Command not found → add ~/.config/composer/vendor/bin to PATH

步驟四：環境變數設定¶

# ENVIRONMENT_VARIABLES: Required for production deployment

# Core (all deployments)
NEXTPDF_TEMP_DIR=/tmp/nextpdf          # Temporary file directory

# Spectrum accelerator (optional, improves performance)
SPECTRUM_ENABLED=true
SPECTRUM_BIN=/usr/local/bin/nextpdf-spectrum
SPECTRUM_SOCKET=/run/nextpdf/spectrum.sock

# Commercial license (Pro/Enterprise only)
NEXTPDF_LICENSE_KEY=your-license-key-here

# MCP Server specific
NEXTPDF_WORKSPACE=/path/to/pdf/files   # Sandbox root directory
NEXTPDF_MAX_FILE_SIZE_MB=100           # Per-file size limit
NEXTPDF_LOG_LEVEL=warn                 # error|warn|info|debug

步驟五：框架特定設定¶

Laravel¶

# PUBLISH_CONFIG: Publish configuration file
php artisan vendor:publish --provider="NextPDF\Laravel\NextPdfServiceProvider" --tag=config
# CREATES: config/nextpdf.php

# VERIFY_LARAVEL: Test via Artisan
php artisan nextpdf:info
# EXPECTED_OUTPUT: NextPDF configuration summary

Symfony¶

# PUBLISH_CONFIG: Export configuration
php bin/console nextpdf:config:dump
# CREATES: config/packages/nextpdf.yaml (with defaults)

步驟六：PHP 8.1 / 7.4 相容性（Backport）¶

# CONDITION: PHP version < 8.5
# ACTION: Install backport package instead

# CHECK PHP VERSION:
php -r "echo PHP_VERSION;"

# IF PHP >= 7.4 && PHP < 8.5:
composer require nextpdf/backport

# NOTE: Backport provides identical API, automatically selects
# the correct polyfills for your PHP version.

常見安裝錯誤排除¶

# TROUBLESHOOTING:

error: "could not find a version of the package"
  cause: "Private package repository not configured"
  fix: |
    composer config repositories.nextpdf-pro composer https://packages.nextpdf.dev/pro
    composer config http-basic.packages.nextpdf.dev license "${NEXTPDF_LICENSE_KEY}"

error: "The requested PHP extension mbstring is missing"
  cause: "Required PHP extension not installed"
  fix: |
    # Ubuntu/Debian:
    sudo apt-get install php8.5-mbstring php8.5-dom php8.5-xml
    # Alpine:
    apk add php85-mbstring php85-dom php85-xml

error: "nextpdf-mcp: command not found"
  cause: "Composer global bin directory not in PATH"
  fix: |
    echo 'export PATH="$PATH:$HOME/.config/composer/vendor/bin"' >> ~/.bashrc
    source ~/.bashrc

error: "Class 'NextPDF\\Core\\Document' not found"
  cause: "Autoloader not initialized"
  fix: |
    # Ensure this line exists at the top of your PHP file:
    require_once __DIR__ . '/vendor/autoload.php';

參見¶

MCP 安裝指南 — MCP 伺服器的 GUI 工具設定
加速器安裝 — Spectrum / Prisma 安裝
常見任務範本 — 安裝後的典型使用模式