必须手动注册Whoops错误处理器才能启用漂亮错误页面，仅安装composer require filp/whoops不够；需在入口文件顶部引入autoload.php，实例化Whoops\Run并调用register()，且须置于所有业务逻辑之前。
装完 filp/whoops 不等于错误页面就变漂亮了——它根本不会自动接管 PHP 错误，必须手动注册错误处理器，否则还是白屏或原始报错。
composer require filp/whoops 是唯一正确的安装命令
旧文档里写的 whoops/whoops 已废弃，现在官方包名是 filp/whoops。运行以下命令即可：
composer require filp/whoops
这条命令会做三件事：把代码下载到 vendor/filp/whoops、写入 composer.json 的 require 区、更新自动加载映射。但注意：
-
vendor/autoload.php必须在入口文件（如index.php）最顶部被require，否则类找不到 - PHP 版本需为 7.4–8.2；8.3 尚未正式支持，部分错误（如
UnhandledMatchError）可能不触发 Whoops - 如果项目用了自定义 autoloader 或禁用了 PSR-4 自动发现，需检查
composer dump-autoload是否成功
Whoops\Run::register() 必须放在所有业务逻辑之前
这是最容易失败的环节：Whoops 不是“插件”，没有启用开关，register() 调用失败或时机不对，就等于没装。
正确写法（以裸 PHP 项目为例）：
require __DIR__ . '/vendor/autoload.php'; $whoops = new \Whoops\Run(); $handler = new \Whoops\Handler\PrettyPageHandler(); $whoops->pushHandler($handler); $whoops->register(); // 这行必须在任何 echo、header、require 业务文件之前 // ✅ 此时才开始加载框架、路由、数据库等 require 'app/bootstrap.php';
常见失效原因：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 入口文件里先写了
echo或输出了空格/UTF-8 BOM，导致 headers already sent，Whoops 渲染失败 -
error_reporting(0)或用了@抑制错误，Whoops 根本收不到异常 - 框架（如 Laravel）已提前注册了异常处理器，覆盖了 Whoops —— 它们互斥，不能共存
Laravel 中启用 Whoops 需绕过 Ignition
Laravel 5.5+ 默认用 spatie/laravel-ignition，它和 Whoops 冲突，即使 composer require filp/whoops 成功也不会生效。
若坚持用 Whoops，必须：
- 删掉 ignition：
composer remove spatie/laravel-ignition - 清缓存：
php artisan config:clear - 在
public/index.php顶部、require_once __DIR__.'/../vendor/autoload.php';之后、$kernel = ...之前插入 Whoops 初始化代码 - 确保
APP_DEBUG=true，否则 Whoops 不会渲染（线上环境绝不能开）
别试图在 App\Exceptions\Handler 里“接管”——Laravel 的异常捕获发生在 Whoops 注册之后，此时已经晚了。
页面仍是白屏或原生错误？优先检查这三处
Whoops 生效链路很脆弱，出问题基本集中在这几个点：
-
Class 'Whoops\Run' not found：确认vendor/autoload.php已require，且路径没错；检查composer.json里是否漏了"autoload": {"psr-4": {...}}配置 - 页面没变化 / 还是原始 PHP 错误：用
var_dump(set_error_handler(null));看当前错误处理器是谁，确认 Whoops 是否真被注册 - PrettyPage 显示不全（无代码、无 $_POST）：
PrettyPageHandler默认会尝试读取$_SERVER和$_POST，但若用了 Swoole、ReactPHP 等非标准 SAPI，它可能无法兼容，得换PlainTextHandler或自己实现
真正麻烦的不是安装，而是让 Whoops 在特定 SAPI、特定框架生命周期、特定错误抑制策略下稳定接住错误——它不黑盒，但每一步都得对得上。
