laravel Collection 使用需规避构造传非数组/NULL、Filter/reject 布尔逻辑陷阱、map 忘 return、when/unless 链中断及大数内存爆满等问题。
Collection 构造时别直接传 null 或数组以外的类型
Collection 构造函数会静默把 null 转成空集合，但如果你传了个对象、字符串或资源句柄，会抛 TypeError：“Argument 1 passed to IlluminateSupportCollection::__construct() must be of the type Array or null”。尤其在从请求或数据库取值后没做判空就直接 collect($data)，容易翻车。
实操建议：
- 从 DB 查询结果（如
$users = User::where(...)->get()）直接调用->map()等方法即可，它本身就是Collection，无需再collect($users) - 处理可能为
null的变量时，显式判空：collect($data ?? []) - 若来源是 json 字符串，先
json_decode($json, true)再传入，否则会报错
filter() 和 reject() 的闭包返回值必须明确为布尔值
很多人写 $collection->filter(fn($item) => $item['status'])，以为非空即真，但 PHP 中 0、false、'' 都会被过滤掉——这常导致 status=0 的记录意外消失。Laravel 的 filter() 不做类型转换，只看闭包返回值是否为 truthy。
实操建议：
- 显式比较：
filter(fn($item) => $item['status'] === 1)或filter(fn($item) => in_array($item['status'], [1, 2])) - 用
reject()替代双重否定：比如要排除已删除的，写reject(fn($item) => $item['deleted_at'] !== null)比filter(fn($item) => $item['deleted_at'] === null)更直觉 - 注意 key 保留逻辑：
filter()后 key 不重排，如果后续依赖数字索引（如分页切片），得接values()
使用 map() 改结构时别漏掉 return
闭包里忘记写 return 是高频错误。比如 $collection->map(fn($user) => $user->name) 看似没问题，但若改成多行逻辑：$collection->map(fn($user) => { $user->name . ' (active)'; })，结尾没 return 就会全变成 null。
实操建议：
- 单表达式用箭头函数最安全：
map(fn($u) => ['id' => $u->id, 'label' => $u->name]) - 多行逻辑务必检查 return：
map(fn($u) => { return ['id' => $u->id, 'label' => strtoupper($u->name)]; }) - 想原地修改对象属性？
transform()更合适，它不生成新集合，而是直接改原数据
when() 和 unless() 在链式调用中容易误判条件上下文
when() 的第一个参数是条件，第二个是回调；但它只在条件为 truthy 时执行回调，且回调接收当前集合作为参数——但很多人以为回调里能直接用外部变量，或者忘了回调必须返回集合（否则链中断）。比如：$collection->when($search, fn($c) => $c->filter(...)) 没问题，但若写成 when($search, fn($c) => $c->filter(...)->dd())，dd() 不返回集合，后面方法就挂了。
实操建议：
- 回调里所有操作必须返回
Collection实例，避免调用dd()、dump()、each()等不返回集合的方法 - 条件本身别依赖集合状态：比如
when($collection->isNotEmpty(), ...)是错的，因为$collection此时还没被前面的方法处理过，应改用中间变量或拆链 - 复杂条件组合优先用普通 if，别硬塞进
when()，可读性差还难调试
Collection 的懒加载特性（比如 LazyCollection）和内存占用差异，在大数据量下不是“用了就快”，而是“不用就崩”。真正卡住的往往不是写法，是没意识到 map() 或 filter() 在 10 万条数据上会立刻全量加载到内存。