装filp/whoops不会自动接管错误，必须手动注册Whoops\Run为错误处理器，否则仍白屏；正确安装命令是composer require filp/whoops --dev，且需在入口文件顶部、任何输出前调用$whoops->register()。
装 filp/whoops 不等于错误页面就变漂亮了——它根本不会自动接管 PHP 错误，必须手动注册 Whoops\Run 为错误处理器，否则还是白屏或原始 Parse error。
composer require 命令必须用对包名
旧文档里写的 whoops/whoops 已废弃，现在唯一正确的安装命令是：
composer require filp/whoops --dev
加 --dev 是因为 Whoops 只用于开发环境，上线后应禁用；这条命令会把代码下载到 vendor/filp/whoops/，写入 composer.json 的 require-dev 区，并更新自动加载映射。如果漏掉 --dev，虽不影响功能，但语义不清、易被误部署到生产环境。
立即学习“PHP免费学习笔记（深入）”；
- PHP 版本需为 7.4–8.2；8.3 尚未正式支持，部分错误（如
UnhandledMatchError）可能不触发 Whoops - 若项目用了自定义 autoloader 或禁用了 PSR-4 自动发现，需确认
composer dump-autoload成功执行 - 别用
composer global require—— 路径混乱、版本难控、类找不到风险高
入口文件顶部必须手动注册 Run 实例
Composer 安装完只是把代码放进来，Whoops\Run::register() 必须显式调用，且时机极其关键：必须在任何业务逻辑、框架启动、DB 连接、甚至 echo 之前执行。
典型正确写法（裸 PHP 项目，public/index.php 开头）：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
require __DIR__ . '/../vendor/autoload.php'; $whoops = new \Whoops\Run(); $whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler()); $whoops->register(); // ✅ 此时才开始加载路由、中间件、数据库等 require '../app/bootstrap.php';
- 如果报
Class 'Whoops\Run' not found，说明autoload.php没引入，或引入位置晚于 Whoops 初始化 - 如果页面没变化 / 仍是原始 PHP 错误，大概率是框架（如 Laravel）已提前注册异常处理器，覆盖了 Whoops —— 它们互斥，不能共存
- 某些 SAPI（如 IIS FastCGI）对长 HTML 响应支持差，会截断 Whoops 页面；Apache/Nginx 若配置了
fastcgi_buffering off，也可能导致渲染失败
Laravel 中启用 Whoops 需绕过 Ignition
Laravel 5.5+ 默认使用 spatie/laravel-ignition，它和 Whoops 冲突，即使 composer require filp/whoops 成功也不会生效。
真要换，必须：
- 删掉 ignition：
composer remove spatie/laravel-ignition - 清缓存：
php artisan config:clear - 在
public/index.php顶部、require_once __DIR__.'/../vendor/autoload.php';之后、$kernel =之前插入初始化代码 - 或改写
App\Exceptions\Handler::render()，用$whoops->handleException($e)构造响应，但要注意PrettyPageHandler可能拿不到request对象，导致Call to a member function getMethod() on null
注意：Laravel 10+ 默认不加载 filp/whoops，即使安装成功，也得自己写注册逻辑。
常见失效原因：headers already sent 或 error_reporting 被关
Whoops 的美化页面依赖内联 CSS/JS，但它靠 PHP 直接输出完整 HTML。一旦 headers 已发送，它就会降级为纯文本，甚至完全不显示。
最常见诱因：
- 入口文件顶部有 UTF-8 BOM、空格、
echo、print或提前require了带输出的文件 - 项目中设置了
error_reporting(0)或用了@抑制错误，Whoops 根本收不到异常 - 用了输出缓冲但没清理干净，比如
ob_start()后没ob_end_flush() - CLI 脚本下默认不渲染 HTML —— 要用
PlainTextHandler，而不是PrettyPageHandler
Whoops 看似简单，但生效链路很脆弱：Composer 安装只是起点，注册时机、环境判断、输出控制、SAPI 兼容性，缺一不可。最容易被忽略的是——它根本不关心你有没有装包，只看你有没有在对的地方、对的时间、调用对的那行 register()。
