本文介绍一种安全变通方案：当外部脚本强制要求通过 url 查询参数（如 `_token`）传递 sanctum 认证令牌时，利用自定义中间件将其注入 `authorization` 请求头，从而复用 sanctum 原生的 bearer token 验证逻辑，避免修改核心认证机制。
在标准 OAuth 2.0 和 Laravel Sanctum 最佳实践中，绝不推荐将 API Token 作为 GET 查询参数（如 /api/report?_token=abc123）传递——这会导致令牌泄露于服务器日志、代理缓存、浏览器历史及 Referer 头中，严重违背安全原则。然而，现实开发中常需对接遗留系统或第三方脚本（如某些报表生成器、嵌入式 iframe 调用），其请求方式完全不可控。此时，硬性拒绝或重构下游系统往往不现实，而应采用「最小侵入、最大复用」的设计策略。
推荐方案是：不重写 Sanctum Guard，而是通过中间件预处理请求，在进入 Sanctum 验证流程前，将查询参数中的令牌“桥接”至标准 Authorization: Bearer {token} 请求头。这样既能满足外部调用约束，又能完整复用 Sanctum 的 token 解析、数据库校验、过期检查、跨域兼容等全部安全能力。
以下是实现该方案的核心中间件代码：
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Log;
class CheckTokenAndAddToHeaderMiddleware
{
public function handle(Request $request, Closure $next): Response
{
// 仅当 _token 参数存在且非空时才注入头信息
$token = $request->query('_token');
if ($token && is_string($token) && trim($token)) {
Log::debug('Sanctum token bridged from query param', ['token_preview' => substr($token, 0, 8) . '...']);
$request->headers->set('Authorization', 'Bearer ' . $token);
}
return $next($request);
}
}✅ 关键设计说明：使用 $request->query('_token') 安全获取查询参数，避免 $_GET 或 $request->all() 引入意外字段；显式校验 $token 类型与非空性，防止空字符串或数组导致头信息污染；日志仅记录令牌前缀（如 abc123...），杜绝完整令牌落盘风险；未匹配时静默透传，不影响正常 Bearer Header 认证流程。
接下来，在 app/Http/Kernel.php 中将该中间件注册到 api 中间件组的最前端（即 Sanctum 自身中间件之前）：
protected $middlewareGroups = [
'api' => [
\App\Http\Middleware\CheckTokenAndAddToHeaderMiddleware::class,
\Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
'throttle:api',
\Illuminate\Routing\Middleware\SubstituteBindings::class,
],
];⚠️ 重要注意事项：
- 切勿在 web 组中启用此中间件，否则可能干扰 Session 登录逻辑；
- 若接口同时支持 Bearer 头和 _token 参数，当前逻辑以 _token 为准（后者会覆盖前者），如需优先级控制，可增加判断逻辑；
- 生产环境务必确保 Web 服务器（Nginx/Apache）已配置 log_not_found off; 及敏感参数过滤，防止 _token 出现在访问日志中；
- 对接外部系统时，建议同步推动对方升级为标准 Header 调用，并设定明确的迁移时间表。
该方案本质是“协议适配层”，既尊重了 Sanctum 的设计契约，又解决了现实集成瓶颈。它比自定义 Guard 更轻量、更稳定、更易维护——因为无需介入 AuthManager、Guard 实例生命周期或 user() 方法内部逻辑（$this->callback 实际指向的是 Sanctum Guard 构造时传入的闭包，用于延迟解析用户，但直接修改它反而破坏封装性）。坚持复用官方验证链路，才是长期可演进的安全之道。
