spatie/laravel-permission 迁移必须先执行 vendor:publish 再 migrate，否则 roles 表 guard_name 为 null 导致权限判定失败；assignRole() 应替代 givePermissionTo() 以保障权限可追溯；API 中间件需传路由参数名而非类名；@can 必须嵌套 @auth；守卫与缓存一致性是 RBAC 核心。
spatie/laravel-permission 迁移必须 publish 再 migrate
不执行 php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="permission-migrations" 就直接 php artisan migrate，结果只有空迁移文件或表结构缺失——roles 表里 guard_name 字段为 null 是最常见静默失败原因。
真实影响：$user->assignRole('admin') 看似成功，但后续 $user->can('delete-post') 永远返回 false。因为 Gate 查询时会严格匹配 guard_name（如 web 或 api），不一致就跳过该角色权限。
- 检查方式：查
roles表，确认guard_name值是否与你的守卫名一致 - 修复方式：手动
UPDATE roles SET guard_name = 'web' WHERE guard_name IS NULL，或删掉迁移记录 +--force重跑 - 上线前必做：
php artisan permission:cache-reset，否则缓存中可能残留旧权限数据
assignRole() 和 givePermissionTo() 别混用
用户直接调用 $user->givePermissionTo('ban-user') 会绕过角色体系，导致权限来源不可追溯——审计时无法定位该权限属于哪个角色，也无法通过改角色批量回收。
$user->can('ban-user') 的结果是「角色继承的权限」+「直接授予的权限」的并集，不是覆盖关系。一旦混用，你永远不知道某条权限是从哪来的。
- ✅ 正确路径：所有权限只绑定到
Role，用户只通过assignRole()获得权限 - ❌ 错误操作：给个别用户开后门式赋权，比如
$user->givePermissionTo('view-analytics') - ⚠️ 注意：
hasRole()不检查权限，只查角色关联；can()才真正触发权限判定链
API 中间件传参必须是路由参数名，不是类名
写成 middleware => ['can:delete-post,App\Models\Post'] 是错的。Laravel 会尝试 new 一个空 Post 实例，$post->id 为 null，Gate 回调收不到真实数据，最终判定失败。
正确方式取决于路由定义：
- 标准资源路由：用参数名，如
Route::delete('/posts/{post}', ...)->middleware('can:delete-post,post')（注意第二个post是路由参数名） - 非标准路由（如
/posts/{id}/ban）：手动查库，$request->user()->can('ban-post', \App\Models\Post::findOrFail($request->route('id'))) - Guard 不一致时：确保中间件使用的守卫和用户登录守卫一致，比如 API 请求用
api守卫，就不能依赖web下的角色数据
@can 在 Blade 中必须嵌套 @auth
@can('edit-post') 在未登录状态下会报 Call to a member function can() on null——Laravel 不自动兜底，$request->user() 是 null，can() 方法无处可调。
这不是语法糖缺陷，而是设计选择：权限检查的前提是身份已确立。
- 安全写法：
@auth @can('edit-post') ... @endcan @endauth - 别依赖
Auth::check()后再写@can，Blade 编译后顺序不可控 - 若需未登录也显示部分 UI（如“请登录后编辑”），用
@guest+@auth双分支控制更稳妥
RBAC 最容易被忽略的不是模型关系，而是守卫（guard）和缓存的一致性。同一个用户在 web 守卫下有 editor 角色，在 api 守卫下却查不到——因为 role_user 关联表里 guard_name 不匹配。这种问题在线上往往表现为「前端说有权限，接口却 403」，排查时容易陷入 Gate 逻辑，其实根子在迁移和守卫配置。
