如何设置Laravel模型作用域实现全局与局部查询范围？

本文共计983个文字，预计阅读时间需要4分钟。

模型以下内容为模型生成的结果，直接输出，不包含图片解释，不涉及数字，不超过100字。

全局作用域必须注册到 boot 方法里才生效

很多人把全局作用域类写好了，却在模型里漏掉 static::addGlobalScope() 调用，结果查出来的数据完全没受限制。

• 必须在模型的 boot 静态方法中注册，不能放在构造函数或其它任意位置
• 注册顺序影响最终 SQL：后注册的作用域会包裹在先注册的外层（类似中间件洋葱模型）
• 如果用了软删除（SoftDeletes），Laravel 自动加了 where deleted_at is null，你的全局作用域会套在这个条件外面，可能意外屏蔽掉本该查到的数据

class User extends Model { protected static function boot() { parent::boot(); static::addGlobalScope(new ActiveUserScope()); // ✅ 正确位置 } }

局部作用域命名要带 scope 前缀，且只能用静态方法

不加 scope 前缀，Eloquent 就不认识这是作用域；写成实例方法（public function），调用时直接报错 Call to undefined method。

• 方法名必须以 scope 开头，比如 scopeActive()、scopeByCategory()
• 参数从第二个开始算（第一个始终是 $query），支持可选参数，但别默认传复杂对象
• 返回值必须是 $query 实例，不能 return true / null / array

class Post extends Model { public function scopeActive($query, $includeDraft = false) { $query->where('status', 'published'); if ($includeDraft) { $query->orWhere('status', 'draft'); // ⚠️ 注意 and/or 逻辑 } return $query; // ✅ 必须返回 } }

withoutGlobalScope() 和 withoutScopes() 的区别很实际

想临时绕过某个全局作用域？用 withoutGlobalScope()；想彻底清空所有（包括软删除、你自定义的、第三方包加的），才用 withoutScopes()。

• withoutGlobalScope(ActiveUserScope::class) 只剔除指定类的作用域
• withoutScopes() 会连 SoftDeletes 的 where 条件都干掉，查出来的可能包含已删除记录
• 这两个方法只对当前链式调用生效，不影响后续查询或模型其它实例

User::withoutGlobalScope(ActiveUserScope::class)->get(); // ✅ 只跳过 ActiveUserScope User::withoutScopes()->get(); // ⚠️ 所有全局作用域都没了，含软删除

作用域里别直接执行 get() 或 first()

作用域本质是“修改查询构建器”，不是“执行查询”。一旦在里面调 $query->get()，这个作用域就变成命令式执行，没法再链式拼接其它条件，后续 ->orderBy() 或 ->with() 全部失效。

• 所有数据库操作（get、count、update）必须交给调用方决定
• 如果真需要预加载关联，用 $query->with(...)，而不是 $query->with(...)->get()
• 调试时想看生成的 SQL？用 toSql()，但它只是字符串，不能和 get() 混用

// ❌ 错误：提前执行，链式中断 public function scopeLatest($query) { return $query->orderBy('created_at', 'desc')->get(); // 别在这 get！ } // ✅ 正确：只构建，不执行 public function scopeLatest($query) { return $query->orderBy('created_at', 'desc'); }

作用域最麻烦的地方不在写法，而在它的“隐形影响力”：一个全局作用域可能让整张表的读写行为突然变样，而错误往往只出现在特定分支逻辑里，比如后台导出、定时任务、API 管理端——这些地方容易忘记检查是否被作用域干扰。