Whoops 库需通过 composer require filp/whoops 显式安装并手动注册错误处理器：引入 autoload.php 后实例化 Whoops\Run，添加 PrettyPageHandler 并调用 register()，且仅限开发环境启用。
Whoops 库不能直接通过 composer install 安装——它必须显式声明为项目依赖，且需配合错误处理器手动启用。
用 composer require 添加 Whoops 到项目
Whoops 是一个独立的 PHP 错误处理库，不随 Composer 自带，必须主动引入：
- 运行
composer require filp/whoops（注意不是whoops/whoops，旧包名已弃用） - 该命令会写入
composer.json的require区，并安装到vendor/filp/whoops - 如果项目启用了自动加载（如 Laravel、Symfony 或标准 PSR-4 配置），无需额外注册类路径
手动注册 Whoops 错误处理器（非框架环境）
Composer 安装完只是把代码放进来，Whoops 不会自动接管错误——必须在入口文件（如 index.php）顶部手动激活：
- 确保
vendor/autoload.php已引入 - 实例化
Whoops\Run并调用register() - 添加
PrettyPageHandler才能显示带代码高亮、请求信息的“优雅页面”
require __DIR__ . '/vendor/autoload.php'; $whoops = new \Whoops\Run(); $whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler()); $whoops->register();
Laravel 中禁用默认异常页、改用 Whoops
Laravel 9+ 默认使用 ignition，会和 Whoops 冲突；若坚持用 Whoops，需绕过框架异常处理流程：
- 在
public/index.php顶部（require __DIR__.'/../vendor/autoload.php'之后、Kernel启动之前）插入 Whoops 初始化代码 - 不要在
App\Exceptions\Handler中尝试接管——Laravel 的异常捕获发生在 Whoops 注册之后，会失效 -
开发环境可临时禁用 ignition：设置
IGNITION_ENABLED=false环境变量，或删除spatie/laravel-ignition
常见失败原因：404 页面、空白页、或报 Class not found
Whoops 配置失败通常不是安装问题，而是执行时机或作用域出错：
-
Class 'Whoops\Run' not found：autoload 未生效，检查是否漏了require vendor/autoload.php - 页面没变化 / 仍是 PHP 原生错误：Whoops 被后加载的异常处理器覆盖（例如 Laravel 的
App\Exceptions\Handler或其他中间件） - PrettyPage 显示不全（无代码、无请求数据）：未调用
$handler->setRequest($_SERVER)或setRequestBody($_POST)，但PrettyPageHandler默认会尝试读取，一般无需手动设 - 线上环境意外启用：Whoops 必须只在
APP_DEBUG=true时注册，否则敏感信息可能泄露
Whoops 的核心逻辑其实就三行初始化代码，但它的生效高度依赖加载顺序和错误触发时机——很多问题不是配错了，而是它根本没来得及注册就被框架拦截了。
