必须手动在public/index.php顶部注册Whoops实例：引入autoload.php后，实例化Whoops\Run、添加PrettyPageHandler并调用register()，且仅限APP_DEBUG=true环境启用，同时确保无前置输出、错误级别匹配、无其他错误处理器覆盖。
Webman 项目里装了 filp/whoops 却没出现美化错误页？不是安装错了，是它根本没被注册为错误处理器——Webman 不像 Laravel 那样自动集成 Whoops，必须手动接管错误流，且时机、位置、环境缺一不可。
Webman 入口文件顶部必须注册 Whoops 实例
Webman 的错误处理完全依赖 PHP 原生错误机制，Whoops\Run 不会自动生效。你得在 public/index.php（或 start.php，取决于启动方式）最开头、任何输出之前完成三件事：
- 确保已加载
vendor/autoload.php（否则Class 'Whoops\Run' not found） - 实例化
Whoops\Run并 pushWhoops\Handler\PrettyPageHandler - 立即调用
register()，且不能晚于Webman\App::run()或路由初始化
正确写法示例（放在 public/index.php 第一行业务代码处）：
require __DIR__ . '/../vendor/autoload.php';
if (env('APP_DEBUG', true)) {
$whoops = new \Whoops\Run();
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler());
$whoops->register();
}
// 后续才是 Webman 启动逻辑
$app = new \Webman\App(__DIR__);
$app->run();
Webman 的 APP_DEBUG 和 PHP 错误级别必须匹配
Webman 默认只在 APP_DEBUG=true 时启用调试行为，但即使开了 debug，若 PHP 没开启对应错误报告，Whoops 也收不到通知。常见失效场景：
立即学习“PHP免费学习笔记（深入）”；
-
error_reporting被设为0或E_ALL & ~E_NOTICE，导致E_NOTICE类错误（如未定义变量）被忽略 - 入口文件中存在
@抑制符，直接跳过错误回调 - Webman 自身的异常处理器（如
app/exception/ExceptionHandler）提前捕获并渲染了错误，Whoops 失去接管机会
建议在注册 Whoops 后显式加固错误级别：
$whoops->handleError(E_ALL);
$whoops->handleException(E_ALL);
ini_set('display_errors', '1');
error_reporting(E_ALL);
Webman 中 Whoops 页面空白或 CSS/JS 加载失败
Whoops 的 PrettyPageHandler 输出的是完整 HTML 页面，但它不走静态资源路由，所有样式和脚本都以内联方式注入。一旦响应头已发送或输出缓冲混乱，页面就会降级为纯文本甚至白屏。
- 检查
public/index.php文件开头是否有 BOM、空格、UTF-8 签名或echo/print语句 - 确认没在 Whoops 注册前调用
ob_start()，或调用后未正确清理（Webman 默认不开启输出缓冲，但中间件可能触发） - 某些 Webman 插件（如日志中间件、响应拦截器）会在 Whoops 渲染前写入响应体，导致 headers already sent
- CLI 启动（
php start.php start -d）下PrettyPageHandler不生效——它只针对 Web SAPI；CLI 场景应改用Whoops\Handler\PlainTextHandler
Webman + Whoops 在视图层出错时仍可能失效
Webman 的视图渲染（如 view()）通常发生在响应已开始输出之后。此时 Whoops 无法替换整个 HTML 页面，只会输出片段，造成“半截错误页”或混杂警告。
- 避免在模板中直接访问未定义变量（如
$user->name），这类E_NOTICE很容易被忽略或截断 - 把关键数据校验提到控制器层，用
isset()或 nullsafe 操作符预检，不让错误落到视图 - 临时调试时可关闭视图缓存和自动缓冲：在
config/view.php中设'cache_path' => false，并确认没启用ob_start()类中间件
真正卡点不在安装，而在 Whoops 是否成为第一个、且唯一一个注册的错误处理器——Webman 没有“异常中间件”概念，谁先 set_error_handler，谁就掌控全局。稍有错位，就退回原始报错。
