Passport安装失败主因是Laravel与Passport版本不匹配，如Laravel 10需^11.0而非^10.0；php artisan passport:install报错多因未执行迁移或oauth_clients表缺失personal_access_client字段；Passport::routes()须在api.php中独立注册且不被其他auth中间件包裹；Personal Access Token默认永不过期，需手动设置有效期。
Passport 安装失败：composer require 报错 “package not found”
常见原因是 Laravel 版本与 Passport 版本不匹配，比如在 Laravel 10 中用了 laravel/passport:^10.0 是对的，但若手误写成 ^9.0 或 ^11.0 就会触发依赖冲突或包不存在错误。
实操建议：
- 先运行
php artisan --version确认 Laravel 实际版本（注意不是composer.json里写的“可能版本”） - 查官方文档对应关系：Laravel 10 → Passport
^11.0（不是 ^10.0），Laravel 9 → Passport^10.0 - 安装命令必须带完整约束：
composer require laravel/passport:^11.0（Laravel 10 下），不能省略^11.0 - 如果已装错，先
composer remove laravel/passport再重装，避免残留配置干扰
php artisan passport:install 报错 “Call to undefined method createPersonalAccessClient()”
这是典型的迁移未执行或数据库结构缺失导致的——passport:install 命令内部会调用模型方法，而这些模型依赖 oauth_clients 表存在且含特定字段（如 personal_access_client）。
实操建议：
- 确认是否已运行
php artisan migrate，且没有跳过CreateOauthClientsTable迁移文件 - 检查数据库中
oauth_clients表是否存在，以及是否有personal_access_clienttinyint(1) 字段（Laravel 9+ 要求） - 如果表存在但字段缺失，不要手动加字段，而是回退迁移：
php artisan migrate:rollback --step=1，再重新migrate - 若使用 SQLite，注意它不支持
tinyint，Passport 的迁移会自动转为integer，但某些旧版 SQLite 驱动可能报错，建议开发环境用 MySQL/PostgreSQL
Passport::routes() 不生效：API 请求始终返回 401
根本原因通常是路由注册时机或位置不对。Passport 的 routes() 必须在 API 路由组内注册，且不能被中间件提前拦截（比如 auth:sanctum 错误地套在了 Passport 路由上）。
实操建议：
- 只在
routes/api.php中调用Passport::routes()，**不要**放在web.php或服务提供者里 - 确保该调用位于
Route::middleware('api')包裹之外——它是独立的认证端点，本身不该被其他 auth 中间件包裹 - 检查
config/auth.php中'guards.api.driver'是否为passport，不是token或sanctum - 前端请求头必须带
Authorization: Bearer {token}，且{token}是Personal access token或密码授权获取的access_token，不是 client_secret
Personal Access Token 无法刷新或过期时间固定为 1 年
Passport 默认把 Personal Access Token 设为永不过期（expires_at = null），但很多开发者误以为它受 tokensExpireIn() 控制——其实这个方法只影响密码授权、客户端凭据等流程生成的 token，不影响 Personal Access Token。
实操建议：
- 如需限制 Personal Access Token 有效期，必须手动设置：
$user->createToken('name', ['*'], now()->addDays(7)) -
Passport::tokensExpireIn()和Passport::refreshTokensExpireIn()只对 OAuth2 流程（/oauth/token）有效，对createToken()无影响 - 别依赖数据库字段
expires_at判断 Personal Access Token 是否过期——它为null时 Passport 仍认为有效；真正控制逻辑在TokenRepository::findValidToken()中的空值判断 - 生产环境建议禁用 Personal Access Token（设
Passport::enableImplicitGrant();不要调用），改用更安全的授权码流程
Passport 的坑多数藏在“默认行为”和“文档隐含前提”里：比如它假设你已理解 Laravel 的 guard 机制、OAuth2 授权类型差异、以及迁移与模型之间的强耦合。一旦某个环节（比如表字段、guard 配置、路由注册顺序）没对齐，错误表现往往很模糊——401、500、空响应都有可能，但根源常常就差那一行 migrate 或一个 ^ 版本号。
