auth:sanctum中间件返回401的主因是认证路径错配：前端域名未列入SANCTUM_STATEFUL_DOMAINS、缺少Authorization: Bearer token或withCredentials:true、EnsureFrontendRequestsAreStateful未正确注册，或误用auth:api而非auth:sanctum。
auth:sanctum 中间件不生效，基本就是没走对认证路径——它不会静默失败，而是直接 401，但原因往往藏在请求头、域名配置或中间件注册里。
为什么 auth:sanctum 总是返回 401？
Sanctum 的认证流程是「先查 Cookie，再查 Bearer Token」，但这个顺序只在特定条件下触发。常见失效场景包括：
- 前端请求域名不在
SANCTUM_STATEFUL_DOMAINS列表中（比如前端跑在http://localhost:3000，但环境变量只写了localhost，漏了端口或协议） -
EnsureFrontendRequestsAreStateful中间件没注册到api中间件组，或被错误地放在了web组里 - 请求没带
Authorization: Bearer xxx，又没带有效 session cookie（比如跨域未配withCredentials: true） - 使用了
auth:api而不是auth:sanctum，而apiguard 在config/auth.php里仍指向token驱动
createToken() 返回空或报错 Object of class Laravel\Sanctum\NewAccessToken could not be converted to string
这是最常踩的坑：你调用了 $user->createToken('login')，但没取 plainTextToken 属性就直接返回了整个对象。
- 正确写法：
$user->createToken('login')->plainTextToken—— 明文只出现一次，必须立刻取出 - 错误写法：
return response()->json($user->createToken('login'))，PHP 会尝试 toString，触发报错 - 别用
$user->tokens()->create()手动建记录，它绕过 Sanctum 的哈希逻辑和作用域校验 - 如果
User模型不是默认的App\Models\User（比如用了自定义模型），确保该模型也引入了HasApiTokenstrait
移动端或 CLI 请求该用 Cookie 还是 Bearer？
移动端、命令行工具、第三方服务调用等无 Cookie 上下文的场景，必须用 Bearer 方式；Cookie 方式只适用于同域或已明确信任的 SPA 前端。
- Bearer 是唯一可靠选择：客户端在每次请求头加
Authorization: Bearer <token> - 不要把 token 存 localStorage —— XSS 一击即溃；内存变量 + 登出清空是更安全的折中方案
- 如果后端强制要求 Cookie 认证（比如误配了
stateful域名），移动端请求会 fallback 失败，且不提示原因 - 检查响应头是否含
Set-Cookie: laravel_session=...—— 如果有，说明 Sanctum 正在尝试走 session 流程，这对移动端无效
如何确认当前请求到底走了哪种认证方式？
Sanctum 不暴露内部决策，但你可以通过日志或临时调试判断实际走的是 Cookie 还是 Token：
- 在路由闭包里加
dd($request->user(), $request->bearerToken(), $request->session()->getId()) - 如果
$request->user()有值但$request->bearerToken()为空，大概率是 Cookie 认证成功 - 如果
$request->bearerToken()有值但$request->user()为空，说明 token 格式不对、已过期或数据库查不到匹配记录 - 注意：token 是明文生成、密文存储，数据库里存的是哈希值，所以不能拿明文去查
personal_access_tokens表
EnsureFrontendRequestsAreStateful 放错位置，或者 SANCTUM_STATEFUL_DOMAINS 配得不精确，整个认证链就会无声断裂——它不会报错，只是默默跳过 Cookie 验证，然后因没 Bearer Token 而 401。 
