LaravelSanctum怎么使用_LaravelSanctum轻量级API令牌【教程】-php教程-PHP中文网

auth:sanctum中间件返回401的主因是认证路径错配：前端域名未列入sanctum_stateful_domains、缺少authorization: bearer token或withcredentials:true、ensurefrontendrequestsarestateful未正确注册，或误用auth:api而非auth:sanctum。

laravelsanctum怎么使用_laravelsanctum轻量级api令牌【教程】

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，而 api guard 在 config/auth.php 里仍指向 token 驱动

`createToken()` 返回空或报错 `Object of class Laravel\Sanctum\NewAccessToken could not be converted to string`

这是最常踩的坑：你调用了 $user->createToken('login')，但没取 plainTextToken 属性就直接返回了整个对象。

Laravel Creem Agent

Creem 支付商店助理 — 查询订阅、客户、交易、产品，执行心跳检查，管理本地 Laravel支付商店。

下载

正确写法：$user->createToken('login')->plainTextToken —— 明文只出现一次，必须立刻取出
错误写法：return response()->json($user->createToken('login'))，PHP 会尝试 toString，触发报错
别用 $user->tokens()->create() 手动建记录，它绕过 Sanctum 的哈希逻辑和作用域校验
如果 User 模型不是默认的 App\Models\User（比如用了自定义模型），确保该模型也引入了 HasApiTokens trait

移动端或 CLI 请求该用 Cookie 还是 Bearer？

移动端、命令行工具、第三方服务调用等无 Cookie 上下文的场景，必须用 Bearer 方式；Cookie 方式只适用于同域或已明确信任的 SPA 前端。

Bearer 是唯一可靠选择：客户端在每次请求头加 Authorization: Bearer <token></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 表

真正容易被忽略的点在于：Sanctum 的「双模式」不是自动切换的智能路由，而是靠请求来源和中间件组合硬性分流。一旦 EnsureFrontendRequestsAreStateful 放错位置，或者 SANCTUM_STATEFUL_DOMAINS 配得不精确，整个认证链就会无声断裂——它不会报错，只是默默跳过 Cookie 验证，然后因没 Bearer Token 而 401。