🛠️ Warning: Each child in a list should have a unique “key” prop 완벽 해결법 – 원인부터 예방까지

Warning: Each child in a list should have a unique “key” prop 에러란?

React 개발을 하다 보면 콘솔 창에서 “Warning: Each child in a list should have a unique “key” prop” 경고 메시지를 자주 접하게 됩니다. 이 경고는 React에서 배열을 렌더링할 때 각 요소에 고유한 key prop을 지정하지 않았을 때 발생합니다. 많은 초보 개발자들이 이 경고를 무시하고 넘어가기도 하지만, 이는 애플리케이션의 성능 저하와 예기치 않은 렌더링 문제를 야기할 수 있습니다. React의 가상 DOM 알고리즘은 key를 사용하여 어떤 항목이 변경, 추가 또는 제거되었는지 식별하므로, 올바른 key 설정은 매우 중요합니다. 이 글에서는 이 경고가 발생하는 원인부터 실전 해결 방법, 그리고 베스트 프랙티스까지 완벽하게 안내해드리겠습니다.

에러 상세 분석

React는 효율적인 렌더링을 위해 가상 DOM(Virtual DOM)을 사용합니다. 리스트를 렌더링할 때 React는 각 요소를 추적하여 변경사항을 감지하고 실제 DOM을 최소한으로 업데이트합니다. 이때 key prop은 각 요소의 고유 식별자 역할을 합니다.

key가 없으면 React는 요소의 순서만으로 변경사항을 파악하려 하는데, 이는 다음과 같은 문제를 발생시킵니다:

• 성능 저하: React가 모든 요소를 다시 렌더링해야 할 수 있습니다
• 상태 혼란: 입력 필드의 값이 잘못된 항목에 연결될 수 있습니다
• 애니메이션 오류: 리스트 항목의 애니메이션이 비정상적으로 작동할 수 있습니다
• 컴포넌트 재사용 문제: 잘못된 컴포넌트 인스턴스가 재사용될 수 있습니다

이 경고는 개발 모드에서만 표시되지만, 프로덕션 환경에서도 동일한 문제가 발생하므로 반드시 해결해야 합니다.

발생 원인 5가지

1. key prop 완전 누락

가장 흔한 원인은 배열을 map으로 렌더링할 때 key를 전혀 지정하지 않는 경우입니다. 많은 초보 개발자들이 key의 중요성을 모르고 생략합니다.

// 잘못된 예시
const items = ['사과', '바나나', '오렌지'];
return (
  

    {items.map(item => 
{item}
)}
  
);

2. 배열 인덱스를 key로 사용

인덱스를 key로 사용하는 것은 리스트가 정적이고 재정렬되지 않을 때만 허용됩니다. 항목이 추가, 삭제, 재정렬되는 경우 인덱스 사용은 심각한 버그를 유발할 수 있습니다.

// 문제가 될 수 있는 예시
{items.map((item, index) => 
{item}
)}

3. 중복되는 key 값

데이터베이스에서 가져온 데이터에 중복된 ID가 있거나, 동일한 key를 여러 요소에 할당하는 경우 발생합니다.

4. Fragment에서 key 누락

React.Fragment를 사용할 때도 배열 내에서는 key가 필요합니다. 단축 문법 <>를 사용하면 key를 전달할 수 없으므로 React.Fragment를 명시적으로 사용해야 합니다.

5. 중첩된 리스트에서 key 누락

리스트 내부에 또 다른 리스트가 있는 경우, 각 레벨마다 key가 필요합니다. 외부 리스트에만 key를 지정하고 내부 리스트는 누락하는 실수가 자주 발생합니다.

해결방법 7가지 (코드 포함)

1. 고유한 ID 사용 (가장 권장)

데이터베이스의 고유 ID나 UUID를 key로 사용하는 것이 가장 안전하고 권장되는 방법입니다.

const users = [
  { id: 1, name: '김철수' },
  { id: 2, name: '이영희' },
  { id: 3, name: '박민수' }
];

return (
  

    {users.map(user => (
      
{user.name}
    ))}
  
);

