map()仅适用于字段重命名和简单格式化，不可用于需分页、导出或依赖模型特性的场景；结构转换应选select()/addSelect()、mapToGroups()或mapWithKeys()等更精准方法。
直接用 map() 就能做基础映射，但多数人卡在结构错乱、键丢失、类型失控或分页崩掉——这不是方法不会用，是没分清“什么时候该用 map”和“什么时候不该碰它”。
map() 适合字段重命名和简单格式化，别碰模型结构
它只处理已加载的数据，返回新集合，不改原始查询。如果你从 User::where()->get() 拿到模型集合，再 map() 出 ['id' => $u->id, 'label' => $u->name]，没问题；但若后续要分页、导出 Excel 或传给前端分页组件，map() 后的集合已经不是 Paginator，分页元信息全丢。
- 需要保留分页？改用
select()或addSelect()在查询层投影字段 - 想加计算字段（如全名）？用
DB::raw("CONCAT(first_name, ' ', last_name) as full_name") - 模型里有
$casts或$appends？map()会绕过它们，导致类型不一致或附加属性消失
mapToGroups() 是唯一正解：按某字段聚合成键值对
当你需要 “以 company 为键、department 列表为值” 这类嵌套结构时，mapToGroups() 不是可选项，是设计初衷。它比先 groupBy('company') 再 pluck('department') 更干净，语义也更直白。
- 回调必须返回一个键值对数组，比如
[$item->company => $item->department] - 原始数据是 JSON 字符串？先
json_decode($json, false)得对象，才能用->company；用true就得改成$item['company'] - 空 company 会生成无效键，前置加
filter(fn($item) => !empty($item->company)) - 要自动去重？
mapToGroups(...)->map(fn($departments) => $departments->unique())
pluck() 和 mapWithKeys() 别混用，键行为完全不同
pluck('name') 提取单字段并扁平成索引数组；mapWithKeys() 是用来构造带自定义键的新集合，比如把 ID 当键、name 当值：mapWithKeys(fn($u) => [$u->id => $u->name])。很多人误用 map() 想保留键，结果得到全是数字索引的集合——那是 mapWithKeys() 的事。
-
map()默认重置键为 0,1,2…，除非你显式返回[$key => $value]并配合mapWithKeys() -
pluck('profile.email')支持嵌套访问，但遇到null会跳过，不是报错 - 需要键值一一对应且不丢原始键？优先检查是否真需要——很多时候
pluck()+values()更安全
真正难的不是写对一行 map()，而是判断当前这一步该在数据库查的时候做，还是在 PHP 层做，还是交给 Resource 响应类。一上来就链式调用 map()->filter()->pluck()，往往意味着你已经在绕远路了。
