Yii 2: The Fast, Secure and Professional PHP Framework 错误页面定制：提升用户体验

冯梦姬Eddie

468人浏览 · 2025-10-12 07:35:21

冯梦姬Eddie · 2025-10-12 07:35:21 发布

Yii 2: The Fast, Secure and Professional PHP Framework 错误页面定制：提升用户体验

【免费下载链接】yii2 Yii 2: The Fast, Secure and Professional PHP Framework 项目地址: https://gitcode.com/gh_mirrors/yi/yii2

当用户在访问网站时遇到错误，一个设计良好的错误页面不仅能减轻用户的挫败感，还能引导用户继续浏览或提供有效的帮助信息。Yii 2 框架提供了灵活的错误处理机制，允许开发者轻松定制错误页面，从而提升整体用户体验。本文将详细介绍如何在 Yii 2 中定制错误页面，包括错误处理器配置、自定义视图以及错误动作的使用。

错误处理基础

Yii 2 内置了一个强大的错误处理器 [[yii\web\ErrorHandler|error handler]]，它负责将 PHP 错误转换为异常、显示错误信息以及提供调试支持。错误处理器默认启用，可以通过修改应用配置来自定义其行为。

官方文档中详细介绍了错误处理器的工作原理和基本配置，你可以参考 docs/guide-zh-CN/runtime-handling-errors.md 获取更多信息。

错误处理器主要完成以下工作：

将所有非致命 PHP 错误（如警告、提示）转换为可捕获的异常
在调试模式下显示详细的错误信息和调用栈
支持使用自定义控制器动作显示错误
支持不同的错误响应格式

自定义错误显示

Yii 2 的错误处理器根据 YII_DEBUG 常量的值来决定错误显示的详细程度。当 YII_DEBUG 为 true 时，会显示包含调用栈的详细错误信息；当为 false 时，只显示简单的错误信息以避免泄露敏感信息。

错误视图文件

错误处理器默认使用两个视图文件来显示错误：

@yii/views/errorHandler/error.php: 用于显示不包含调用栈的简单错误信息
@yii/views/errorHandler/exception.php: 用于显示包含调用栈的详细错误信息

你可以通过配置错误处理器的 errorView 和 exceptionView 属性来自定义这些视图文件：

return [
    'components' => [
        'errorHandler' => [
            'errorView' => '@app/views/error/error.php',
            'exceptionView' => '@app/views/error/exception.php',
        ],
    ],
];

使用错误动作

除了直接自定义视图文件，Yii 2 还允许你使用指定的控制器动作来处理错误显示。这种方式更加灵活，便于集成到应用的整体架构中。

首先，在应用配置中设置错误处理器的 errorAction 属性：

return [
    'components' => [
        'errorHandler' => [
            'errorAction' => 'site/error',
        ],
    ]
];

然后，在 SiteController 中定义 error 动作。你可以直接使用 Yii 提供的 [[yii\web\ErrorAction]] 类，或者自定义动作方法：

namespace app\controllers;

use Yii;
use yii\web\Controller;

class SiteController extends Controller
{
    public function actions()
    {
        return [
            'error' => [
                'class' => 'yii\web\ErrorAction',
            ],
        ];
    }
}

或者自定义动作方法：

public function actionError()
{
    $exception = Yii::$app->errorHandler->exception;
    if ($exception !== null) {
        return $this->render('error', ['exception' => $exception]);
    }
}

接下来，创建对应的视图文件 views/site/error.php。在该视图中，你可以访问以下变量：

name: 错误名称
message: 错误信息
exception: 异常对象，包含 HTTP 状态码、错误码等详细信息

错误页面设计最佳实践

一个好的错误页面应该具备以下特点：

清晰地告知用户发生了什么错误
提供有用的导航选项，帮助用户回到正常流程
保持与网站整体风格一致的设计
对于 404 等常见错误，提供搜索功能或热门链接

404 错误页面示例

下面是一个自定义 404 错误页面的示例视图文件：

<?php
use yii\helpers\Html;

$this->title = '页面未找到';
?>
<div class="site-error">
    <h1><?= Html::encode($this->title) ?></h1>
    <div class="alert alert-danger">
        <?= Html::encode($message) ?>
    </div>
    <p>
        您请求的页面不存在。可能是由于以下原因：
    </p>
    <ul>
        <li>URL 输入错误</li>
        <li>页面已被删除</li>
        <li>链接已过期</li>
    </ul>
    <p>
        请尝试以下操作：
    </p>
    <ul>
        <li>检查 URL 拼写</li>
        <li>返回 <?= Html::a('首页', Yii::$app->homeUrl) ?></li>
        <li>使用网站 <?= Html::a('搜索功能', ['site/search']) ?></li>
    </ul>
</div>

错误页面设计示例

下面是一个设计精美的错误页面示意图，展示了如何将错误信息与用户引导相结合：

这个示例展示了 Yii 2 应用安装成功后的欢迎页面，但设计理念同样适用于错误页面：清晰的标题、简洁的说明文字、明确的操作指引。

高级自定义：响应格式与重定向

Yii 2 的错误处理器支持根据响应格式（如 HTML、JSON、XML）来显示不同的错误信息。你可以通过配置 response 组件来自定义错误响应格式。

例如，将 JSON 错误响应格式化为统一的结构：

return [
    'components' => [
        'response' => [
            'class' => 'yii\web\Response',
            'on beforeSend' => function ($event) {
                $response = $event->sender;
                if ($response->data !== null && !$response->isSuccessful) {
                    $response->data = [
                        'success' => false,
                        'error' => [
                            'code' => $response->statusCode,
                            'message' => $response->data['message'],
                        ],
                    ];
                }
            },
        ],
    ],
];

如果需要在发生特定错误时重定向用户，可以在错误动作中添加重定向逻辑：

public function actionError()
{
    $exception = Yii::$app->errorHandler->exception;
    if ($exception instanceof \yii\web\NotFoundHttpException) {
        // 重定向到搜索页面
        return $this->redirect(['site/search']);
    }
    // 其他错误处理逻辑
}