errorAction 路由必须在 urlManager 配置之前定义，否则解析失败导致白屏或500错误；error-404.php、error-500.php、error.php 须严格按大小写和路径存放；API请求应拦截并返回JSON错误，而非HTML页面。
errorAction 路由必须能被正确解析
Yii2 的 errorHandler 组件依赖路由系统分发错误请求，所以 'errorAction' => 'site/error' 这个配置**必须放在 'urlManager' 配置之前**。否则框架在解析 errorAction 时找不到对应控制器动作，最终返回空白页或 500 错误，而不是你写的 error.php。
常见错误现象：页面白屏、Network 面板看到 500 但没日志、$exception 在视图里是 null。
- 检查
/config/web.php中components数组顺序，确认errorHandler在urlManager前 - 若用了自定义控制器（如
ErrorController），errorAction必须写成'error/error'，且该控制器需继承yii\web\Controller - 不要在
SiteController里手写actionError()方法——复用yii\web\ErrorAction类才是标准做法
error-404.php 和 error-500.php 文件名大小写敏感
Yii2 的 yii\web\ErrorAction 会根据异常类型自动匹配视图文件：yii\web\NotFoundHttpException → error-404.php，其他未捕获异常（含 yii\base\Exception）→ error-500.php。匹配失败就回退到 error.php，但前提是这三个文件**严格按大小写命名、放在 /views/site/ 下**。
容易踩的坑：写成 Error-404.php 或 error404.php，Linux 服务器直接 404；或者漏掉 error.php 导致某些异常无兜底视图。
- 必须存在的三个文件：
error.php、error-404.php、error-500.php - 文件名中短横线
-不可省略，数字不可用下划线替代 - 视图中通过
$exception->getMessage()获取提示文字，但生产环境禁止输出$exception->getTraceAsString()
API 请求不能依赖默认 errorAction 渲染 HTML 页面
当请求头带 X-Requested-With: XMLHttpRequest 或 Accept: application/json 时，返回 HTML 错误页毫无意义。此时应绕过 yii\web\ErrorHandler 的视图渲染逻辑，直接输出 JSON 格式错误响应。
最稳妥的做法是在 bootstrap 或 beforeAction 中拦截判断，而非修改全局 responseFormat ——后者只影响正常响应，不接管异常流。
- 在
SiteController::beforeAction()中加判断：if (Yii::$app->request->getIsAjax() || Yii::$app->request->getIsJson()) { throw new \Exception('API error'); } - 配合自定义
ExceptionHandler类重写renderException()，统一返回{"code":500,"message":"..."} - 别用
Yii::$app->response->format = Response::FORMAT_JSON全局设置，它对异常无效
YII_DEBUG 关闭后仍显示堆栈信息？检查 maxSourceLines 配置
maxSourceLines 和 maxTraceString 控制错误页中源码上下文和调用栈的显示长度，但它们**只在 YII_DEBUG === true 时生效**。一旦 YII_DEBUG = false，即使设了 maxSourceLines => 0，也不会显示源码——但很多人误以为这是配置没起作用。
真正影响生产环境提示内容的是视图文件本身：error-500.php 里是否写了 $exception->getTraceAsString()，这个调用在生产环境必须删掉或包裹 if (YII_DEBUG) 判断。
-
maxSourceLines默认值是 20，调试时够用；线上建议保持默认，靠视图层控制输出 - 检查
/runtime/logs/app.log是否有异常记录——如果日志有但页面没提示，说明是视图层没取到$exception或被 PHP 错误屏蔽 - PHP 致命错误（如 Parse Error）不会触发
errorAction，需靠register_shutdown_function补充捕获
实际项目里最容易被忽略的，是 API 和 Web 页面共存时对同一套 errorHandler 的“误用”——不是所有异常都该走视图渲染，也不是所有 JSON 响应都要塞进 errorAction。分清场景，手动干预时机，比堆配置重要得多。
