Passport 报错主因是 MySQL 版本低于 5.7.8 不支持 JSON 字段，需升级或改用 Socialite；Laravel 9+ 废弃 createFreshApiToken，Laravel 10 需用 passport guard 并确保 Authorization 头正确；token client_id 无效需重跑 passport:install；SPA 场景须统一认证方式并配置 CORS credentials。
composer require laravel/passport 后 migrate 报错 SQLSTATE[42000]: Syntax error or access violation
Passport 的数据库迁移依赖 MySQL 5.7.8+ 或 MariaDB 10.2.7+，低版本不支持 JSON 字段类型。你执行 php artisan migrate 时看到这个错误，大概率是 MySQL 版本太老。
实操建议：
- 先运行
mysql --version确认版本；若低于 5.7.8，别硬升 Passport，改用laravel/socialite做第三方登录更稳妥 - 若环境可控，升级 MySQL 后，删掉已失败的迁移记录（
php artisan migrate:rollback --step=1可能不生效，直接清空migrations表中失败项） - Passport 的
createFreshApiToken中间件在 Laravel 9+ 已废弃，别照着旧文档配
Laravel 10 中 use TokenGuard 但 Auth::user() 返回 null
Passport 默认用 passport guard，不是 web 或 api。你没切对 guard，Auth 就找不到用户。
实操建议：
- 检查
config/auth.php的'defaults' => ['guard' => 'api']—— 这里必须是passport，不是api - API 请求头必须带
Authorization: Bearer {token}，漏空格、多空行、用单引号包 token 都会导致解析失败 - Token 过期后不会自动刷新，
Passport::tokensExpireIn()和Passport::refreshTokensExpireIn()要在AuthServiceProvider@boot里显式调用
Passport::personalAccessClientId 配置无效，createToken() 生成的 token 总是 client_id=1
这是 Laravel 8+ 的坑：Passport 不再读取 .env 里的 PASSPORT_PERSONAL_ACCESS_CLIENT_ID，而是强制从数据库查 oauth_clients 表中标记为 personal_access_client = 1 的那条记录。
实操建议：
- 别改 .env，运行
php artisan passport:install --force重新生成 client，它会自动设好标记 - 如果已有 client，手动执行 SQL：
UPDATE oauth_clients SET personal_access_client = 1 WHERE id = X（X 是你的 personal client ID） -
Passport::hashIds(false)在 Laravel 10.30+ 默认开启，若你用自定义 ID 映射，记得关掉，否则token->client->id会是 hash 值而非数字
前端发请求拿到 401 Unauthenticated，但 Postman 能通
常见于 SPA 场景：Vue/React 发请求时没带 Cookie，或没开 withCredentials: true，导致 session 无法复用，Passport 回退到 token 解析，而你又没传 Bearer。
实操建议：
- 确认是否混用了两种认证方式——Web 登录态（session）和 API token（Bearer），它们互不兼容，别指望一个请求同时走两边
- 如果是 SPA + Laravel API 模式，别用
auth:web中间件，统一走auth:passport，前端所有请求加Authorization头 - CORS 配置里
supports_credentials必须为 true，且allowed_origins不能写*，得填具体域名
Passport 的难点不在装，而在“什么时候该用它”。比如内部微服务通信、纯 API 场景才需要 OAuth2 授权码流；管理后台登录、小程序静默登录，用 Sanctum 更轻、更不容易配错。
