sanctum 不生成 jwt，而是用加密字符串作 api 令牌，依赖会话或 bearer token 验证；auth::user() 在 api 路由返回 null 主因是未启用 session 中间件或未正确配置 stateful 域名及 cookie 传递。
Sanctum 不生成长期有效的 API 令牌，它依赖于「会话 + Tokenable 模型」的组合实现无状态请求验证；直接调用 createToken() 得到的是加密字符串（不是 JWT），且默认只在当前设备/浏览器有效。
为什么 Auth::user() 在 API 路由里返回 null？
这是最常见的误用起点：Sanctum 的默认行为不自动启用 session 中间件，而 auth:sanctum 中间件只负责从 Authorization: Bearer {token} 或 Cookie 中提取并验证 token —— 但若你没配对使用 stateful 域名或没发带 Cookie 的请求，它就退化为纯 token 验证，此时必须确保请求头含有效 token。
- 检查
config/sanctum.php中的stateful是否包含你的前端域名（如['localhost:5173']） - 确保前端发起请求时携带了 Cookie（
credentials: 'include'），否则无法复用 session - 非 stateful 场景下，必须手动在请求头中传入
Authorization: Bearer {token} -
sanctum中间件不会自动登录用户，它只设置Auth::guard('sanctum')->user()；别混用auth:api或自定义 guard
createToken() 返回的 token 怎么用？
这个方法返回的是 Sanctum\PersonalAccessToken 实例，其 plainTextToken 属性才是你要传给前端的明文 token。它本质是服务端生成的随机字符串，存于 personal_access_tokens 表，不加密 payload，也不过期（除非手动 revoke）。
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
public function login(Request $request)
{
$credentials = $request->only('email', 'password');
if (Auth::attempt($credentials)) {
$user = Auth::user();
// 注意：$token 是 PersonalAccessToken 实例，不是字符串
$token = $user->createToken('api-token');
return response()->json([
'token' => $token->plainTextToken, // ← 必须取这个
'user' => $user
]);
}
return response()->json(['error' => 'Unauthorized'], 401);
}
- 不要把整个
$token对象 JSON 化返回，它含敏感字段（如token字段是哈希值） -
createToken()第二个参数可传数组定义 abilities，如['read', 'write:posts']，后续可用$user->tokenCan('write:posts')校验 - 该 token 仅用于 API 请求（
auth:sanctum），不能用于登录网页（不触发 session）
如何验证请求是否拥有某权限（abilities）？
Sanctum 的 abilities 是白名单机制，不是 role-based，每次验证都查数据库里的 abilities 字段。它不缓存、不解析 JWT claim，所以性能开销略高于纯 header 解析，但更可控。
// 在控制器中
if (! $request->user()->tokenCan('delete:comments')) {
abort(403);
}
// 或在中间件里
if (! $request->user()->currentAccessToken()->can('edit:post')) {
abort(403);
}
- abilities 区分大小写，且必须完全匹配（
'read'≠'Read'） -
tokenCan()只对通过auth:sanctum认证的用户生效；未认证时$request->user()为 null，会报错 - 如果用了
withCookie或stateful模式，$request->user()->currentAccessToken()可能为 null（因为走的是 session，不是 token）
真正容易被忽略的是：Sanctum 的 token 和 session 是两条路径。你得明确当前请求走哪条——是单页应用用 Bearer token 调 API，还是混合模式下部分接口靠 Cookie 自动鉴权。混用却不校验来源，就会出现 Auth::user() 有时有、有时空的情况。
