直接运行composer require laravel/sanctum即可安装，但必须手动发布并执行迁移、在User模型中引入HasApiTokens trait、API路由使用auth:sanctum中间件、配置stateful域名精确匹配前端地址，缺一不可，否则导致401错误。
直接运行 composer require laravel/sanctum 就够了，但装完不等于能用——漏掉迁移、没配中间件、错用中间件名，三个动作一少，API 认证就 401。
装完必须手动跑迁移，否则 Token 表不存在
Sanctum 不会自动创建 personal_access_tokens 表，只注册服务提供者。没这张表，调 createToken() 或发带 Authorization: Bearer 的请求，直接报 SQLSTATE[42S02]: Base table or view not found 或 TokenMismatchException。
- 先发布迁移：
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"（只生成一个迁移文件） - 再执行：
php artisan migrate - 生产环境务必把这步写进 CI/CD 脚本，不能只在本地跑一次
- 如果项目已有同名迁移（比如从旧版升级），
php artisan migrate会跳过，得查migrations表确认是否真执行了
API 路由要用 auth:sanctum，不是 sanctum 中间件
很多人在 routes/api.php 里写 middleware => ['sanctum']，结果所有请求都 401——这是混淆了 Sanctum 的两种模式：sanctum 是中间件类名，专用于 SPA 的 session + CSRF 检查；而 API 场景该用的是 auth:sanctum 这个 guard 别名。
-
auth:sanctum会自动解析Authorization: Bearer头里的 token，并关联用户 - Laravel 9+ 默认已在
app/Http/Kernel.php的'api'中间件组里预置了\Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class和throttle:api，不用额外加 - 确保
config/auth.php里'guards'['api']['driver']是'sanctum'，不是'token'或空
用户模型要加 HasApiTokens trait
没加这个 trait，$user->createToken() 方法根本不存在，调用就报 Call to undefined method。
- 在
app/Models/User.php里补上：use Laravel\Sanctum\HasApiTokens;，然后在 class 定义里加use HasApiTokens; - 这个 trait 提供了
createToken()、currentAccessToken()、tokens()等方法，是生成和管理 token 的基础 - 别漏掉
php artisan config:clear和composer dump-autoload——装完包后缓存没清，Class 'Laravel\Sanctum\Sanctum' not found这类错误大概率是它导致的
stateful 域名配错，API 认证静默失败
开发时前端跑在 http://localhost:5173，但 config/sanctum.php 里 'stateful' 写的是 ['localhost']，结果登录成功、token 也返回了，后续请求却始终拿不到用户——因为 Sanctum 在验证 cookie 时发现来源域名不匹配，直接跳过 session 解析，也不报错。
-
'stateful'数组必须精确匹配前端完整协议 + 域名 + 端口，例如：['http://localhost:5173', 'https://myapp.com'] - 开发环境可临时写成
['*']方便调试，但上线前必须改回具体域名 - 这个配置只影响带 session 的认证路径（如
/sanctum/csrf-cookie和登录后走 cookie 的请求），纯 token 认证不受它限制
最常被忽略的是：迁移没跑、trait 没加、stateful 配错三者叠加，现象就是“一切看着都对，但就是 401”，排查时得挨个确认，不能只盯路由中间件那一行。
