Map.groupBy()是JavaScript ECMA2024新增的静态方法，用于对可迭代对象按回调函数返回值分组，返回Map实例，支持任意类型键，浏览器Chrome 129+/Firefox 128+/Safari 17.4+已支持。
Map.groupBy() 不是 HTML 的方法，也不是 DOM API 的一部分——它是 JavaScript（ECMAScript 2024）新增的静态方法，作用对象是可迭代集合（如 Array），返回值是 Map 实例。浏览器支持从 Chrome 129+、Firefox 128+、Safari 17.4+ 开始（截至 2026 年 5 月，主流新版均已支持，但旧版或 Electron 等嵌入环境仍需检查）。
Map.groupBy() 的基本用法和参数差异
Map.groupBy() 接收两个参数：items（可迭代对象）和 callback（分组键生成函数）。它不修改原数组，也不接受初始值或累加器逻辑，和 Array.prototype.reduce() 有本质区别。
-
callback必须返回一个值（不能是undefined或null），否则该元素会被丢弃（不是报错，而是静默跳过） - 返回的键可以是任意类型（
string、number、Symbol、甚至object或function），Map天然支持，这点比Object.groupBy()更灵活 - 如果回调返回
NaN，它会被当作独立键（NaN !== NaN，但Map内部用 SameValueZero 比较，所以多个NaN会归到同一组）
示例：
const items = [
{ id: 1, type: 'user', active: true },
{ id: 2, type: 'admin', active: false },
{ id: 3, type: 'user', active: true }
];
const grouped = Map.groupBy(items, item => item.type);
// Map(2) { 'user' => [{...}, {...}], 'admin' => [{...}] }
grouped.get('user').length; // 2
常见错误现象：undefined 键、空 Map、类型误判
最常踩的坑是回调函数没做兜底，导致部分元素被过滤掉，最终 Map 少了预期的 key。
- 回调中访问
item.status?.toLowerCase()，但status是undefined→ 返回undefined→ 该元素不进入任何组 - 用
item.category.id作键，但某些category是null→ 报TypeError: Cannot read property 'id' of null（不是静默失败） - 误把
Map.groupBy()当成Array.prototype.groupBy()调用（后者不存在）→TypeError: Array.prototype.groupBy is not a function - 在不支持的环境中运行（如 Node.js 20.x 默认未启用，需加
--harmony-array-grouping标志；Webpack/Babel 默认不 polyfill）→ 运行时报错或回退到手动实现
为什么不用 Object.groupBy() 而选 Map.groupBy()
当你需要以下任一能力时，Map.groupBy() 是更稳妥的选择：
立即学习“前端免费学习笔记（深入）”；
- 分组键是对象或函数（例如按
{ priority: 1, level: 'high' }分组），Object.groupBy()强制转为[object Object]，所有键撞成一个 - 后续要迭代分组结果并保留插入顺序（
Map保证，Object在 ES2015+ 虽也保证字符串键顺序，但 Symbol 键顺序不一致） - 需要频繁增删某组（
map.get(key)?.push(...)+map.set(key, newValue)），Map的get/set是 O(1)，且避免了Object.entries()→reduce()→Object.fromEntries()的冗余转换 - 与已有
Map流程集成（比如你已用Map做缓存索引，现在想复用同一数据结构）
注意：Object.groupBy() 返回 plain object，没有 entries() 方法，必须先 Object.entries(grouped) 才能遍历；而 Map.groupBy() 返回的 Map 可直接 for (const [key, values] of grouped) { ... }。
兼容性 fallback：如何安全降级
不要依赖全局检测 typeof Map.groupBy === 'function' 后再分支调用——ES2024 规范要求它必须是静态方法，但 polyfill 很难完美模拟其行为（尤其对非字符串键的支持）。更务实的做法是封装一层：
function safeGroupBy(items, keyFn) {
if (typeof Map.groupBy === 'function') {
return Map.groupBy(items, keyFn);
}
// 降级：手动构建 Map
const map = new Map();
for (const item of items) {
const key = keyFn(item);
if (key === undefined || key === null) continue;
const group = map.get(key) ?? [];
group.push(item);
map.set(key, group);
}
return map;
}
// 使用
const result = safeGroupBy(data, x => x.category);
这个 fallback 显式跳过 undefined/null，行为与原生一致；且不依赖 Object.groupBy（它本身不支持任意键类型，fallback 逻辑反而更通用）。
真正容易被忽略的是：分组后若需对每组再做聚合（比如统计数量、求平均值），别直接在 Map.values() 上链式调用 .map().reduce() ——先确认是否真需要中间数组。对超大数据量，用 for...of 遍历 map.entries() 手动累积，内存更可控。
