Yii框架本身不提供PDF内容提取功能，实际依赖第三方库（如smalot/pdfparser），提取失败主因是路径非绝对、权限不足、PDF加密/扫描、PHP扩展缺失或编码处理不当。
Yii框架本身不提供PDF内容提取功能，实际依赖第三方库（如smalot/pdfparser、setasign/fpdi或spipu/html2pdf等），提取失败通常不是Yii的问题，而是底层解析库的使用方式或环境配置不当所致。
文件路径不可读或权限不足
PHP进程必须能以文件系统方式读取PDF文件，不能用Web URL（如http://example.com/file.pdf）直接传给解析器。常见错误是误用@web别名拼接路径，结果传入的是HTTP地址而非绝对磁盘路径。
- 正确做法：用
Yii::getAlias('@webroot') . '/uploads/report.pdf'生成真实路径 - 务必在调用解析前检查：
is_file($path) && is_readable($path) - Linux服务器注意PHP运行用户（如
www-data）是否对文件有读权限
PDF格式受保护或结构异常
加密PDF、扫描版PDF（纯图片无文字层）、或含非标准字体嵌入的PDF，会导致文本提取为空或乱码。
- 用命令行工具
pdfinfo file.pdf查看是否标记为“encrypted” - 用
pdftotext -layout file.pdf -测试原生提取效果，若也失败，说明问题在PDF本身 - 扫描件需先OCR（如Tesseract），Yii中可调用shell命令或集成
thiagoalessio/tesseract_ocr
解析库未正确加载或缺少扩展
很多PDF解析器依赖PHP扩展，例如mbstring、xml、iconv，部分还要求gmp或openssl。
- 运行
php -m | grep -E "(mbstring|xml|iconv|gmp|openssl)"确认已启用 - 使用
smalot/pdfparser时，若PDF含JavaScript或XFA表单，它会静默跳过——这不是Bug，是设计限制 - Composer安装后记得清空Yii缓存：
./yii cache/flush-all
编码与字符集处理不当
中文PDF常因字体映射缺失或编码声明混乱，导致提取出的文本是空格、方块或乱码（如）。
- 避免直接
echo $text调试，改用var_dump(bin2hex($text))看原始字节 - 尝试强制UTF-8转换：
mb_convert_encoding($text, 'UTF-8', 'auto') - 某些库（如
setasign/fpdi）仅支持元数据读取，不支持正文提取——要看清文档定位
