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 模型里用了 HasRoles trait，并且 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 Spati
e\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() 默认绑定到 web guard；若需绑定到 api，得显式传参：$user->assignRole(['editor'], 'api')

权限系统真正的复杂点不在安装或赋值，而在于「何时该建新角色」「权限粒度怎么划」「谁有权增删角色」——这些没法靠包解决，得结合业务流程提前想清楚。Spatie 做得再好，也只是把数据库操作封装得顺手些而已。