Spatie Permission 非开箱即用，需手动实现角色权限关联、中间件拦截与UI判断；安装后必做三件事：发布配置、执行迁移、清缓存并确认User模型正确引入HasRoles；assignRole()等操作须在模型持久化后调用；中间件role/permission依赖缓存，动态变更时需主动清除spatie_permission_cache。
直接说结论：Spatie Permission 不是“开箱即用”的权限系统，它默认只提供数据库结构和基础模型方法，角色与权限的关联逻辑、中间件拦截、UI 权限判断都得你手动组织——尤其容易在 hasRole() 和 can() 混用、缓存未刷新、中间件注册顺序这几个点上翻车。
安装后必须立刻执行的三件事
很多人装完就写 php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"，但漏掉关键收尾：
- 运行
php artisan migrate—— 表没建好，后续所有assignRole()都会抛SQLSTATE[42S02]: Base table or view not found - 清空配置缓存：
php artisan config:clear（否则config/permission.php里的cache配置不生效） - 确认
App\Models\User已 useSpatie\Permission\Traits\HasRoles，且该模型继承Illuminate\Foundation\Auth\User（不是Model）
assignRole() 和 givePermissionTo() 的调用时机陷阱
这两个方法只能对已持久化的模型实例调用。常见错误是新建用户后立刻赋权：
$user = new User(['name' => 'Alice', 'email' => 'a@example.com']);
$user->assignRole('admin'); // ❌ 报错：Call to a member function getKey() on null
正确做法是先 save() 或用 create()：
$user = User::create(['name' => 'Alice', 'email' => 'a@example.com']);
$user->assignRole('admin'); // ✅
// 或一步到位
$user = User::create(['name' => 'Alice', 'email' => 'a@example.com'])->assignRole('admin');
另外注意：assignRole('admin') 接受字符串、数组或 Role 实例；但传字符串时，角色名必须已存在（用 Role::create(['name' => 'admin']) 创建过），否则静默失败。
中间件 permission 和 role 的真实行为差异
role:admin 中间件只检查用户是否有指定角色（精确匹配，不继承），而 permission:edit articles 检查的是权限（可来自角色分配，也可直接赋予用户）。但两者都依赖缓存，且默认不刷新：
- 修改角色权限后，旧用户请求仍走缓存——需手动调用
$user->forgetCachedPermissions()，或设'cache' => ['expiration_time' => 0]关闭缓存（开发期推荐） -
role中间件不支持通配符（如role:admin|editor无效），得写成role:admin,editor（逗号分隔，表示“任一满足”） - 路由组里混用时，
middleware(['role:admin', 'permission:delete users'])是“与”关系，但中间件执行顺序无关紧要——它们都在请求进入控制器前完成校验
blade 中 @can() 和 @role() 的性能隐患
@can('update', $post) 底层触发 Gate::inspect()，会加载策略类并执行 update() 方法；@role('admin') 则查用户角色关系表。高频渲染页（如后台列表）中滥用会导致 N+1 查询：
- 避免在循环里反复调用
@can('delete', $item)—— 改用预加载：$user->load('roles.permissions')，再在视图中用$user->can('delete', $item) -
@role('admin')本质是$user->hasRole('admin')，如果已知用户角色固定，可用@if(auth()->user()->hasRole('admin'))替代，减少模板引擎解析开销 - 别把
@can()当业务逻辑开关——权限校验应前置到控制器或 Policy，视图只做展示控制
真正麻烦的从来不是装包或写 assignRole()，而是当角色权限动态变化（比如运营后台实时调整某角色权限）时，缓存没清、中间件没重载、blade 还在读旧数据——这时候 debug 要盯住 spatie_permission_cache 这个缓存键，而不是重跑迁移。
