Eloquent本地作用域是可复用的查询片段封装机制，用于解决重复条件逻辑和可读性问题；不能直接用where链式调用代替，因其提供命名语义、复用性、可维护性和继承支持，而硬写where易出错且难统一维护。
什么是Eloquent本地作用域，为什么不能直接用where链式调用代替
本地作用域（Local Scopes）是 Laravel Eloquent 提供的、可复用的查询片段封装机制。它不是语法糖，而是解决「重复条件逻辑」和「可读性崩坏」的实际工具。比如 where('status', 'active')->where('deleted_at', null) 在 5 个控制器里重复出现，硬写不仅难维护，还容易漏掉某个 deleted_at 判断。
作用域必须定义为模型中的方法，且以 scope 开头（如 scopeActive()），内部必须返回 $this（即 Builder 实例），否则链式调用会中断。
- 不加
return $query→ 调用后报错Call to a member function get() on null - 方法名没带
scope前缀 → 方法不会被识别为作用域，调用时报Method does not exist - 用了
static或self→ 作用域无法继承，子模型调用失败
如何定义带参数的动态作用域（比如按时间范围筛选）
动态作用域以 scope 开头，第一个参数固定为 $query，后续参数由你定义。Laravel 不限制参数数量或类型，但注意：所有参数都必须显式传入，不能依赖闭包或全局变量。
例如定义一个按创建时间区间筛选的动态作用域：
立即学习“PHP免费学习笔记（深入）”；
public function scopeCreatedBetween($query, $start, $end)
{
return $query->whereBetween('created_at', [$start, $end]);
}
使用时：Post::createdBetween('2024-01-01', '2024-06-30')->get()。注意：$start 和 $end 必须是字符串或 DateTimeInterface 实例；若传入 null 或空字符串，whereBetween 会生成无效 SQL，需提前校验。
- 参数未做非空/类型检查 → 查询可能返回空结果但无报错，调试困难
- 在作用域里调用
$query->toSql()→ 报错，因为此时查询尚未编译，只能用于调试时临时 dump - 想支持默认值？PHP 8+ 可用命名参数，但 Eloquent 不识别，仍需手动处理默认逻辑，如
$start = $start ?? now()->subMonth()
全局作用域 vs 本地作用域：什么时候该用哪个
全局作用域（Global Scopes）自动应用到所有该模型的查询中，典型场景是软删除（SoftDeletes trait 就是靠全局作用域实现的）。而本地作用域必须显式调用，更安全、更可控。
别误以为「全局=更高级」——它恰恰是更危险的选项。一旦注册了全局作用域，所有 Post::all()、Post::find(1) 都会被拦截，连 withTrashed() 这种绕过方法都得配套写。
- 误把权限过滤逻辑写成全局作用域 → 后台管理员查不到数据，因为权限判断逻辑对所有请求一视同仁
- 多个全局作用域之间冲突（比如都修改
where条件）→ SQL 条件叠加出错，且难以定位来源 - 测试时忘记移除全局作用域 → 单元测试通过，线上却漏数据
作用域组合失效的常见原因和排查方式
两个作用域连用（如 Post::active()->published()->get()）看似没问题，但实际可能因执行顺序、条件覆盖或 Builder 状态污染而失效。最典型的例子是某个作用域里用了 $query->whereRaw('1=0') 或重置了 select 字段，导致后续作用域丢失上下文。
排查建议优先看生成的 SQL：dd(Post::active()->published()->toSql())，而不是只看返回结果。
- 某个作用域里调用了
$query->from('other_table')→ 后续作用域的 where 条件仍作用于原表，但 from 已改，SQL 报错或逻辑错位 - 作用域里用了
groupBy但没配select→ MySQL 严格模式下直接报错Expression #1 of SELECT list is not in GROUP BY clause - 作用域返回了
$query->get()而非$query→ 链式中断，后续调用报Call to a member function published() on array
作用域本质是 Builder 的修饰器，它的健壮性取决于你是否始终把它当成“可继续加工的管道”，而不是“执行终点”。这点容易被忽略，尤其当作用域最初只是临时写的单次查询逻辑。
