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 vendo

  

  r/autoload.php
• 页面没变化 / 仍是 PHP 原生错误：Whoops 被后加载的异常处理器覆盖（例如 Laravel 的 App\Exceptions\Handler 或其他中间件）
• PrettyPage 显示不全（无代码、无请求数据）：未调用 $handler->setRequest($_SERVER) 或 setRequestBody($_POST)，但 PrettyPageHandler 默认会尝试读取，一般无需手动设
• 线上环境意外启用：Whoops 必须只在 APP_DEBUG=true 时注册，否则敏感信息可能泄露

Whoops 的核心逻辑其实就三行初始化代码，但它的生效高度依赖加载顺序和错误触发时机——很多问题不是配错了，而是它根本没来得及注册就被框架拦截了。