Sanctum 默认按请求来源自动切换认证路径：同源 SPA 走 session + CSRF，跨域或非浏览器客户端走 Bearer token；401/419 错误主因是请求未匹配对应路径，而非 token 未生成。
Sanctum 不是“配好就能用”的黑盒，它默认按请求来源自动切换认证路径：同源 SPA 走 session + CSRF，跨域或非浏览器客户端走 Bearer token。你收到 401 或 419，大概率不是 token 没生成，而是请求没走对那条路。
为什么 /sanctum/csrf-cookie 必须先调一次
这个端点不校验用户身份，只负责在响应头中 set XSRF-TOKEN cookie 和 laravel_session（如果还没创建）。后续所有带凭据的请求（比如登录）都依赖浏览器自动携带这两个 cookie，否则 auth:sanctum 中间件会因 CSRF 校验失败返回 419。
-
/sanctum/csrf-cookie必须用GET请求，且不能加任何 auth 中间件，否则形成死循环 - 前端必须开启凭据：axios 实例设
withCredentials = true，fetch 加credentials: 'include' - 后端
config/cors.php中'supports_credentials' => true，且'allowed_origins'明确列出前端地址（如http://localhost:5173），不能写* - 该请求必须发生在登录前；若已登录但刷新页面后失效，说明 session 过期或 cookie 被清除，需重新触发
login 后怎么正确生成并返回 token
调用 $user->createToken('login')->plainTextToken 是唯一推荐方式。它会写入 personal_access_tokens 表、哈希存储、绑定用户，并返回明文字符串——这个值只能取一次，之后再也无法还原。
- 别直接
return $user->createToken('login')：返回的是NewAccessToken对象，前端拿到的是空或报错Object of class ... could not be converted to string - 别手动插入数据库或用
$user->tokens()->create()：绕过 Sanctum 的哈希和作用域逻辑，token 无法被中间件识别 - 明文 token 只能通过响应体一次性返回，绝不能存进 cookie（有 XSS 泄漏风险），应由前端存在
localStorage或pinia，后续请求头带上Authorization: Bearer {token} - 若用在 PWA 或 Safari 等限制 cookie 的环境，必须走这一步；仅靠 session 在这些场景下不可靠
auth:sanctum 中间件到底在做什么
它不是单一路线，而是按固定顺序尝试两种认证：先查 cookie session，再查 Authorization header 中的 Bearer token。顺序不可逆，也不能拆开用。
- 当请求来自你配置的
SANCTUM_STATEFUL_DOMAINS（如test.local），它优先走 session 分支，验证laravel_session和XSRF-TOKEN - session 无效或缺失时，才 fallback 到
personal_access_tokens表查 Bearer token - 这意味着：同一个
auth:sanctum中间件，既支持 SPA 登录态维持，也兼容移动端或 CLI 的 token 认证，无需额外配置 - 如果你发现 API 总是 401，检查
.env中SANCTUM_STATEFUL_DOMAINS是否漏了前端域名（多个用逗号分隔，不带协议、端口）
API 令牌不适合做服务间静态密钥
Sanctum 的 createToken() 强制绑定用户实例，每次调用都新增数据库记录，无法预设、复用或长期有效。它不是为 APP_API_TOKEN=xxx 这类服务间通信设计的。
- 不要试图用
User::find(1)->createToken('service')->plainTextToken生成“应用令牌”：它仍要查用户、写表、带作用域，且无法脱离用户上下文 - 替代方案：在
users表加api_token字段（string, unique, nullable），自己生成（如Str::random(60)），再写个简单中间件校验$request->bearerToken()是否匹配数据库值 - 这种方案无状态、无数据库写入开销，适合 Webhook 验证、内部服务调用等无需用户会话的场景
真正容易被忽略的点在于：Sanctum 的双模式不是可选项，而是强制共存的底层逻辑。你无法只用 token 而禁用 session 分支，也无法让 SPA 请求跳过 CSRF 预检直接走 token 路径——这不是 bug，是设计前提。适配的关键，是让请求准确落到它期望的分支上。
