直接运行composer require spatie/laravel-permission即可完成安装，Laravel 11+自动注册服务提供者；需发布配置与迁移、适配MySQL8+/UUID/团队模式、清缓存、在User模型中引入HasRoles Trait，并注意表前缀手动处理。
直接运行 composer require spatie/laravel-permission 就够了
这是唯一必需的安装命令，Laravel 11+ 会自动注册服务提供者，不用手动改 config/app.php。如果你用的是 Laravel 10 或更早版本，才需要检查 config/app.php 的 providers 数组里是否包含 Spatie\Permission\PermissionServiceProvider::class。
发布迁移和配置前，先确认数据库连接已就绪
执行 php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" 后，你会得到两样东西：config/permission.php 和一个带时间戳的迁移文件（比如 xxxxxx_create_permission_tables.php）。但别急着 migrate —— 这些表依赖你当前数据库驱动的实际能力：
- MySQL 8+ 用户要留意
Specified key was too long错误，得进迁移文件把Schema::create('roles', ...)里所有string('name')改成string('name', 191)，否则迁移失败 - 用 UUID 主键？迁移文件里默认是
increments，得手动改成uuid，同时在config/permission.php开启'uuids' => true - 团队模式（multi-tenancy）不是默认开启的，如果要用，得在
config/permission.php里设'teams' => true，否则assignRole('admin', 'team1')会报错
php artisan migrate 失败时，先清缓存再试
常见现象是执行完 vendor:publish 立刻 migrate，结果提示“Table 'permissions' already exists”或“Class Permission does not exist”。这不是包的问题，而是 Laravel 缓存没刷新：
- 运行
php artisan config:clear清掉配置缓存（config/permission.php才真正生效） - 如果项目开了 OPCache，还得跑
php artisan optimize:clear（尤其部署到生产环境后） - 迁移失败后，别反复重跑
migrate—— 先查database/migrations下是否已生成对应文件，再看migrations表里有没有重复记录
用户模型必须引入 HasRoles Trait
装完包、迁完库、清完缓存，不代表权限方法就能用。最关键的一步常被跳过：打开 app/Models/User.php，确认加了这三行：
use Spatie\Permission\Traits\HasRoles;
class User extends Authenticatable
{
use HasRoles;
}
漏掉 use HasRoles，调 $user->assignRole('admin') 就会抛 BadMethodCallException；而 HasRoles 必须放在 Authenticatable 之后，否则 trait 内部对 $this->id 的引用可能为空。
最易被忽略的点：迁移生成的表名是硬编码的（roles、permissions、model_has_permissions 等），不随 Laravel 的 DB_PREFIX 配置自动加前缀。如果项目用了表前缀，得手动改迁移文件里的 Schema::create('roles', ...) 为 Schema::create(config('database.connections.mysql.prefix').'roles', ...)，否则上线后查不到数据。
