结论：安装 dompdf 必须用 composer require dompdf/dompdf，而非 install；PHP < 8.0 需指定 ^1.4 版本；需启用 mbstring/gd 扩展、正确引入 autoload、注册中文字体并确保路径一致。
直接说结论：用 composer require dompdf/dompdf，不是 composer install dompdf/dompdf —— 后者必然报错，因为 install 命令根本不接受包名参数。
为什么 composer install dompdf 会失败
这是最常卡住的第一步。composer install 的作用只是读取当前目录下的 composer.json，安装里面已声明的依赖。它没有“加新包”的能力。
你输 composer install dompdf/dompdf，Composer 会把它当成一个叫 install 的未知命令来解析，报错类似：Unknown command "install" 或 Could not find a composer.json file。
- 想加新包 → 必须用
composer require dompdf/dompdf - 项目还没初始化 Composer？没关系，
require会自动创建composer.json和vendor/ - 国内用户建议提前配置镜像源，否则可能卡在下载
phenx/php-font-lib上
PHP 版本不匹配导致 dompdf/dompdf 安装失败
DOMPDF v2.0+（当前默认）要求 PHP ≥ 8.0。如果你用的是 PHP 7.4 或更低版本，composer require dompdf/dompdf 会提示找不到包，或拉到一个不兼容的 dev 分支。
这不是网络问题，是版本约束冲突。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 先确认版本：
php -v - PHP < 8.0？强制指定旧版：
composer require dompdf/dompdf:^1.4 - 避免用
:dev-main或:dev-develop，这些分支不稳定，容易导致Class 'Dompdf\Dompdf' not found - v1.4 仍需
mbstring和gd扩展，但对 PHP 7.2+ 兼容性更好
装完后 new Dompdf() 报 Class 'Dompdf\Dompdf' not found
不是类名写错了，99% 是加载链断了。
DOMPDF 是库，不是命令行工具 —— 它不会自动注册命名空间，也不会自己找 autoload。你得手动搭好这根线。
- 必须
require 'vendor/autoload.php'（注意路径是否正确） - 必须写
use Dompdf\Dompdf;（大小写敏感，不能是DOMPDF或dompdf\Dompdf） - v2+ 版本推荐显式传入选项数组，否则某些环境（如 CLI 或无 web server 的调试）会静默失败：
$dompdf = new Dompdf(['enable_remote' => false]); - 检查
composer.json中的"autoload"段是否被误删或格式错误，尤其是 PSR-4 配置
中文乱码、字体缺失、PDF 空白或报 Failed to load PDF document
这类问题几乎都和输出污染或字体未注册有关。DOMPDF 默认只认英文，且对中文字体路径极其敏感。
浏览器报 PDF 加载失败？大概率是 PHP 输出了 warning 或 notice（比如 mbstring 未启用），把 PDF 二进制流开头污染了。
- 临时验证：在
render()前加ob_clean(); flush(); - 真正解法：确保
mbstring和gd已启用（php -m | grep -E 'mbstring|gd'） - 中文字体必须手动注册：放一个
.ttc或.otf文件（如NotoSansCJKsc-Regular.otf）到项目fonts/目录，再调用$dompdf->getFontMetrics()->registerFont([...]) - CSS 中必须用注册时指定的
family名，font-family: 'SimSun'有效，font-family: 'Microsoft YaHei'无效
DOMPDF 不解析系统字体，也不支持 @font-face 远程加载。所有字体路径必须是本地可读的绝对路径，且注册和使用必须完全一致。
