直接给出答案：使用 Composer 安装 dompdf 库，唯一正确的命令是 composer require dompdf/dompdf。如果你错误地输入了 composer install dompdf/dompdf，系统必然会报错，因为 install 命令本身并不接受具体的包名作为参数。
解析：为何执行 composer install dompdf 会出错
这是初学者最容易遇到的第一个问题。你需要明确 composer install 命令的核心作用：它仅负责读取项目根目录下的 composer.json 配置文件，并安装其中已定义的所有依赖包。这个命令不具备“添加新依赖包”的功能。
因此，当你输入 composer install dompdf/dompdf 时，Composer 会因无法识别该指令而报错，通常会提示 Unknown command "install" 或 Could not find a composer.json file。
- 如何正确添加新包？ 必须使用
composer require 包名命令。 - 项目尚未初始化 Composer？ 无需担心，
require命令会自动为你生成composer.json文件并创建vendor/目录。 - 给国内开发者的优化建议： 强烈建议预先配置 Composer 国内镜像源，以加速依赖下载，避免在拉取
phenx/php-font-lib等包时长时间等待。
PHP 版本兼容性问题导致 dompdf/dompdf 安装失败
第二个常见的障碍是 PHP 版本不兼容。DOMPDF 从 v2.0 版本起（这也是当前默认安装的最新稳定版），强制要求 PHP 版本不低于 8.0。如果你的开发环境仍在使用 PHP 7.4 或更旧的版本，直接运行 composer require dompdf/dompdf 将会失败，可能表现为找不到包或拉取到不兼容的开发分支。
这并非网络连接问题，而是版本约束条件冲突所致。
- 首先确认 PHP 版本： 在命令行中执行
php -v进行查看。 - 若 PHP 版本低于 8.0： 你需要强制指定兼容的旧版本进行安装：
composer require dompdf/dompdf:^1.4。 - 避开常见陷阱： 切勿使用
:dev-main或:dev-develop这类开发分支，它们极不稳定，极易引发后续的Class 'Dompdf\Dompdf' not found错误。 - 版本兼容性说明： v1.4 版本对 PHP 7.2+ 环境有更好的支持，但它同样依赖于
mbstring和gd这两个 PHP 扩展。
安装成功后，调用 new Dompdf() 却报错 Class 'Dompdf\Dompdf' not found
依赖包安装成功，但代码运行时提示类不存在？先别怀疑类名拼写，绝大多数情况是自动加载机制未正确生效。
DOMPDF 是一个 PHP 库，而非独立的命令行工具。它不会自动注册自己的命名空间，也不会被自动加载到内存中。你需要手动建立这个连接。
- 必须引入 Composer 自动加载文件： 在代码的起始位置，务必添加
require 'vendor/autoload.php';（请根据项目结构确认该文件的正确路径）。 - 必须使用正确的命名空间： 在类文件顶部添加
use Dompdf\Dompdf;（注意大小写敏感，DOMPDF或dompdf\Dompdf均为错误写法）。 - v2+ 版本的最佳实践： 建议在实例化时显式传入配置数组，特别是在命令行（CLI）环境或无 Web 服务器的调试场景下，可避免一些静默错误：
$dompdf = new Dompdf(['enable_remote' => false]); - 检查 composer.json 配置： 确认
composer.json文件中的"autoload"段落未被误删或格式错误，尤其是 PSR-4 自动加载规则的配置。
生成 PDF 时遇到中文乱码、字体缺失、PDF 空白或 Failed to load PDF document 错误
进入 PDF 生成阶段，问题通常源于输出缓冲区污染或字体未正确注册。DOMPDF 默认仅支持英文字体，且对中文字体文件的路径极其敏感。
浏览器直接提示“加载 PDF 文档失败”？这通常是因为 PHP 执行过程中输出了警告（Warning）或通知（Notice）信息（例如 mbstring 扩展未启用），这些文本内容污染了 PDF 二进制流的头部，导致浏览器无法识别。
- 临时验证与修复： 在调用
render()方法前，尝试使用ob_clean(); flush();清空输出缓冲区。 - 根本解决方案： 确保 PHP 已启用
mbstring和gd扩展（可通过命令php -m | grep -E 'mbstring|gd'检查）。 - 中文字体必须手动注册： 准备一个中文字体文件（如
.ttc或.otf格式的NotoSansCJKsc-Regular.otf），将其放置于项目的fonts/目录下，然后调用$dompdf->getFontMetrics()->registerFont([...])方法进行注册。 - 确保 CSS 字体名称匹配： 在 CSS 样式中，
font-family属性必须使用你注册字体时指定的family名称。例如，注册时使用了'SimSun'，CSS 中就必须写font-family: 'SimSun'，写font-family: 'Microsoft YaHei'则无效。
这里有一个关键原则：DOMPDF 不会自动解析你操作系统已安装的字体，也不支持通过 CSS 的 @font-face 规则远程加载网络字体。所有需要用到的字体，都必须提供本地可读的绝对路径文件，并且注册时使用的路径与 CSS 中引用的名称必须完全一致。
核心总结： 安装 dompdf 务必使用
composer require dompdf/dompdf命令；PHP 版本低于 8.0 需指定安装 ^1.4 版本；必须启用 mbstring 与 gd 扩展、正确引入 autoload 文件、手动注册中文字体并确保文件路径一致。
