Yii2 REST API使用Postman携带auth key调用接口返回401未授权问题

高优先级排查项（XAMPP环境90%的问题集中在前两项） #

• 校验Authorization头是否真正传到PHP层
  不要只改.htaccess就默认规则生效，XAMPP的Apache默认配置经常覆盖目录级规则。首先打开Apache的httpd.conf，找到你项目对应目录的配置块，确认AllowOverride参数值为All，否则.htaccess里写的所有转发规则都不会执行。
  直接在项目入口文件web/index.php最开头加调试代码：

  var_dump($_SERVER);die;
  

  发起业务接口请求，查看输出的SERVER数组：
  • 如果找不到HTTP_AUTHORIZATION和REDIRECT_HTTP_AUTHORIZATION字段，说明Apache层直接吃掉了Authorization头，要么是mod_security模块拦截，要么是重写规则配置错误，和业务代码无关。
  • 如果能找到REDIRECT_HTTP_AUTHORIZATION但没有HTTP_AUTHORIZATION，直接在入口文件最开头加如下代码手动补全头信息，比.htaccess规则稳定：

    if (isset($_SERVER['REDIRECT_HTTP_AUTHORIZATION'])) {
        $_SERVER['HTTP_AUTHORIZATION'] = $_SERVER['REDIRECT_HTTP_AUTHORIZATION'];
    }
    

• 校验自定义认证类的逻辑正确性
  首先确认你继承的HttpHeaderAuth基类实现了yii\filters\auth\AuthInterface接口，再逐行核对认证逻辑：
  1. 提取令牌时，必须匹配Authorization: Bearer {auth_key}格式，注意Bearer后有半角空格，前缀大小写错误、漏写前缀、多传隐式空格/换行都会导致令牌提取失败。
  2. 打印提取到的令牌值，和用户表存储的auth_key做精确比对：确认auth_key字段长度足够（建议设为varchar(64)以上），存储时没有被截断，查询时没有附加多余过滤条件（比如判断用户状态为激活、未删除等条件意外过滤掉了对应用户）。
  3. 确认认证逻辑找不到对应用户时返回null即可，不要提前抛出其他异常打断框架认证流程。

次优先级排查项 #

• 校验控制器行为配置
  1. 检查BaseController重写behaviors()方法时，有没有调用parent::behaviors()合并父类配置，避免认证器没有正确挂载。
  2. 检查authenticator过滤器的only/except配置，确认需要认证的业务接口没有被加入免认证白名单；同时确认没有挂载多个冲突的认证方式（比如同时开启HttpBasicAuth、QueryParamAuth），多认证器按顺序执行，前一个认证失败会直接返回401，不会走后续Bearer认证逻辑。
  3. 确认配置的user应用组件符合REST场景要求：identityClass正确绑定到你的User模型类，enableSession设为false，否则框架会优先从session读取用户身份，读不到就直接返回401，不会执行token校验逻辑。
• 校验传参方式正确性
  HttpBearerAuth仅从Authorization请求头读取令牌，不要在请求Body、URL参数里传auth key，这些位置的参数不会被Bearer认证器识别。Postman正确传参方式：选择Authorization标签，类型选Bearer Token，将auth key填入Token输入框即可；可以打开Postman自带的请求控制台，查看实际发出的请求头，确认Authorization头格式正确。
• 校验基础配置残留
  二次确认REST模块的request组件配置中enableCookieValidation设为false，控制器层面$enableCsrfValidation设为false，避免框架优先校验Cookie/CSRF令牌，跳过token认证流程。

快速定位技巧 #

可以暂时注释掉自定义的认证类，换成Yii2原生yii\filters\auth\HttpBearerAuth，同时在User模型中实现最简单的身份查找逻辑：

public static function findIdentityByAccessToken($token, $type = null)
{
    return static::findOne(['auth_key' => $token]);
}

如果原生逻辑可以正常通过认证，说明问题出在自定义认证类的代码逻辑；如果原生逻辑依然返回401，说明问题出在Apache环境、组件配置层面。

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