spatie/laravel-permission 是 laravel 最稳妥的角色权限方案，需正确发布迁移、清缓存、配置 user 模型与守卫，并遵循“权限→角色→用户”分层赋权逻辑。
直接用 Spatie/laravel-permission 是目前 Laravel 项目中最稳妥、最省心的角色权限方案，它不依赖中间件硬编码，支持数据库动态管理，也兼容 Laravel 的 Gate 和 Policy 机制。
安装与基础配置要注意哪些关键点？
别跳过发布迁移和清缓存这步，否则 roles、permissions 表不会建，后续所有赋权都会静默失败。
- 运行
composer require spatie/laravel-permission后，必须执行php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" - 接着跑
php artisan migrate—— 缺少这张表，Role::create()会抛出SQLSTATE[42S02]: Base table or view not found - 模型绑定前，确保在
User模型里用了HasRolestrait，并且config/auth.php中的'providers.users.model'指向的是你实际使用的 User 类（比如App\Models\User） - 开发中频繁修改权限后，记得清缓存：
php artisan cache:forget spatie.permission.cache，否则$user->can('delete post')可能返回旧结果
如何正确分配权限给角色，再分配角色给用户？
权限必须先挂到角色上，再把角色 assign 给用户；不能跳过角色直接 $user->givePermissionTo()（除非你明确走的是“用户直授权限”模式，但会破坏 RBAC 分层逻辑）。
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;
// 创建权限（只执行一次，或放在 Seeder 中）
Permission::create(['name' => 'edit articles']);
Permission::create(['name' => 'delete articles']);
// 创建角色并同步权限
$editor = Role::create(['name' => 'editor']);
$editor->givePermissionTo(['edit articles', 'delete articles']);
// 给用户分配角色（不是权限！）
$user = \App\Models\User::find(1);
$user->assignRole('editor');
// ✅ 此时 $user->can('edit articles') === true
// ❌ 不要写 $user->givePermissionTo('edit articles') —— 这会让权限脱离角色管控，难以审计
Gate 和 Policy 中怎么配合使用？
Spatie/laravel-permission 自动注册了 Gate 能识别的权限名，所以不用额外写 Gate::define，但 Policy 方法里仍需显式调用 $user->can() 或 $user->hasRole()。
- 在控制器中可直接用
$this->authorize('delete', $post)，前提是PostPolicy的delete()方法里写了return $user->can('delete posts') || $user->hasRole('admin'); - 注意：Policy 方法接收的第一个参数是
User实例，第二个才是模型；不要误写成$user->can($post)这种类型错位 - 如果用
@can('update post')Blade 指令，底层走的就是 Gate，只要权限名匹配数据库里的name字段即可，大小写敏感
常见报错和绕不开的坑
最常卡在「明明 assignRole 了，$user->can() 还是 false」——八成是缓存没清、模型没加 trait、或者权限名拼错了空格/复数形式。
-
Call to undefined method App\Models\User::assignRole()→ 检查User模型是否 use 了HasRoles，且没有命名空间错误 -
There is no permission named `xxx`.→ 权限名必须和数据库permissions.name完全一致，建议统一用 kebab-case，如manage-users，避免用下划线或驼峰 - API 请求中
$request->user()->can('view dashboard')返回 false → 确保 API guard 配置正确，在config/auth.php中检查'guards.api.provider'是否指向正确的 user provider - 多守卫（web + api）共用同一套权限没问题，但
assignRole()默认绑定到webguard；若需绑定到api，得显式传参：$user->assignRole(['editor'], 'api')
权限系统真正的复杂点不在安装或赋值，而在于「何时该建新角色」「权限粒度怎么划」「谁有权增删角色」——这些没法靠包解决，得结合业务流程提前想清楚。Spatie 做得再好，也只是把数据库操作封装得顺手些而已。
