很多 Laravel 开发者第一次打开app/Providers/AuthServiceProvider.php时十有八九会愣一下这个文件里明明只有几行代码一个protected $policies空数组一个boot()方法里调用registerPolicies()然后就没了。可就是这寥寥几行牵扯出 Laravel 权限体系的一整套设计。我为什么对这个文件这么上心因为在真实项目里我见过太多因为不懂它而把权限写成一坨的人——有人把判断逻辑堆在 Controller 里有人把 Policy 注册错了位置导致线上 403 半天查不出原因还有人干脆把整个文件删了结果所有授权方法全部失效。所以我想用庖丁解牛的方式把这个文件从头到尾拆开看看它到底凭什么能牵动整个权限系统。1. AuthServiceProvider是干什么的——先搞明白它的“官位”1.1 服务提供者Laravel的“总开关”Laravel 框架启动时会执行两次“遍历服务提供者”的动作一次是调用所有 Provider 的register()一次是调用所有 Provider 的boot()。你可以把服务提供者理解成一个个电源插头register()是插上电boot()是按下开关。框架本身自带的强大功能比如数据库、队列、缓存全都靠这些插头供电。app/Providers目录下的AuthServiceProvider、RouteServiceProvider、EventServiceProvider都是项目级插头专门给应用接入相应的能力。很多初学者容易把这里的register()方法理解成“注册路由”或者“注册模型”其实它是“往容器里绑定东西”。AuthServiceProvider默认没有register()方法因为它继承的基类里已经完成了必要的绑定但它有boot()而boot()正是整个授权体系点火的地方。1.2 AuthServiceProvider是授权的中枢不是认证的中枢这里必须先把概念拧清楚Laravel 里的“认证”Authentication 和“授权”Authorization 是两码事。认证解决的是“你是谁”登录、session、token 都归它管授权解决的是“你能干什么”比如编辑这篇文章、删除那个评论、查看后台报表。AuthServiceProvider名字里带Auth但主职是后者——它是 Laravel 授权系统Gate 和 Policy的注册中枢。认证相关配置在config/auth.php和app/Http/Kernel.php的auth中间件里别被名字带偏。在AuthServiceProvider里你干的最多的事就是两件把某个模型和某个策略类绑定起来或者直接用Gate::define()定义一条能力规则。前者叫 Policy策略后者叫 Gate闸门。Policy 适合围绕一个模型写一整套 CRUD 权限Gate 适合定义独立的能力点比如“是否允许导出报表”。它们最终都会归入同一个Gate实例在业务代码里用Gate::allows()、can、$user-can()等方式触发。1.3 为什么你要读懂这个文件我见过不少项目权限判断撒得满世界都是if(auth()-user()-role admin)直接写在 Blade 模板里if($post-user_id auth()-id())写在 Controller 里用户表加个is_admin字段就号称做了 RBAC。短期看是爽了等业务复杂起来你会发现在十个地方维护着八九种“判断逻辑”改一次权限模型能改到怀疑人生。AuthServiceProvider存在的意义就是把这些零散的判断收拢到一个“总闸门”里。读懂它你就掌握了 Laravel 权限系统的心脏Policy 绑定、Gate 定义、超级管理员规则、主键模型授权。后面排查 403、写单元测试、做接口权限控制都会顺很多。2. 庖丁解牛把默认代码拆到骨头里2.1 命名空间和 use一张“依赖清单”拿 Laravel 10 里自动生成的AuthServiceProvider.php来说默认内容长这样?php namespace App\Providers; use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider; use Illuminate\Support\Facades\Gate; class AuthServiceProvider extends ServiceProvider { protected $policies [ // App\Models\Model App\Policies\ModelPolicy, ]; public function boot() { $this-registerPolicies(); Gate::before(function ($user, $ability) { // }); } }第一行namespace App\Providers决定了这个类的“门牌号”。第二三行use是两张依赖清单一个是从框架基类继承过来的AuthServiceProvider为了不被同名类搞混这里被别名成了ServiceProvider另一个是门面Gate后面的Gate::before()靠它才能调用。如果你在boot()里写Gate::define(...)这两个use一个都不能少少了直接白屏报“Class not found”。有个细节值得注意Gate的底层其实是Illuminate\Contracts\Auth\Access\Gate这个接口的实现通过门面Facade代理访问。你在AuthServiceProvider里用的Gate::policy()本质上是在往容器里解析出来的那个 Gate 实例里注册规则。所以如果你在别的类里也用Gate同样得引入use Illuminate\Support\Facades\Gate;。2.2 类继承与 $policies 属性策略注册表这个类继承了框架的Illuminate\Foundation\Support\Providers\AuthServiceProvider而它的祖父类其实是Illuminate\Support\ServiceProvider。这意味着它天然拥有register()、boot()这两个生命周期方法以及一个专门为授权准备的$policies属性。protected $policies [ // App\Models\Model App\Policies\ModelPolicy, ];这个数组就是“策略注册表”键是模型类名值是策略类名。比如protected $policies [ App\Models\Post::class App\Policies\PostPolicy::class, ];::class返回的字符串就是类的完整命名空间比手写App\Models\Post更安全因为 IDE 能帮你跳转和检查拼写。我把这个数组理解成一张“员工花名册”Markdown 模型对应 MarkdownPolicy 策略Comment 模型对应 CommentPolicy 策略。哪天来了新模型要加权限只需在这张表里加一行registerPolicies()会自动去注册。为什么通过数组而不是直接在boot()里一行行写Gate::policy()因为数组声明是声明式的一眼就能看出模型和策略的映射关系而且基类registerPolicies()已经帮我们循环处理了你不用自己动手。如果你想在boot()里手动加也可以写Gate::policy(Post::class, PostPolicy::class)效果完全一样只是不在这张表里。2.3 boot() 与 registerPolicies()点火的瞬间boot()方法会在服务容器准备好之后执行这时候所有 Provider 都已经完成了register()阶段的注册框架的基础设施比如数据库、缓存也都可用了。AuthServiceProvider里的boot()首先调用了$this-registerPolicies()。这个registerPolicies()是基类提供的方法它的内部实现其实很简单大致是public function registerPolicies() { foreach ($this-policies as $key $value) { Gate::policy($key, $value); } }它把$policies数组里的每一对映射都转发给Gate::policy()。所以你在boot()里写的顺序很重要如果先写了Gate::define(custom, ...)再调用registerPolicies()通常也没问题因为这两者不是互相覆盖的关系但如果你在registerPolicies()之后又重新给同一个模型绑定了另一个 Policy那毫无意义甚至可能混淆。我习惯把$this-registerPolicies()放在boot()的第一行然后才开始定义自定义 Gate 或Gate::before()这样逻辑上最干净。2.4 被删掉的 AuthServiceProvider新版本发生了啥到了 Laravel 11你会发现php artisan make:provider AuthServiceProvider出来的项目里根本没有这个文件因为框架认为不再需要你手动维护 Policy 映射了——Policy 自动发现已经足够聪明。Laravel 会自动到app/Policies目录里找与模型同名的策略类规则是你在route或auth中调用Gate::authorize(update, $post)时框架拿$post的类名比如App\Models\Post截掉Models前缀得到Post再去App\Policies\PostPolicy找。所以新版项目里AuthServiceProvider默认不再生成这也导致很多习惯了老版本的开发者找不着北我原本写在AuthServiceProvider里的Gate::before()超级管理员逻辑去哪写两个去处一是手动创建一个AuthServiceProvider并在config/app.php的providers数组里注册二是直接写到现有的AppServiceProvider::boot()。我个人更倾向新建一个专用 Provider因为权限相关的东西集中在一起以后维护方便。我的建议是不管新老版本你都要理解这个文件的工作原理因为老项目里它还在新项目里你随时可能被迫“再造一个”出来。3. 实操让 Policy 真正跑起来3.1 三步创建 Policy以一个典型的博客系统为例文章属于作者作者可以管理自己的文章管理员可以管理所有文章。第一步用 Artisan 命令生成策略类php artisan make:policy PostPolicy --modelPost--modelPost参数会自动生成包含viewAny、view、create、update、delete、restore、forceDelete这些方法的骨架并在方法里填好类型提示。生成的PostPolicy默认长这样以 Laravel 10 为例?php namespace App\Policies; use App\Models\Post; use App\Models\User; class PostPolicy { public function viewAny(User $user): bool { // } public function view(User $user, Post $post): bool { // } public function update(User $user, Post $post): bool { return $user-id $post-user_id || $user-isAdmin(); } }第二步如果项目是 Laravel 11 之前把策略注册到AuthServiceProvider的$policies数组里如果是 Laravel 11并且模型放在app/Models、策略放在app/Policies自动发现就能找到不需要注册。第三步在 Controller 或路由里调用授权。3.2 手动注册还是自动发现怎么选手动注册和自动发现并不是互斥的。手动注册的优先级更高你写在$policies里的映射会覆盖自动发现的结果。什么情况下需要手动注册模型不在app/Models目录比如放在app/Domain/Post、策略类名不符合PostPolicy这种命名规则、或者你有多个策略类对应同一个模型的不同场景都需要手动注册。我整理了一个简单的选择表场景自动发现手动注册标准模型标准策略推荐不必要模型在自定义命名空间不生效必须策略类名带额外后缀不生效必须需要动态切换策略不推荐推荐想集中查看所有策略映射看不清推荐实际项目里我一般折中标准模型交给自动发现特殊映射在AuthServiceProvider里手动注册。这样既省事又不会因为某个“奇怪路径”导致 403。3.3 在 Controller 和 Blade 里“用权”定义好 Policy 之后使用方式有很多种。最推荐的是在 Controller 方法里调用$this-authorize()因为App\Http\Controllers\Controller自带AuthorizesRequeststraitpublic function update(Request $request, Post $post) { $this-authorize(update, $post); // 更新逻辑... }这行代码相当于当前登录用户是否有权限执行update能力作用于$post。没有权限时框架会直接抛出AuthorizationException最终渲染成 403 页面。如果你更喜欢显式判断可以这样写if ($request-user()-cannot(update, $post)) { abort(403, 你无权编辑这篇文章); }这里用了cannot()语义是“如果用户不能做就拒绝”。反过来用Gate::allows()也一样但注意allows和denies是相反的逻辑别搞混。在 Blade 模板里最常见的用途是控制按钮显示can(update, $post) a href{{ route(posts.edit, $post) }}编辑/a endcancan指令背后调用的就是Gate::allows所以权限逻辑始终只有一份Controller 和模板都能复用。3.4 高级玩法Gate::before 超级管理员与自定义 Gate业务里最常用的“管理员通吃一切”需求用Gate::before()实现最优雅。在boot()里加上public function boot() { $this-registerPolicies(); Gate::before(function ($user, $ability) { if ($user-isAdmin()) { return true; } }); }Gate::before()的回调会在所有 Policy 和Gate::define()判断之前执行。如果它返回true直接放行返回false直接拒绝返回null则继续走后面的正常授权判断。这里千万注意如果回调里写了return false等于把所有权限都关了容易出大事故。我只在Gate::before里返回true或什么都不返回即null绝不轻易返回false。除了 PolicyGate::define()还能定义独立能力适合“导出报表”“审批流程”这类不绑定单一模型的操作Gate::define(export-reports, function ($user) { return $user-department operations; });然后业务代码里直接Gate::authorize(export-reports);这样就能把散落的判断逻辑全部收进AuthServiceProviderController 里干净到让人感动。4. 常见问题与排查技巧实录4.1 线上 403Policy 没注册还是没找到403 是权限系统最常见的报错但原因可能千奇百怪。按顺序排查第一请求是否真的登录了auth()-user()是否为nullPolicy 里的$user参数是否为 null 导致异常。第二Policy类是否存在、命名是否正确。第三如果是手动注册AuthServiceProvider的$policies数组是否正确填写boot()里有没有调用registerPolicies()。第四如果是自动发现检查模型和策略的命名空间是否符合规则。我踩过一次很深的坑PostPolicy文件方法写的是public function update(User $user, Post $post)但调用授权时传的是$this-authorize(update, $post-author)把目标传成了另一个用户对象。框架去查找UserPolicy结果自然没有直接抛 403。排查了半天才意识到$this-authorize()的第二个参数必须是“被操作模型实例”而不是“发起操作的人”。这类问题很容易被忽视建议你在写 Policy 方法之前先用php artisan route:list或者单元测试确认参数传递没问题。4.2 自动发现为何“失灵”自动发现是 Laravel 7 之后引入的能力但它的触发条件比很多人想象中严格。它要求模型类名与策略类名的“驼峰对应”关系成立App\Models\Post对应App\Policies\PostPolicyApp\Models\ProductCategory对应App\Policies\ProductCategoryPolicy。如果你的模型并没有放在app/Models下比如放在app/Entities那自动发现就找不到——除非你调用Gate::guessPolicyNamesUsing()自定义规则否则只能手动注册。还有一个隐蔽情况模型类名是Post但策略类文件命名成PostPolicy.php里面类名却写成PostPolicyRulePHP 类名与文件名不匹配自动加载都过不去更别提自动发现了。出现“我明明有PostPolicy为什么它就是不用”的诡异现象时先跑一下composer dump-autoload。因为新增的 Policy 类如果没有被框架自动发现到往往是 composer 的类映射缓存没有刷新这在部署流程中特别常见。4.3 改了没反应是缓存在作祟线上项目经常开php artisan config:cache和php artisan route:cache但确确实实有开发者会忘记清缓存。当你改了AuthServiceProvider里的Gate::define后如果业务代码里一直拿旧逻辑在跑第一反应就应该是php artisan optimize:clear这条命令会清掉配置、路由、缓存、视图所有常见缓存。生产环境我一般执行php artisan optimize:reload或者部署脚本里做php artisan optimize后再清缓存。另外如果AuthServiceProvider是新加的并且手动在config/app.php的providers数组注册过记得也要清一下配置缓存否则 Provider 列表可能还是旧的。4.4 Gate 与 Policy 的使用边界很多人上来就在 Controller 里用Gate::define但用着用着发现代码越来越乱原因是没有区分 Gate 和 Policy 的职责。我的经验法则如果一个能力与某个具体模型对象强相关比如修改文章、删除评论请用 Policy因为它是面向模型的如果一个能力与模型类型无关比如查看后台仪表盘、执行系统维护请用Gate::define因为它是面向操作的。如果你两者混用可能会出现同一个动作既在 Policy 里定义又在 Gate 里定义然后Gate::before一插进来行为更难预测。Laravel 的判断顺序是先走Gate::before回调再走Gate::define定义的具体能力最后才尝试自动解析 Policy。如果你使用Gate::authorize(update, $post)这个update能力会先去 Gate 里找有没有update的define找不到再用 Policy 的update方法。因此如果你在Gate::define(update, ...)里写了一套逻辑又在PostPolicy::update写了另一套真正生效的是Gate::define那套。要避免这种“双写”的混乱统一走 Policy 或统一走 Gate别一条路拆成两半。5. 权限设计的心法从文件到架构5.1 AuthServiceProvider 之外的选择如果你的项目已经演进到需要“角色 权限”的完整 RBAC可以考虑社区方案比如spatie/laravel-permission。它提供角色、权限的数据库存储和管理界面并且能很好地和 Laravel 自带的Gate体系兼容。它本质上做的事情和AuthServiceProvider一样把权限规则注册进 Gate。你可以在它的boot()里看到大量Gate::define和Gate::before只是这些规则是动态从数据库里读出来的。但这不代表你可以完全无视AuthServiceProvider。即便用了第三方库你还是需要在这个 Provider或者AppServiceProvider里定义自己的Gate::before超级管理员逻辑或者处理一些特殊策略。而且第三方库在复杂规则下的性能不如静态 Policy我的建议是中小项目直接写 Policy别为了一两个角色引入大包大项目可以用第三方做基础但把核心权限规则仍然留在代码里避免把权限全部搬进数据库导致性能失控。5.2 权限设计的“三不”原则在拆过太多权限项目之后我总结出三条心法。第一不要在 Controller 里写if($user-id $model-user_id)这种裸判断。一旦要加管理员、超管、团队权限你要改一堆 Controller而如果统一放进 Policy只需要动一个文件。第二不要在每个模型里复制粘贴同一个isAdmin()判断。把“是否管理员”放到User模型的方法里并且在Gate::before里只用一次全局生效。第三不要顺着一股脑用Gate::allow而不考虑性能。在列表遍历时每行调用一次 Policy 方法会有 N 次查询要用Post::query()-where(user_id, $user-id)这类预筛选权限只是最后一道防线不是查询优化方案。5.3 兼容 PHP 8 与 Laravel 11 的现代化写法PHP 8 之后Policy 类可以写得更紧凑。比如用构造器属性提升来自动注入依赖class PostPolicy { public function __construct( private readonly PostRepository $posts, ) { } public function update(User $user, Post $post): bool { return $user-id $post-user_id; } }这在AuthServiceProvider里并不会增加额外负担因为 Policy 是通过容器解析的构造器里的依赖会自动注入。Laravel 11 之后如果项目里没有AuthServiceProvider你也可以在AppServiceProvider::boot()里直接写Gate::policy(...)效果是一样的。只是我个人依然建议保留一个独立的AuthServiceProvider让权限相关的代码一眼可见。你可以手动执行php artisan make:provider AuthServiceProvider然后把它加到bootstrap/providers.phpLaravel 11或config/app.phpLaravel 10 及以下的providers数组里。这样即使框架不再默认生成这个文件你也能继续沿用集中管理的思路。我个人在实际项目里被这个文件救过很多次也被它坑过很多次。最典型的一次升级框架后AuthServiceProvider被移除了我却还在老文档里找$policies结果权限规则全部乱套。后来我养成了一个习惯——每次接手 Laravel 项目第一件事就是把app/Providers里每个 Provider 都看一遍尤其是AuthServiceProvider。它也许只有几行代码但就像房间里的配电箱表面只是一个铁盒子里面却决定了整个屋子哪些灯能亮哪些插座有电。你愿意花十分钟打开它后面排查权限问题就能省下十个小时。最后再分享一个小技巧写完 Policy 后顺手写一个php artisan make:test PostPolicyTest的单元测试用actingAs模拟不同用户把update、delete这些方法逐条断言。一旦AuthServiceProvider哪天被改动了测试会第一时间提醒你比线上 403 来得温柔得多。
很多 Laravel 开发者第一次打开app/Providers/AuthServiceProvider.php时十有八九会愣一下这个文件里明明只有几行代码一个protected $policies空数组一个boot()方法里调用registerPolicies()然后就没了。可就是这寥寥几行牵扯出 Laravel 权限体系的一整套设计。我为什么对这个文件这么上心因为在真实项目里我见过太多因为不懂它而把权限写成一坨的人——有人把判断逻辑堆在 Controller 里有人把 Policy 注册错了位置导致线上 403 半天查不出原因还有人干脆把整个文件删了结果所有授权方法全部失效。所以我想用庖丁解牛的方式把这个文件从头到尾拆开看看它到底凭什么能牵动整个权限系统。1. AuthServiceProvider是干什么的——先搞明白它的“官位”1.1 服务提供者Laravel的“总开关”Laravel 框架启动时会执行两次“遍历服务提供者”的动作一次是调用所有 Provider 的register()一次是调用所有 Provider 的boot()。你可以把服务提供者理解成一个个电源插头register()是插上电boot()是按下开关。框架本身自带的强大功能比如数据库、队列、缓存全都靠这些插头供电。app/Providers目录下的AuthServiceProvider、RouteServiceProvider、EventServiceProvider都是项目级插头专门给应用接入相应的能力。很多初学者容易把这里的register()方法理解成“注册路由”或者“注册模型”其实它是“往容器里绑定东西”。AuthServiceProvider默认没有register()方法因为它继承的基类里已经完成了必要的绑定但它有boot()而boot()正是整个授权体系点火的地方。1.2 AuthServiceProvider是授权的中枢不是认证的中枢这里必须先把概念拧清楚Laravel 里的“认证”Authentication 和“授权”Authorization 是两码事。认证解决的是“你是谁”登录、session、token 都归它管授权解决的是“你能干什么”比如编辑这篇文章、删除那个评论、查看后台报表。AuthServiceProvider名字里带Auth但主职是后者——它是 Laravel 授权系统Gate 和 Policy的注册中枢。认证相关配置在config/auth.php和app/Http/Kernel.php的auth中间件里别被名字带偏。在AuthServiceProvider里你干的最多的事就是两件把某个模型和某个策略类绑定起来或者直接用Gate::define()定义一条能力规则。前者叫 Policy策略后者叫 Gate闸门。Policy 适合围绕一个模型写一整套 CRUD 权限Gate 适合定义独立的能力点比如“是否允许导出报表”。它们最终都会归入同一个Gate实例在业务代码里用Gate::allows()、can、$user-can()等方式触发。1.3 为什么你要读懂这个文件我见过不少项目权限判断撒得满世界都是if(auth()-user()-role admin)直接写在 Blade 模板里if($post-user_id auth()-id())写在 Controller 里用户表加个is_admin字段就号称做了 RBAC。短期看是爽了等业务复杂起来你会发现在十个地方维护着八九种“判断逻辑”改一次权限模型能改到怀疑人生。AuthServiceProvider存在的意义就是把这些零散的判断收拢到一个“总闸门”里。读懂它你就掌握了 Laravel 权限系统的心脏Policy 绑定、Gate 定义、超级管理员规则、主键模型授权。后面排查 403、写单元测试、做接口权限控制都会顺很多。2. 庖丁解牛把默认代码拆到骨头里2.1 命名空间和 use一张“依赖清单”拿 Laravel 10 里自动生成的AuthServiceProvider.php来说默认内容长这样?php namespace App\Providers; use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider; use Illuminate\Support\Facades\Gate; class AuthServiceProvider extends ServiceProvider { protected $policies [ // App\Models\Model App\Policies\ModelPolicy, ]; public function boot() { $this-registerPolicies(); Gate::before(function ($user, $ability) { // }); } }第一行namespace App\Providers决定了这个类的“门牌号”。第二三行use是两张依赖清单一个是从框架基类继承过来的AuthServiceProvider为了不被同名类搞混这里被别名成了ServiceProvider另一个是门面Gate后面的Gate::before()靠它才能调用。如果你在boot()里写Gate::define(...)这两个use一个都不能少少了直接白屏报“Class not found”。有个细节值得注意Gate的底层其实是Illuminate\Contracts\Auth\Access\Gate这个接口的实现通过门面Facade代理访问。你在AuthServiceProvider里用的Gate::policy()本质上是在往容器里解析出来的那个 Gate 实例里注册规则。所以如果你在别的类里也用Gate同样得引入use Illuminate\Support\Facades\Gate;。2.2 类继承与 $policies 属性策略注册表这个类继承了框架的Illuminate\Foundation\Support\Providers\AuthServiceProvider而它的祖父类其实是Illuminate\Support\ServiceProvider。这意味着它天然拥有register()、boot()这两个生命周期方法以及一个专门为授权准备的$policies属性。protected $policies [ // App\Models\Model App\Policies\ModelPolicy, ];这个数组就是“策略注册表”键是模型类名值是策略类名。比如protected $policies [ App\Models\Post::class App\Policies\PostPolicy::class, ];::class返回的字符串就是类的完整命名空间比手写App\Models\Post更安全因为 IDE 能帮你跳转和检查拼写。我把这个数组理解成一张“员工花名册”Markdown 模型对应 MarkdownPolicy 策略Comment 模型对应 CommentPolicy 策略。哪天来了新模型要加权限只需在这张表里加一行registerPolicies()会自动去注册。为什么通过数组而不是直接在boot()里一行行写Gate::policy()因为数组声明是声明式的一眼就能看出模型和策略的映射关系而且基类registerPolicies()已经帮我们循环处理了你不用自己动手。如果你想在boot()里手动加也可以写Gate::policy(Post::class, PostPolicy::class)效果完全一样只是不在这张表里。2.3 boot() 与 registerPolicies()点火的瞬间boot()方法会在服务容器准备好之后执行这时候所有 Provider 都已经完成了register()阶段的注册框架的基础设施比如数据库、缓存也都可用了。AuthServiceProvider里的boot()首先调用了$this-registerPolicies()。这个registerPolicies()是基类提供的方法它的内部实现其实很简单大致是public function registerPolicies() { foreach ($this-policies as $key $value) { Gate::policy($key, $value); } }它把$policies数组里的每一对映射都转发给Gate::policy()。所以你在boot()里写的顺序很重要如果先写了Gate::define(custom, ...)再调用registerPolicies()通常也没问题因为这两者不是互相覆盖的关系但如果你在registerPolicies()之后又重新给同一个模型绑定了另一个 Policy那毫无意义甚至可能混淆。我习惯把$this-registerPolicies()放在boot()的第一行然后才开始定义自定义 Gate 或Gate::before()这样逻辑上最干净。2.4 被删掉的 AuthServiceProvider新版本发生了啥到了 Laravel 11你会发现php artisan make:provider AuthServiceProvider出来的项目里根本没有这个文件因为框架认为不再需要你手动维护 Policy 映射了——Policy 自动发现已经足够聪明。Laravel 会自动到app/Policies目录里找与模型同名的策略类规则是你在route或auth中调用Gate::authorize(update, $post)时框架拿$post的类名比如App\Models\Post截掉Models前缀得到Post再去App\Policies\PostPolicy找。所以新版项目里AuthServiceProvider默认不再生成这也导致很多习惯了老版本的开发者找不着北我原本写在AuthServiceProvider里的Gate::before()超级管理员逻辑去哪写两个去处一是手动创建一个AuthServiceProvider并在config/app.php的providers数组里注册二是直接写到现有的AppServiceProvider::boot()。我个人更倾向新建一个专用 Provider因为权限相关的东西集中在一起以后维护方便。我的建议是不管新老版本你都要理解这个文件的工作原理因为老项目里它还在新项目里你随时可能被迫“再造一个”出来。3. 实操让 Policy 真正跑起来3.1 三步创建 Policy以一个典型的博客系统为例文章属于作者作者可以管理自己的文章管理员可以管理所有文章。第一步用 Artisan 命令生成策略类php artisan make:policy PostPolicy --modelPost--modelPost参数会自动生成包含viewAny、view、create、update、delete、restore、forceDelete这些方法的骨架并在方法里填好类型提示。生成的PostPolicy默认长这样以 Laravel 10 为例?php namespace App\Policies; use App\Models\Post; use App\Models\User; class PostPolicy { public function viewAny(User $user): bool { // } public function view(User $user, Post $post): bool { // } public function update(User $user, Post $post): bool { return $user-id $post-user_id || $user-isAdmin(); } }第二步如果项目是 Laravel 11 之前把策略注册到AuthServiceProvider的$policies数组里如果是 Laravel 11并且模型放在app/Models、策略放在app/Policies自动发现就能找到不需要注册。第三步在 Controller 或路由里调用授权。3.2 手动注册还是自动发现怎么选手动注册和自动发现并不是互斥的。手动注册的优先级更高你写在$policies里的映射会覆盖自动发现的结果。什么情况下需要手动注册模型不在app/Models目录比如放在app/Domain/Post、策略类名不符合PostPolicy这种命名规则、或者你有多个策略类对应同一个模型的不同场景都需要手动注册。我整理了一个简单的选择表场景自动发现手动注册标准模型标准策略推荐不必要模型在自定义命名空间不生效必须策略类名带额外后缀不生效必须需要动态切换策略不推荐推荐想集中查看所有策略映射看不清推荐实际项目里我一般折中标准模型交给自动发现特殊映射在AuthServiceProvider里手动注册。这样既省事又不会因为某个“奇怪路径”导致 403。3.3 在 Controller 和 Blade 里“用权”定义好 Policy 之后使用方式有很多种。最推荐的是在 Controller 方法里调用$this-authorize()因为App\Http\Controllers\Controller自带AuthorizesRequeststraitpublic function update(Request $request, Post $post) { $this-authorize(update, $post); // 更新逻辑... }这行代码相当于当前登录用户是否有权限执行update能力作用于$post。没有权限时框架会直接抛出AuthorizationException最终渲染成 403 页面。如果你更喜欢显式判断可以这样写if ($request-user()-cannot(update, $post)) { abort(403, 你无权编辑这篇文章); }这里用了cannot()语义是“如果用户不能做就拒绝”。反过来用Gate::allows()也一样但注意allows和denies是相反的逻辑别搞混。在 Blade 模板里最常见的用途是控制按钮显示can(update, $post) a href{{ route(posts.edit, $post) }}编辑/a endcancan指令背后调用的就是Gate::allows所以权限逻辑始终只有一份Controller 和模板都能复用。3.4 高级玩法Gate::before 超级管理员与自定义 Gate业务里最常用的“管理员通吃一切”需求用Gate::before()实现最优雅。在boot()里加上public function boot() { $this-registerPolicies(); Gate::before(function ($user, $ability) { if ($user-isAdmin()) { return true; } }); }Gate::before()的回调会在所有 Policy 和Gate::define()判断之前执行。如果它返回true直接放行返回false直接拒绝返回null则继续走后面的正常授权判断。这里千万注意如果回调里写了return false等于把所有权限都关了容易出大事故。我只在Gate::before里返回true或什么都不返回即null绝不轻易返回false。除了 PolicyGate::define()还能定义独立能力适合“导出报表”“审批流程”这类不绑定单一模型的操作Gate::define(export-reports, function ($user) { return $user-department operations; });然后业务代码里直接Gate::authorize(export-reports);这样就能把散落的判断逻辑全部收进AuthServiceProviderController 里干净到让人感动。4. 常见问题与排查技巧实录4.1 线上 403Policy 没注册还是没找到403 是权限系统最常见的报错但原因可能千奇百怪。按顺序排查第一请求是否真的登录了auth()-user()是否为nullPolicy 里的$user参数是否为 null 导致异常。第二Policy类是否存在、命名是否正确。第三如果是手动注册AuthServiceProvider的$policies数组是否正确填写boot()里有没有调用registerPolicies()。第四如果是自动发现检查模型和策略的命名空间是否符合规则。我踩过一次很深的坑PostPolicy文件方法写的是public function update(User $user, Post $post)但调用授权时传的是$this-authorize(update, $post-author)把目标传成了另一个用户对象。框架去查找UserPolicy结果自然没有直接抛 403。排查了半天才意识到$this-authorize()的第二个参数必须是“被操作模型实例”而不是“发起操作的人”。这类问题很容易被忽视建议你在写 Policy 方法之前先用php artisan route:list或者单元测试确认参数传递没问题。4.2 自动发现为何“失灵”自动发现是 Laravel 7 之后引入的能力但它的触发条件比很多人想象中严格。它要求模型类名与策略类名的“驼峰对应”关系成立App\Models\Post对应App\Policies\PostPolicyApp\Models\ProductCategory对应App\Policies\ProductCategoryPolicy。如果你的模型并没有放在app/Models下比如放在app/Entities那自动发现就找不到——除非你调用Gate::guessPolicyNamesUsing()自定义规则否则只能手动注册。还有一个隐蔽情况模型类名是Post但策略类文件命名成PostPolicy.php里面类名却写成PostPolicyRulePHP 类名与文件名不匹配自动加载都过不去更别提自动发现了。出现“我明明有PostPolicy为什么它就是不用”的诡异现象时先跑一下composer dump-autoload。因为新增的 Policy 类如果没有被框架自动发现到往往是 composer 的类映射缓存没有刷新这在部署流程中特别常见。4.3 改了没反应是缓存在作祟线上项目经常开php artisan config:cache和php artisan route:cache但确确实实有开发者会忘记清缓存。当你改了AuthServiceProvider里的Gate::define后如果业务代码里一直拿旧逻辑在跑第一反应就应该是php artisan optimize:clear这条命令会清掉配置、路由、缓存、视图所有常见缓存。生产环境我一般执行php artisan optimize:reload或者部署脚本里做php artisan optimize后再清缓存。另外如果AuthServiceProvider是新加的并且手动在config/app.php的providers数组注册过记得也要清一下配置缓存否则 Provider 列表可能还是旧的。4.4 Gate 与 Policy 的使用边界很多人上来就在 Controller 里用Gate::define但用着用着发现代码越来越乱原因是没有区分 Gate 和 Policy 的职责。我的经验法则如果一个能力与某个具体模型对象强相关比如修改文章、删除评论请用 Policy因为它是面向模型的如果一个能力与模型类型无关比如查看后台仪表盘、执行系统维护请用Gate::define因为它是面向操作的。如果你两者混用可能会出现同一个动作既在 Policy 里定义又在 Gate 里定义然后Gate::before一插进来行为更难预测。Laravel 的判断顺序是先走Gate::before回调再走Gate::define定义的具体能力最后才尝试自动解析 Policy。如果你使用Gate::authorize(update, $post)这个update能力会先去 Gate 里找有没有update的define找不到再用 Policy 的update方法。因此如果你在Gate::define(update, ...)里写了一套逻辑又在PostPolicy::update写了另一套真正生效的是Gate::define那套。要避免这种“双写”的混乱统一走 Policy 或统一走 Gate别一条路拆成两半。5. 权限设计的心法从文件到架构5.1 AuthServiceProvider 之外的选择如果你的项目已经演进到需要“角色 权限”的完整 RBAC可以考虑社区方案比如spatie/laravel-permission。它提供角色、权限的数据库存储和管理界面并且能很好地和 Laravel 自带的Gate体系兼容。它本质上做的事情和AuthServiceProvider一样把权限规则注册进 Gate。你可以在它的boot()里看到大量Gate::define和Gate::before只是这些规则是动态从数据库里读出来的。但这不代表你可以完全无视AuthServiceProvider。即便用了第三方库你还是需要在这个 Provider或者AppServiceProvider里定义自己的Gate::before超级管理员逻辑或者处理一些特殊策略。而且第三方库在复杂规则下的性能不如静态 Policy我的建议是中小项目直接写 Policy别为了一两个角色引入大包大项目可以用第三方做基础但把核心权限规则仍然留在代码里避免把权限全部搬进数据库导致性能失控。5.2 权限设计的“三不”原则在拆过太多权限项目之后我总结出三条心法。第一不要在 Controller 里写if($user-id $model-user_id)这种裸判断。一旦要加管理员、超管、团队权限你要改一堆 Controller而如果统一放进 Policy只需要动一个文件。第二不要在每个模型里复制粘贴同一个isAdmin()判断。把“是否管理员”放到User模型的方法里并且在Gate::before里只用一次全局生效。第三不要顺着一股脑用Gate::allow而不考虑性能。在列表遍历时每行调用一次 Policy 方法会有 N 次查询要用Post::query()-where(user_id, $user-id)这类预筛选权限只是最后一道防线不是查询优化方案。5.3 兼容 PHP 8 与 Laravel 11 的现代化写法PHP 8 之后Policy 类可以写得更紧凑。比如用构造器属性提升来自动注入依赖class PostPolicy { public function __construct( private readonly PostRepository $posts, ) { } public function update(User $user, Post $post): bool { return $user-id $post-user_id; } }这在AuthServiceProvider里并不会增加额外负担因为 Policy 是通过容器解析的构造器里的依赖会自动注入。Laravel 11 之后如果项目里没有AuthServiceProvider你也可以在AppServiceProvider::boot()里直接写Gate::policy(...)效果是一样的。只是我个人依然建议保留一个独立的AuthServiceProvider让权限相关的代码一眼可见。你可以手动执行php artisan make:provider AuthServiceProvider然后把它加到bootstrap/providers.phpLaravel 11或config/app.phpLaravel 10 及以下的providers数组里。这样即使框架不再默认生成这个文件你也能继续沿用集中管理的思路。我个人在实际项目里被这个文件救过很多次也被它坑过很多次。最典型的一次升级框架后AuthServiceProvider被移除了我却还在老文档里找$policies结果权限规则全部乱套。后来我养成了一个习惯——每次接手 Laravel 项目第一件事就是把app/Providers里每个 Provider 都看一遍尤其是AuthServiceProvider。它也许只有几行代码但就像房间里的配电箱表面只是一个铁盒子里面却决定了整个屋子哪些灯能亮哪些插座有电。你愿意花十分钟打开它后面排查权限问题就能省下十个小时。最后再分享一个小技巧写完 Policy 后顺手写一个php artisan make:test PostPolicyTest的单元测试用actingAs模拟不同用户把update、delete这些方法逐条断言。一旦AuthServiceProvider哪天被改动了测试会第一时间提醒你比线上 403 来得温柔得多。
到O(n)的经典算法)
