Yii2请求未跳转至actionError，如何自定义401响应格式？

你遇到的问题是Yii2的errorHandler能正常处理404异常并调用自定义的actionError，但401未授权请求却返回框架默认响应，这是因为Yii的User组件默认行为会绕过你的自定义错误处理逻辑，下面是具体的解决步骤：

问题根源 #

Yii的yii\web\User组件在开启session的默认状态下，检测到未授权请求时会触发登录跳转逻辑，这个过程中抛出的UnauthorizedHttpException会被框架直接处理，不会走到你配置的errorAction。而API场景通常是无状态的，session的存在反而干扰了异常的正常捕获流程。

解决方案 #

1. 更新user组件配置，适配无状态API #

在api/config/main.php的components中修改user配置，核心是关闭session，并调整未授权的处理逻辑：

'user' => [
    'identityClass' => 'common\\models\\User',
    'enableAutoLogin' => false, // API场景不需要自动登录功能
    'enableSession' => false, // 关键：关闭session，让异常能被errorHandler捕获
    'identityCookie' => ['name' => '_identity-api', 'httpOnly' => true],
    // 可选：自定义未授权时的提示信息
    'loginRequired' => function() {
        throw new \yii\web\UnauthorizedHttpException('请提供有效的认证凭证');
    },
],

2. 确认errorHandler配置无拦截 #

你的errorHandler已经正确指定了errorAction，只需确保项目中没有自定义全局过滤器提前拦截或处理401异常，保证异常能正常流转到errorHandler。

3. 验证自定义错误响应逻辑 #

你的ApiController::actionError已经覆盖了401状态码的处理，修改后，未授权请求触发异常时，会返回你定义的JSON格式响应：

{
    "error": "Unauthorized",
    "message": "请提供有效的认证凭证"
}

补充提示 #

• API项目推荐使用无状态认证方式（如Bearer Token），配合enableSession: false更符合RESTful设计规范。
• 如果需要处理其他HTTP异常（如403禁止访问），可以在actionError的switch语句中添加对应的case分支。

内容的提问来源于stack exchange，提问作者Maarten Vermeer