map 必须返回新对象而非修改原数组，正确做法是显式返回新对象并注意空值处理、类型转换、嵌套解构及 TypeScript 泛型标注。
map 不能直接修改原对象，必须返回新对象
很多开发者以为 map 会就地更新数组元素，结果发现 API 返回的 data 字段没变——其实 map 的设计原则就是纯函数：它只生成新数组，不碰原数据。如果你在回调里只做赋值（比如 item.name = item.title）却不 return，那整个新数组全是 undefined。
正确做法是显式返回一个新对象：
apiData.map(item => ({
id: item.id,
title: item.name || item.product_name,
price: Number(item.cost) || 0,
status: item.is_active ? 'active' : 'inactive'
}));- 别用
Object.assign(item, {...})或扩展原对象，这破坏了不可变性，后续 diff 或缓存可能出错 - 字段名不一致时优先用逻辑运算符（
||、??）兜底，而不是写一堆if - 数值类字段务必显式转换，比如
Number(item.count)，避免字符串拼接 bug
嵌套字段映射时，map 要配合解构和可选链
真实 API 常有 user.profile.full_name 或 items[0].sku.code 这类结构，直接访问容易报 Cannot read property 'profile' of undefined。
安全写法是结合解构默认值和可选链：
立即学习“前端免费学习笔记（深入）”；
apiData.map(({ id, user = {}, items = [] }) => ({
id,
userName: user?.profile?.full_name ?? 'Unknown',
firstSku: items[0]?.sku?.code ?? null,
tagList: items.map(i => i.tag || 'default')
}));-
user = {}防止解构时报错；??比||更适合处理0、false等假值 - 深层嵌套字段不要连写
user.profile.full_name.toLowerCase()，先取值再操作，否则一环为undefined就崩 - 如果嵌套数组也要映射（比如
items），就在内层再套一层map，别试图用单层map处理多级
遇到 null/undefined 元素时，map 仍会保留空位，需提前过滤
有些后端返回的数组里混着 null 或 undefined（比如分页漏数据、关联查询失败），这时 map 依然会为它们执行回调，并返回 undefined 元素——前端渲染时可能报错或显示空白项。
稳妥做法是先 filter 再 map：
apiData
.filter(item => item && typeof item === 'object')
.map(item => ({ /* 映射逻辑 */ }));- 别用
filter(Boolean)，它会把0、false、''也干掉，而这些可能是合法值 - 如果后端明确约定空数据用
null，那就写filter(item => item !== null)，语义更准 - 顺序不能颠倒：先
filter再map，否则map中还要反复判空，代码冗余
TypeScript 下 map 返回类型推导容易出错
TS 默认根据第一个元素推导整个数组类型，如果 API 数据不规范（比如前几条有 avatar_url，后面突然没有），TS 可能推成 string | undefined，导致后续调用 .length 报错。
显式标注返回类型最稳：
apiData.map<FrontendItem>(item => ({
id: item.id,
title: item.name,
avatar: item.avatar_url ?? ''
}));其中 FrontendItem 是你定义的接口。不加泛型时，哪怕写了 as FrontendItem 在 return 后面，TS 也不保证数组整体类型安全。
- 别依赖 IDE 自动补全的类型提示，它有时会“妥协”于数据样本
- 如果映射逻辑复杂（比如含条件分支），一定要加泛型，否则联合类型会层层嵌套，最后变成
any - 字段缺失比字段类型错误更难调试——运行时不报错，但视图上突然少内容
实际项目里最常被忽略的是字段语义一致性：比如后端用 is_deleted 表示软删，前端模型却叫 deletedAt。这种不匹配不会让 map 报错，但会让业务逻辑散落在各处。映射不是翻译，是建模。
