唯一推荐安装方式是composer require spatie/laravel-permission，之后必须执行php artisan vendor:publish --provider="spatie\permission\permissionserviceprovider"以生成配置和迁移文件，并在用户模型中use hasroles，角色权限须用role::create()创建。
composer require spatie/laravel-permission 是唯一推荐的安装方式，其他写法（如带版本号硬指定、加 --dev、用 require-dev）容易引发依赖冲突或功能缺失。
composer require spatie/laravel-permission 后必须跑 vendor:publish
不执行这步，config/permission.php 不会出现，迁移文件也不会复制到 database/migrations/。
常见错误现象：
- 运行
php artisan migrate报错Base table or view not found: 1146 Table 'xxx.roles' -
Role::create()抛出Class 'Role' not found（因为模型类未自动加载，而 vendor:publish 会注册服务提供者并触发自动发现）
执行命令：php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
它会生成：
-
config/permission.php（可选改'cache.expiration_time'或启用'teams'） - 一个形如
2018_01_01_000000_create_permission_tables.php的迁移文件
别跳过这步，也别手动创建迁移——官方迁移已适配 MySQL 8+ 索引长度限制。
用户模型必须 use HasRoles，且不能漏掉命名空间
app/Models/User.php 中要这样写：
use Spatie\Permission\Traits\HasRoles;
<p>class User extends Authenticatable
{
use HasRoles;
}</p> 容易踩的坑：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 忘了
use语句，只写了use HasRoles→ PHP 解析失败 - 在非
App\Models\User路径下（比如用了自定义命名空间），没同步更新config/permission.php中的'models.role'和'models.permission'配置项 - Laravel 11+ 默认启用了模型自动发现，但如果你删过
vendor:publish生成的配置，或清过缓存后没重发，HasRoles方法仍可能不可用
验证是否生效：在 Tinker 里运行 (new App\Models\User)->assignRole('admin')，不报错即 OK。
创建角色和权限必须用 Role::create() 和 Permission::create()
不要用 new Role(['name' => 'admin'])->save()，否则事件监听器不触发，缓存不会刷新，后续 $user->hasRole('admin') 可能返回 false。
正确写法：
-
$role = Role::create(['name' => 'admin']) -
$permission = Permission::create(['name' => 'delete user']) -
$role->givePermissionTo($permission)或$role->givePermissionTo(['edit post', 'view post'])
注意：
-
name字段是唯一索引，重复插入会抛Integrity constraint violation - 名称建议全小写 + 下划线，避免空格或大写导致 Blade 指令（如
@can('Delete User')）匹配失败 - 不要用中文做
name值，底层缓存键基于字符串哈希，非 ASCII 字符在某些环境可能引发不一致
生产环境慎用 $user->givePermissionTo('...') 直接赋权——权限逻辑会散落各处，难以审计。
Laravel 10/11 用户要特别注意：别试图装旧版 v3 或手动降级，spatie/laravel-permission 官方已明确支持 Laravel 11，只要 Composer 版本 ≥ 2.5，require 命令默认拉取的就是兼容分支。真正卡住的，往往是漏了 vendor:publish 或模型没加 Trait。
