在 React 项目里，用 map() 把一个数组渲染成一组 JSX 元素几乎是绕不开的操作。不过很多人第一次写的时候会遇到一个困惑：明明数组里有好几项数据，渲染出来的内容却全部排在同一行，或者干脆报了警告。换行显示看似是个小问题，背后其实牵扯到 HTML 元素的默认布局行为和 JSX 的书写习惯。这篇文章就来把这个问题拆开讲清楚，并给出几种常用的解决方案。
为什么 map 渲染的内容会挤在一行
先看一段最典型的写法：
function FruitList() {
const fruits = ['苹果', '香蕉', '橙子'];
return (
<div>
{fruits.map((item, index) => (
<span key={index}>{item}</span>
))}
</div>
);
}这段代码渲染出来的结果是 苹果香蕉橙子，三个词连在一起，中间连空格都没有。原因在于 <span> 是行内元素，行内元素默认就在同一行内排列，不会自动换行。JSX 中 return 返回的结构如果没有显式的空白符，浏览器渲染时也不会帮你补上。
这里还有一个 JSX 特有的坑值得单独说明：JSX 编译后会自动剔除标签之间仅包含换行和空格的空白文本节点，所以就算你在代码里手动把每个 span 写在不同的行上，渲染结果依然是连在一起的。换行必须依靠 CSS 布局或者真实的 HTML 结构来实现，靠代码排版是没用的。
方案一：利用块级元素天然换行
最直接的做法是把行内元素换成块级元素。块级元素默认独占一行，渲染出来的列表自然就是一行一项：
function FruitList() {
const fruits = ['苹果', '香蕉', '橙子'];
return (
<div>
{fruits.map((item, index) => (
<div key={index}>{item}</div>
))}
</div>
);
}如果你渲染的本来就是列表数据，语义上更推荐使用 <ul> 配合 <li> 的组合。这样不仅换行效果自然，还符合 HTML 语义化要求，对屏幕阅读器和 SEO 都更友好：
function FruitList() {
const fruits = ['苹果', '香蕉', '橙子'];
return (
<ul>
{fruits.map((item) => (
<li key={item}>{item}</li>
))}
</ul>
);
}注意这里 key 用的是 item 本身而不是索引。当列表数据会发生变化（排序、插入、删除）时，用索引当 key 会导致 React 复用错误的元素，引起状态错乱或性能问题。只有列表完全静态、永不重排时才适合用索引。
方案二：用 CSS 控制换行
如果因为样式限制不方便换标签，比如必须保留 span 的行内特性，可以借助 CSS 实现。一种方式是给元素加 display: block 或者 white-space 相关属性：
/* 方式一：改成块级布局 */
.fruit-item {
display: block;
}
/* 方式二：在文本中插入真实换行符并保留 */
.fruit-box {
white-space: pre-line;
}white-space: pre-line 的思路是先在文本内容里拼入换行符，再让浏览器保留它。对应到 React 里可以这样写：
function FruitText() {
const fruits = ['苹果', '香蕉', '橙子'];
return (
<p className="fruit-box">
{fruits.map((item) => item).join('\n')}
</p>
);
}注意 join('\n') 里的 \n 必须是真实的换行字符，配合 pre-line 才会生效。如果你用的是普通段落样式，\n 在 HTML 里会被当作普通空白折叠掉。
另一种现代做法是 flex 布局加换行：
.fruit-container {
display: flex;
flex-wrap: wrap;
gap: 8px;
}flex 容器默认不换行，加上 flex-wrap: wrap 之后，当一行放不下时子项会自动换到下一行。这种方式特别适合标签、卡片这类需要在容器宽度内自动折行的场景，比强制一行一项灵活得多。
常见报错与注意事项
写 map 渲染列表时，有几个高频问题需要留意。第一个是每个列表项的 key 属性不能省略，否则控制台会给出警告：Each child in a list should have a unique key prop。key 要放在 map 返回的最外层元素上，如果外面还包了一层 Fragment，要把 key 写在 Fragment 上，简写形式 <> 不支持传属性，需要写成 <Fragment key={...}>。
第二个是 map 的回调写法。如果用箭头函数直接返回 JSX 对象，要用圆括号包裹而不是花括号；用了花括号就必须显式 return，否则返回 undefined，页面什么都不渲染，也不报错，排查起来很费劲：
// 正确：圆括号形式，隐式返回
{fruits.map((item) => (
<div key={item}>{item}</div>
))}
// 正确：花括号加显式 return
{fruits.map((item) => {
return <div key={item}>{item}</div>;
})}
// 错误：花括号没有 return，渲染结果为空
{fruits.map((item) => {
<div key={item}>{item}</div>
})}最后一点，map 只能用于真正的数组。如果数据来源可能是对象或者 undefined，先用 Array.isArray() 做判断，或者提供默认值 (data || []).map(...)，避免运行时报 map is not a function 这类错误。
小结
React 中 map 渲染列表的换行问题，本质上分为两步解决：先确认 HTML 结构，块级元素天然换行，行内元素则需要 CSS 介入；再根据场景选择方案，纯列表数据用 <ul> 和 <li> 最稳妥，标签卡片类布局用 flex 加 wrap 最灵活，纯文本拼接则可以走 join('\n') 配合 white-space 的路线。同时别忘了 key 的正确使用和 map 回调的书写规范，这些细节决定了列表渲染是否稳定可靠。掌握这些思路后，再遇到类似布局问题就能快速定位原因了。