使用Spatie/laravel-permission实现RBAC需避开三大坑：模型未注册守卫、缓存未清、多守卫下未指定guard_name；安装后须发布配置、执行迁移、在User模型中添加HasRoles并匹配auth默认guard；创建角色/权限时必须显式传guard_name；高频赋权用syncPermissions()而非givePermissionTo()；权限判断推荐策略类+@can语法；修改权限后务必php artisan cache:forget spatie.permission.cache。
直接用 Spatie/laravel-permission 实现 RBAC，比手写权限系统快 5 倍以上，而且它不依赖中间件硬编码、支持数据库动态赋权、能无缝对接 Laravel 的 can 和 @can 语法——但前提是配置别踩三个典型坑：模型未注册守卫、缓存未清导致权限不生效、多守卫场景下未指定 guard_name。
安装与基础配置必须做这三件事
装包只是第一步，漏掉任一环节都会导致 syncPermissions() 失效或 @can('delete post') 永远返回 false：
- 运行
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"，确保迁移文件生成并执行php artisan migrate - 在
app/Models/User.php中添加use HasRoles;，并确认该模型已继承Authenticatable - 检查
config/auth.php中的默认guard名称（通常是web），后续所有角色/权限操作必须显式匹配这个值，否则查不到数据
创建角色和权限时必须指定 guard_name
尤其当项目有多个 guard（比如 web 和 api）时，不传 guard_name 会导致权限绑定到错误守卫，auth()->user()->can('edit post') 返回 false 却查不出原因：
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;
// 正确：显式声明 guard
$adminRole = Role::create(['name' => 'admin', 'guard_name' => 'web']);
$editPost = Permission::create(['name' => 'edit post', 'guard_name' => 'web']);
// 错误：没传 guard_name → 默认用 config('auth.defaults.guard')，但可能不是你当前登录的 guard
$adminRole = Role::create(['name' => 'admin']); // ⚠️ 危险！
给用户分配权限的两种方式及适用场景
别无脑用 givePermissionTo()，高频操作下性能差；批量赋权要用 syncPermissions()，而判断逻辑建议走策略而非硬编码：
-
$user->givePermissionTo('delete post')：适合单次、管理后台手动赋权 -
$user->syncPermissions(['edit post', 'publish post'])：清空旧权限后批量写入，避免 N+1 查询，适合初始化或角色切换 - 控制器里别写
if ($user->hasPermissionTo('manage users'))，改用策略类 +@can('manage users', $user)，权限逻辑可复用、易测试
缓存不刷新是权限不生效最常见原因
Spatie 默认启用缓存，开发阶段改了权限却没反应？不是代码错，是缓存没清：
- 每次修改权限/角色关系后，必须运行
php artisan cache:forget spatie.permission.cache - 生产环境建议用
php artisan optimize:clear（Laravel 9+）或php artisan config:clear && php artisan cache:clear - 如果用了 Redis 缓存，确认
CACHE_DRIVER=redis且连接正常，否则缓存命令看似成功实则没生效
RBAC 的核心不在“建几个表”，而在“权限何时加载、在哪校验、出错往哪查”。Spatie 的坑基本都藏在 guard 对齐、缓存生命周期和 sync/give 的语义差异里——这些地方一旦疏忽，调试半小时不如重跑一遍 cache:forget。
