PHP如何用TCPDF生成PDF实战

TCPDF 初始化失败主因是自动加载未生效或字体/路径配置错误；须用Composer安装并使用完整命名空间，中文需先addTTFfont()注册再setFont()指定，writeHTML()仅支持有限内联样式且要求绝对路径和严格标签闭合。

TCPDF 初始化失败：空白页或 Fatal error

常见现象是调用 TCPDF 后直接报 Fatal error: Class 'TCPDF' not found，或者生成 PDF 是空白页、只显示“TCPDF Example”。本质是自动加载没走通，或字体/路径配置错。

实操建议：

• 确认已通过 Composer 安装：composer require tecnickcom/tcpdf，别手动下载 ZIP 放目录里——类名空间和自动加载会出问题
• 初始化必须用完整命名空间：use TCPDF\TCPDF;，然后 $pdf = new TCPDF();，不能写 new TCPDF() 前不 use
• 如果用在旧项目（无 Composer），得手动 require 所有核心文件，但强烈不推荐——tcpdf.php 依赖 tcpdf_fonts.php 和 tcpdf_static.php，漏一个就白屏
• 中文乱码或空白？默认不带中文字体。必须显式添加：先用 addTTFfont() 注册一个 .ttf 文件（如 simhei.ttf），再用 setFont() 切换，否则 writeHTML() 里的中文全丢

writeHTML() 渲染失败：样式丢失、换行异常、图片不显示

writeHTML() 看似像浏览器渲染 HTML，实际是 TCPDF 自研的轻量解析器，CSS 支持极弱，且对标签闭合敏感。很多前端写的 HTML 直接粘过去就崩。

实操建议：

• 只用内联 style，别依赖外部 CSS 或 <style> 标签；支持的属性极少：color、font-size、text-align、margin（仅 top/bottom）、padding（仅 left/right）
• <img src="xxx"> 必须是绝对路径（/var/www/html/images/logo.png），不能是 URL 或相对路径；且图片得能被 PHP 进程读取（权限、SELinux、open_basedir 限制都可能拦住）
• 避免自闭合标签：<br/> 会被忽略，必须写成 <br>；<p> 必须配 </p>，否则后续内容全乱
• 表格建议用 <table border="1"> 显式设边框，否则默认无边线；colspan/rowspan 可用，但嵌套表格大概率崩溃

中文支持踩坑：字体注册后仍显示方块或报错

TCPDF 的中文字体不是“装上就能用”，而是要走两步：注册 + 指定。很多人卡在第一步——addTTFfont() 返回空数组或抛异常，但没检查返回值就直接 setFont()，结果静默失败。

实操建议：

• 注册前先确认 .ttf 文件真实存在且可读：is_readable('/path/to/simhei.ttf')；Windows 路径别用反斜杠，统一用正斜杠或 realpath()
• addTTFfont() 第二个参数是字体类型，中文必须传 'TrueTypeUnicode'（字符串，不是常量），写错就注册失败
• 注册成功后，返回的是字体别名（如 'simhei'），之后 setFont('simhei', '', 12) 才生效；别名不等于文件名，也别加 .ttf 后缀
• 如果服务器没 GUI，某些 .ttf（尤其微软雅黑）可能因版权检测失败；换用开源字体如 wqy-zenhei.ttc 更稳

输出 PDF 到浏览器 vs 下载文件：header 冲突和缓存陷阱

用 Output('report.pdf', 'I') 在浏览器打开时，页面一片空白或弹出下载框但文件损坏，八成是 PHP 输出了额外字符（BOM、空格、调试 echo）或 header 已被发送。

实操建议：

• 确保 Output() 前没有任何输出：关闭所有 error_reporting(E_ALL) 的 warning 显示（用 ini_set('display_errors', '0')），禁用 Xdebug 的 trace 输出
• 检查文件编码：PHP 文件本身必须是 UTF-8 无 BOM，编辑器里看一眼右下角状态栏，Sublime/VSCode 默认可能带 BOM
• 如果集成在框架（如 Laravel）里，别在控制器方法末尾直接 Output()；框架可能已发过 Content-Type，得先 ob_clean() + flush()，再手动 header() 设置 Content-Type: application/pdf
• 调试时优先用 Output('report.pdf', 'F') 写入本地文件，验证内容是否正常，再切回 I 或 D

最麻烦的其实是字体路径和 HTML 闭合——这两处出错不会报明显错误，只会静默失效。建议每次改完先用最简 HTML（比如一行中文+一张图）验证通路，再往上叠功能。