本地作用域是Laravel模型中以scope开头的静态方法，用于封装常用查询条件，必须显式调用；定义时需为public static，首参为$query，支持驼峰转短横线调用；调用不可省略括号，且scope内应避免直接使用orWhere以防逻辑错误。
什么是本地作用域（Local Scope）
本地作用域是 Laravel 模型中以 scope 开头的静态方法，用于封装常用查询条件。它不是全局生效的，必须显式调用，比如 User::popular()->active()->get() 中的 popular() 和 active() 就是两个本地作用域。
如何定义和调用 scope 方法
scope 方法必须是 public、static，且第一个参数固定为 $query（即 Builder 实例），后续参数按需添加。Laravel 会自动把驼峰命名转为短横线调用（如 scopeLatestPublished() 可链式调用为 ->latestPublished()）。
class Post extends Model
{
public function scopeActive($query)
{
return $query->where('status', 'active');
}
public function scopeByCategory($query, $category)
{
return $query->where('category', $category);
}
public function scopePopular($query, $minViews = 100)
{
return $query->where('views', '>=', $minViews);
}
}
调用方式：
Post::active()->get()Post::byCategory('news')->get()Post::popular(50)->get()
注意：不能省略括号，哪怕无参也要写 ->active()，写成 ->active 会报错 Call to undefined method Illuminate\Database\Query\Builder::active()。
scope 和 where 系列方法混用时的执行顺序
本地作用域本质是提前拼接 where 条件，所有 scope 调用顺序与 where 链式调用顺序一致，最终生成 SQL 的 WHERE 子句是「从左到右」叠加的。但 scope 内部若用了 orWhere，容易引发意料外的逻辑分组问题。
- 安全写法：scope 内统一用
where、whereIn等 AND 类型约束 - 风险写法：在 scope 里直接写
$query->orWhere(...)，会导致该条件脱离主 AND 分组，可能查出不该出现的数据 - 若真需要 OR 逻辑，应改用
where(function ($q) { ... })显式包裹，例如：$query->where(function ($q) { $q->where('status', 'draft')->orWhere('status', 'pending'); });
scope 无法复用到关联查询？试试 has() 或 withWhereHas()
本地作用域只作用于当前模型的主查询，不会自动下推到 with() 加载的关联模型中。比如 User::with('posts')->active()->get() 中的 active() 只过滤 User，不筛选 Posts。
要限制关联数据，得用：
-
with(['posts' => function ($q) { $q->active(); }])—— 推荐，清晰可控 -
whereHas('posts', function ($q) { $q->active(); })—— 用于「用户有活跃文章」这类存在性筛选 -
withWhereHas('posts', function ($q) { $q->active(); })（Laravel 10.29+）—— 同时满足「加载 + 筛选」，且主模型也参与关联条件过滤
别指望给 Post 定义的 scopeActive() 能在 User::with('posts') 里自动生效；scope 不是魔法，它只是语法糖，背后仍是手动拼 query。