2. 복합 key 생성

단일 필드로 고유성을 보장할 수 없다면 여러 필드를 조합하여 key를 생성합니다.

const orders = [
  { userId: 1, productId: 101, quantity: 2 },
  { userId: 1, productId: 102, quantity: 1 }
];

return (
  

    {orders.map(order => (
      

        주문: {order.quantity}개
      
    ))}
  
);

3. UUID 라이브러리 활용

고유 ID가 없는 데이터의 경우 uuid 라이브러리를 사용하여 고유 키를 생성할 수 있습니다.

import { v4 as uuidv4 } from 'uuid';

const items = ['항목1', '항목2', '항목3'].map(item => ({
  id: uuidv4(),
  value: item
}));

return (
  

    {items.map(item => (
      
{item.value}
    ))}
  
);

4. Fragment에 key 지정

Fragment를 사용할 때는 단축 문법 대신 명시적 문법을 사용하여 key를 전달합니다.

import React from 'react';

const items = [1, 2, 3];

return (
  

    {items.map(item => (
      
        
제목 {item}
        
내용 {item}
      
    ))}
  
);

5. 중첩 리스트 처리

중첩된 리스트의 경우 각 레벨에 적절한 key를 지정합니다.

const categories = [
  { id: 1, name: '과일', items: ['사과', '바나나'] },
  { id: 2, name: '채소', items: ['당근', '양파'] }
];

return (
  

    {categories.map(category => (
      

        
{category.name}
        

          {category.items.map((item, idx) => (
            
{item}
          ))}
        
      
    ))}
  
);

6. 컴포넌트 분리 시 key 전달

리스트 아이템을 별도 컴포넌트로 분리할 때는 컴포넌트 호출 시 key를 전달해야 합니다.

const ListItem = ({ item }) => {
  return 
{item.name}
;
};

const MyList = ({ items }) => {
  return (
    

      {items.map(item => (
        
      ))}
    
  );
};

7. 정적 리스트의 경우 인덱스 사용 (최후의 수단)

리스트가 절대 변경되지 않고 재정렬되지 않는다면 인덱스를 사용할 수 있습니다.

// 정적 데이터이고 절대 변경되지 않는 경우에만
const staticMenu = ['홈', '소개', '연락처'];

return (
  
);

예방법과 베스트 프랙티스

데이터 구조 설계 단계부터 고려하기

백엔드 API 설계 시 모든 리스트 데이터에 고유 ID를 포함시키는 것이 가장 좋습니다. 프론트엔드에서 임시로 ID를 생성하는 것보다 서버에서 제공하는 것이 일관성 있고 안전합니다.

ESLint 규칙 활용

eslint-plugin-react를 설치하고 react/jsx-key 규칙을 활성화하면 key 누락을 자동으로 감지할 수 있습니다.

// .eslintrc.json
{
  "extends": ["plugin:react/recommended"],
  "rules": {
    "react/jsx-key": "error"
  }
}

코드 리뷰 체크리스트

팀 프로젝트에서는 .map() 사용 시 반드시 key 존재 여부를 코드 리뷰 항목에 포함시키세요. 또한 인덱스를 key로 사용하는 경우 정당한 이유가 있는지 확인해야 합니다.

컴포넌트 추상화

자주 사용되는 리스트 패턴을 재사용 가능한 컴포넌트로 만들어 key 관리를 중앙화하면 실수를 줄일 수 있습니다.

마무리

“Warning: Each child in a list should have a unique “key” prop” 경고는 React 개발에서 가장 흔하게 접하는 문제 중 하나이지만, 올바른 이해와 적용으로 쉽게 해결할 수 있습니다. key는 단순한 경고 제거용이 아니라 React의 효율적인 렌더링과 올바른 상태 관리를 위한 필수 요소입니다. 항상 고유하고 안정적인 key를 사용하고, 인덱스 사용은 최후의 수단으로만 고려하세요. 이 글에서 소개한 해결 방법들을 프로젝트에 적용하여 더 안정적이고 성능이 뛰어난 React 애플리케이션을 개발하시기 바랍니다.