比较与部署指南
不确定需要哪些包？使用下方的交互式向导，或浏览部署场景与决策矩阵，找到最适合您的配置。
找到您的完美配置
项目类型
生成您的配置
配置生成器
选择包和选项，自动生成可直接使用的配置文件。
composer require yeeefang/tcpdf-next部署场景
不同的托管环境具有不同的功能支持。以下是各环境的最佳搭配：
共享主机
Core有限的 PHP 访问，无 Shell。仅 Core 搭配基本字体。无 Chrome/RoadRunner。
VPS (PHP-FPM)
Core
Artisan
Laravel完全服务器控制。安装 Chrome 支持 HTML→PDF。适合大部分应用。
VPS + RoadRunner
RoadRunner Core Artisan Laravel常驻 Worker 消除冷启动。吞吐量提升 3-7 倍。
专用服务器
Core Artisan
Pro Laravel完整资源。适合 Pro 功能（PAdES、PDF/A-4、HSM）。
专用服务器 + RoadRunner
RoadRunner Core Artisan Pro Laravel最大吞吐量。4 Workers 可达 9,000+ docs/s。
Kubernetes / Docker
RoadRunner Core Artisan Pro
Symfony水平扩展。RoadRunner 作为 Worker 进程。生产级部署。
性能：标准 PHP-FPM vs RoadRunner
RoadRunner 将您的 PHP 应用程序保留在内存中作为持久化工作进程，消除冷启动并大幅提升吞吐量。
标准 PHP-FPM vs RoadRunner
▲ 越高越好PHP 8.5.3 + OPcache + JIT · Docker 4 CPUs / 16 GB · i9-13900K · 20 次中位数
何时使用 RoadRunner
当您需要高吞吐量（每分钟数百个 PDF）或低延迟（亚毫秒级响应时间）时，建议使用 RoadRunner。对于每次请求只生成少量 PDF 的典型 Web 应用程序，标准 PHP-FPM 完全足够。
用例决策矩阵
针对您的特定用例，应该安装哪些包？
| 使用场景 | Core | Artisan | Pro | Laravel | Symfony |  CI4 |  Adaptation |
|---|---|---|---|---|---|---|---|
| 发票与报表生成 | ✅ | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ | — |
| 电商（HTML→PDF） | ✅ | ✅ | ⚪ | ⚪ | ⚪ | ⚪ | — |
| 无障碍文档（PDF/UA） | ✅ | — | ✅ | ⚪ | ⚪ | ⚪ | — |
| 数字签名（PAdES） | ✅ | — | ✅ | ⚪ | ⚪ | ⚪ | — |
| 旧版 TCPDF 迁移 | ✅ | ⚪ | — | ⚪ | ⚪ | ⚪ | ✅ |
| 高吞吐量 API | ✅ | ⚪ | ⚪ | ✅ | ✅ | ⚪ | — |
| 归档合规（PDF/A-4） | ✅ | — | ✅ | ⚪ | ⚪ | ⚪ | — |
| 大量条码文档 | ✅ | — | ⚪ | ⚪ | ⚪ | ⚪ | — |
包兼容性
大多数包可以无缝搭配使用，但有一个例外：
| 组合 | 兼容 | 备注 |
|---|---|---|
| Core + 任何包 | 是 | Core 是必需的基础包 |
| Artisan + 任何框架 | 是 | Chrome CDP 适用于所有框架 |
| Pro + Laravel/Symfony/CI | 是 | 在任何框架中都能使用完整的企业级功能 |
| Pro + Adaptation | 否 | Adaptation 封装了旧版 TCPDF API；Pro 扩展了现代 TCPDF-Next API。请选择其中一种方式。 |
| Adaptation + 框架 | 是 | 使用 Adaptation 在您的框架中迁移旧版代码 |
CJK 与字体注意事项
内置的 Basic 14 字体（Helvetica、Times、Courier 等）仅支持拉丁字符。如果您的文档需要中文、日文或韩文文字，您必须：
- 嵌入 TrueType 字体 — 使用
setFont()搭配支持您所需字符集的 TTF 字体 - 配置字体路径 — 设置
TCPDF_FONTS_DIR环境变量或使用配置 API - 考虑文件大小 — CJK 字体通常每个 5-15 MB；使用字体子集化来减小 PDF 大小
// 示例：使用 CJK 字体
$pdf = Document::createStandalone()
->addPage()
->setFont('/path/to/NotoSansCJK-Regular.ttf', '', 12)
->cell(0, 10, '你好世界 こんにちは 안녕하세요');推荐的 CJK 字体
- Noto Sans CJK — Google 的开源 CJK 字体家族（免费）
- Source Han Sans — Adobe 的同等产品（免费）
- 两者都在单一字体文件中支持简体中文、繁体中文、日文和韩文。
共享主机限制
在共享主机上，您通常无法：
- 安装 Chrome/Chromium（无法使用 Artisan 包）
- 运行长期运行的进程（无法使用 RoadRunner）
- 安装 PHP 扩展（仅限主机提供的部分）
共享主机的推荐配置：
composer require yeeefang/tcpdf-next仅使用 Core 搭配内置的 HTML 解析器来满足基本的 HTML 转 PDF 需求。如果需要像素级精确的 HTML 渲染，建议升级到 VPS。
下一步
- 快速入门 — 安装并创建您的第一个 PDF
- 安装指南 — 所有包的详细安装说明
- 性能基准测试 — 完整的性能比较数据
- 从 TCPDF 迁移 — 逐步迁移指南