React列表key警告疑难：已配置唯一key仍触发该警告

已为列表项配置唯一key属性，React开发者工具也显示各列表项的key值完全不同，但仍持续收到「Each child in a list should have a unique "key" prop」警告。该问题在SSR场景及用Material-UI的NoSsr组件包裹的非SSR场景下均存在，且项目中其他列表未出现此类问题，完全无从下手。

简化代码示例 #

index.tsx

export default function Index() {
    return (
        <Box display="flex">
            {items.map((item) => (
                <Item key={item.id} {...item} />
            ))}
        </Box>
    )
}

items.ts

export const items = [
    {
        id: 1,
        text: 'item 1',
    },
    {
        id: 2,
        text: 'item 2',
    },
]

Item.tsx

export const Item = ({ text }) => <Box>{text}</Box>;

项目依赖版本 #

• react: 18.2.0
• @mui/material: 5.10.1
• next: 12.2.5
• styled-components: 5.3.5
• 已启用babel-plugin-styled-components

排查方向及解决方案 #

1. 检查组件内部的嵌套列表
   警告可能并非来自外层的items.map，而是Item组件内部或Material-UI Box底层渲染的列表结构遗漏了key。仔细检查Item的实现细节，包括第三方组件生成的子元素，确认没有未加key的列表项。

2. 强制转换key的类型为字符串
   尽管item.id是数字，但在SSR或styled-components的场景下，类型隐式转换可能导致React无法正确识别key。尝试将key转为字符串：key={String(item.id)}，再观察警告是否消失。

3. 排查Next.js SSR与客户端Hydration不匹配
   Next.js中服务端渲染的DOM与客户端生成的DOM结构不一致时，可能触发虚假的key警告。可以：

   • 确认服务端和客户端的items数据完全同步，避免服务端异步加载数据但客户端初始数据不同的情况
   • 在getServerSideProps或getStaticProps中确保数据一致，消除hydration mismatch

4. 排查styled-components与Material-UI的冲突
   同时使用两者可能存在组件包装或样式注入顺序的问题，干扰React对key的识别。可以：

   • 暂时移除styled-components相关配置，验证警告是否消失，确认是否为两者冲突导致
   • 参考Next.js官方文档，调整babel-plugin-styled-components的配置，确保与Material-UI兼容

5. 用React DevTools深层检查
   展开React DevTools中列表项的所有子元素，排查是否存在隐藏的列表结构（比如Material-UI组件内部生成的列表）遗漏了key。有时候警告指向的父组件并非直观看到的外层列表。

内容的提问来源于stack exchange，提问作者yataw