本文详解如何在 laravel 中正确实现多字段（主模型 id/名称 + 关联模型 sku）联合搜索，解决因 `orwhere` 优先级导致的查询失效问题，并提供可扩展、安全、高效的 eloquent 实现方案。
在 Laravel 中实现跨字段、跨模型的搜索功能时，一个常见却极易被忽视的陷阱是 orWhere() 的作用域问题：当它与 where() 混用且未显式分组时，Eloquent 会生成不符合业务逻辑的 SQL OR 条件，导致关联查询失效（如您遇到的 SKU 不返回结果的问题）。
根本原因在于：您原始代码中将 ->orWhere('id', '=', $request->search) 直接置于主查询链末端，而 with() 中的闭包 orWhere 又未受约束——这会使最终 SQL 的 WHERE 子句变成类似：
WHERE (products.name LIKE '%xxx%') OR (products.id = 'xxx') -- 但 getProductItem 的关联条件被降级为独立 OR 分支，而非嵌套在 JOIN 条件中
更严重的是，with() 中使用 orWhere() 并不会自动影响主查询的 WHERE 逻辑，它仅控制预加载的关联数据过滤，无法用于主结果集的筛选。因此，SKU 匹配必须通过 whereHas() 显式声明关联存在性。
✅ 正确做法是：使用 whereHas() 定义“产品必须拥有匹配 SKU 的关联项”，并用闭包内嵌 where() + orWhere() 组合，配合 DB::raw() 或子查询确保逻辑分组：
use Illuminate\Support\Str;
$search = $request->input('search');
$exactMatch = $request->boolean('match'); // 更安全地获取布尔值
$products = Product::query();
// 条件1：匹配 product_id（精确）
$products->when($search, function ($query) use ($search) {
return $query->where('id', $search);
});
// 条件2：匹配 product_name（支持模糊/精确）
$products->when($search, function ($query) use ($search, $exactMatch) {
if ($exactMatch) {
return $query->orWhere('name', $search);
} else {
return $query->orWhere('name', 'like', '%' . $search . '%');
}
});
// 条件3：匹配关联表 product_items.itemSkuNumber（必须用 whereHas）
$products->when($search, function ($query) use ($search) {
return $query->whereHas('getProductItem', function ($subQuery) use ($search) {
$subQuery->where('itemSkuNumber', $search);
});
});
// 合并所有条件（注意：此处用 orWhereGroup 需手动分组，但更推荐 above 的 when 链式写法）
return $products->distinct()->get();⚠️ 关键注意事项：
- 永远避免裸 orWhere() 与 where() 混用：除非用 where(function ($q) { ... }) 显式包裹形成逻辑组；
- 关联字段搜索必须用 whereHas()：with() 只负责加载，不参与主查询过滤；
- 防止 SQL 注入：切勿直接拼接 $request->search 到查询中，Eloquent 参数绑定已默认防护，但需避免 DB::raw("...{$search}...")；
- 性能优化建议：为 products.name、products.id 和 product_items.itemSkuNumber 字段添加数据库索引；
- 扩展性提示：如需支持全文搜索或高并发场景，后续可平滑迁移至 Laravel Scout + Algolia/Meilisearch。
综上，一个健壮的多字段搜索应以「主模型条件 + 关联存在性断言」为骨架，通过 when() 动态构建、whereHas() 精准关联、distinct() 去重，兼顾可读性、安全性与可维护性。
