直接使用 spatie/laravel-permission，它覆盖95% RBAC场景，避免手动建表和维护关联逻辑的隐性bug；安装后必须先 publish 迁移再 migrate，确保 guard_name 一致，规范使用 assignRole() 而非 givePermissionTo()，API 中间件需传路由参数名而非类名，Blade 中 @can 前需 @auth，上线前务必执行 permission:cache-reset 并确认缓存驱动支持标签。
直接用 spatie/laravel-permission，别自己从零建表写关系——它已覆盖 95% 的 RBAC 场景，且避免了手动维护 permission_role 和 role_user 关联逻辑时的隐性 bug。
安装后必须跑迁移，否则 can() 永远返回 false
包本身不自动建表。执行这两步缺一不可：
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="permission-migrations"php artisan migrate
常见错误：跳过 publish 直接 migrate，结果只生成了空迁移文件；或 migration 成功但 roles 表里 guard_name 字段为 null，导致 $user->assignRole('admin') 静默失败——检查该字段是否和你的 guard（如 web 或 api）一致，不一致就手动 update 或重跑带 --force 的迁移。
assignRole() 和 givePermissionTo() 别混用
前者把角色塞给用户，后者直接授予权限（绕过角色）。混用会导致权限来源不可追溯：
- ✅ 推荐：用户只通过
assignRole('editor')获得权限，所有权限都绑定在角色上 - ❌ 避免：
$user->givePermissionTo('delete-user')单独赋权——审计时无法看出该权限属于哪个角色，也无法批量回收 - ⚠️ 注意：
$user->can('delete-user')会同时检查角色权限 + 直接权限，结果是并集，不是覆盖
API 路由里用 can 中间件要传模型实例，不能只传类名
写 middleware => ['can:delete-post,App\Models\Post'] 是错的。Laravel 会尝试 new 一个空 Post，$post->id 为 null，Gate 回调收不到真实数据。
正确方式有两种：
- 路由参数名与模型绑定一致：
Route::delete('/posts/{post}', ...)->middleware('can:delete-post,post')（注意第二个post是参数名，不是类名） - 手动查库：
$request->user()->can('delete-post', \App\Models\Post::findOrFail($request->route('id')))，适合/posts/{id}/actions/ban这类非标准绑定结构
Blade 里用 @can 前先确认用户已登录
@can('edit-post') 在未登录时会报 Call to a member function can() on null。Laravel 不会自动兜底。
安全写法是嵌套判断：
@auth
@can('edit-post')
<button>编辑</button>
@endcan
@endauth
或者统一在中间件层拦截未登录请求——别把权限校验和身份验证逻辑拆到模板里。
最易被忽略的一点：缓存。权限数据默认不缓存，高频调用 can() 会反复查库。上线前务必运行 php artisan permission:cache-reset 并确认 config/cache.php 中的默认驱动支持标签（如 redis），否则缓存无效。
