Laravel Sanctum对接独立SPA访问auth:sanctum路由返回401错误

常见触发原因 #

• **SANCTUM_STATEFUL_DOMAINS配置不匹配
  如果本地开发环境前端站点带端口（例如admin.app.test:3000），仅填写域名无法匹配规则，需要完整带上端口信息。无端口场景也需要确认配置值和请求Origin请求头完全一致，大小写、拼写不能有偏差。
• **跨域请求未开启凭证携带
  前端发起请求的工具必须开启凭证携带配置：
  axios配置示例：axios.defaults.withCredentials = true
  fetch配置示例：fetch(url, { credentials: 'include' })
  未开启该配置的情况下，浏览器不会自动携带session cookie到后端服务，导致鉴权失败。
• **CSRF令牌未按流程获取
  调用所有需要鉴权的接口之前，必须先请求/sanctum/csrf-cookie接口获取CSRF令牌，该请求也需要开启凭证携带，浏览器会自动将令牌写入Cookie，后续请求会自动携带X-XSRF-TOKEN请求头。
• **旧配置缓存未清理
  执行php artisan config:clear命令清除所有配置缓存，避免.env修改后未生效，旧的SESSION_DOMAIN、SANCTUM_STATEFUL_DOMAINS配置仍在使用。
• **路由未归属到正确的中间件组
  确认你的鉴权路由确实被api中间件组包裹，能正常触发EnsureFrontendRequestsAreStateful中间件逻辑，若路由直接定义在web中间件组内，或未触发该中间件，都会导致鉴权失败。
• **CORS配置不符合要求
  检查config/cors.php配置：
  1. paths数组需要包含api/*和sanctum/csrf-cookie路径
  2. allowed_origins数组需要包含http://admin.app.test
  3. supports_credentials必须设置为true
     任意一项配置错误都会导致预检请求被拦截，后续鉴权请求无法正常发起。
• **登录状态未正确写入Session
  确认登录接口调用时，执行了Auth::attempt($credentials)或Auth::login($user)操作，且操作完成后再返回响应，避免提前返回导致Session未写入登录状态。

快速排查步骤 #

1. 先清理配置缓存并重启服务后重试
2. 打开浏览器开发者工具的网络面板，查看鉴权请求的请求头信息：
   • 确认Cookie头中同时携带了laravel_session和XSRF-TOKEN两个Cookie
   • 确认Origin头的值和SANCTUM_STATEFUL_DOMAINS配置完全一致
   • 确认请求头中存在X-XSRF-TOKEN头
3. 确认请求顺序正确：先请求/sanctum/csrf-cookie→再调用登录接口→最后调用鉴权接口，顺序不能调换。
4. 若使用Laravel 9及以上版本，可以直接在config/sanctum.php中硬编码stateful配置值测试，避免.env配置的引号、逗号等符号解析错误。

内容的提问来源于stack exchange，提问作者Nick van der Waal