结论：安装 dompdf 必须用 composer require dompdf/dompdf，而非 install；php

直接说结论：用 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 分支。

这不是网络问题，是版本约束冲突。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

• 先确认版本：php -v
• PHP 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 远程加载。所有字体路径必须是本地可读的绝对路径，且注册和使用必须完全一致。