如何在 PHP 中通过Composer安装 Whoops 库优化错误异常的显示界面-composer-PHP中文网

装filp/whoops不会自动接管错误，必须手动注册whoops\run为错误处理器，否则仍白屏；正确安装命令是composer require filp/whoops --dev，且需在入口文件顶部、任何输出前调用$whoops->register()。

如何在 php 中通过composer安装 whoops 库优化错误异常的显示界面

装 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 版本需为 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 开头）：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(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