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（比如一行中文+一张图）验证通路，再往上叠功能。
