Blog

도입

React 개발 중 콘솔에 “Warning: Each child in a list should have a unique “key” prop”라는 경고 메시지를 본 적이 있으신가요? 이 경고는 React 개발자라면 누구나 한 번쯤 마주치는 매우 흔한 문제입니다. 리스트를 렌더링할 때 각 항목에 고유한 key 속성을 지정하지 않으면 발생하는 이 경고는 단순해 보이지만, 제대로 이해하고 해결하지 않으면 애플리케이션 성능 저하와 예상치 못한 버그를 초래할 수 있습니다. 이 글에서는 이 경고가 발생하는 근본적인 원인부터 실전에서 바로 적용할 수 있는 해결 방법, 그리고 앞으로 이러한 문제를 예방하는 베스트 프랙티스까지 상세하게 알아보겠습니다.

에러 상세 분석

“Warning: Each child in a list should have a unique “key” prop” 경고는 React의 Virtual DOM 알고리즘이 효율적으로 작동하기 위해 필요한 key 속성이 누락되었을 때 발생합니다. React는 컴포넌트가 업데이트될 때 이전 Virtual DOM과 새로운 Virtual DOM을 비교하는 재조정(Reconciliation) 과정을 거칩니다. 이때 리스트의 각 항목을 식별할 수 있는 고유한 key가 없다면, React는 어떤 항목이 변경, 추가, 삭제되었는지 정확히 파악할 수 없습니다. 결과적으로 불필요한 DOM 조작이 발생하여 성능이 저하되고, 컴포넌트 상태가 잘못 유지되는 등의 부작용이 생길 수 있습니다. 이 경고는 개발 모드에서만 표시되며, 프로덕션 빌드에서는 나타나지 않지만 근본적인 문제는 여전히 존재합니다. 따라서 개발 단계에서 반드시 해결해야 하는 중요한 경고입니다.

발생 원인 5가지

1. key 속성 완전 누락

가장 기본적인 원인은 배열을 map 함수로 렌더링할 때 key 속성을 아예 지정하지 않는 경우입니다. JSX에서 반복되는 요소를 생성할 때 key를 빼먹으면 즉시 이 경고가 발생합니다.

2. 인덱스를 key로 사용

배열의 인덱스를 key로 사용하는 것은 일견 해결책처럼 보이지만, 리스트 항목의 순서가 변경되거나 항목이 추가/삭제될 때 문제를 일으킵니다. 인덱스는 데이터의 고유 식별자가 아니라 단순히 배열 내 위치를 나타내기 때문입니다.

3. 중복된 key 값 사용

여러 항목이 동일한 key 값을 가지고 있으면 React는 이들을 구별할 수 없습니다. 데이터베이스에서 가져온 ID 같은 고유 값을 사용해야 하는데, 중복 가능한 값을 key로 사용하면 이 문제가 발생합니다.

4. Fragment에 key 누락

React.Fragment를 사용하여 여러 요소를 그룹화할 때도 리스트 내에서 렌더링된다면 key가 필요합니다. 단축 문법인 <>는 key를 받을 수 없으므로 명시적으로 <React.Fragment>를 사용해야 합니다.

5. 조건부 렌더링에서 일관성 없는 key

조건에 따라 다른 컴포넌트를 렌더링할 때, 각 경우에 key를 일관성 있게 지정하지 않으면 React가 요소를 추적하는 데 혼란을 겪습니다. 특히 삼항 연산자나 논리 연산자를 사용한 조건부 렌더링에서 자주 발생합니다.

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

방법 1: 고유 ID를 key로 사용

데이터에 고유 ID가 있다면 이것을 key로 사용하는 것이 가장 이상적입니다.

const users = [
  { id: 1, name: 'Kim' },
  { id: 2, name: 'Lee' },
  { id: 3, name: 'Park' }
];

function UserList() {
  return (
    

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

방법 2: 복합 key 생성

단일 속성으로 고유성을 보장할 수 없다면, 여러 속성을 조합하여 고유한 key를 만듭니다.

const items = [
  { category: 'fruit', name: 'apple' },
  { category: 'fruit', name: 'banana' },
  { category: 'vegetable', name: 'carrot' }
];

function ItemList() {
  return (
    

      {items.map(item => (
        

          {item.category}: {item.name}
        
      ))}
    
  );
}

방법 3: UUID 라이브러리 사용

데이터에 고유 식별자가 없는 경우, uuid 같은 라이브러리로 고유 ID를 생성합니다.

import { v4 as uuidv4 } from 'uuid';

const items = ['apple', 'banana', 'cherry'].map(item => ({
  id: uuidv4(),
  name: item
}));

function FruitList() {
  return (
    

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

방법 4: Fragment에 key 추가

Fragment를 리스트에서 사용할 때는 명시적 문법으로 key를 지정합니다.

function ItemList({ items }) {
  return (
    

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

방법 5: 정적 리스트에만 인덱스 사용

리스트가 절대 변경되지 않는 정적 데이터라면, 최후의 수단으로 인덱스를 사용할 수 있습니다.

const staticItems = ['Home', 'About', 'Contact'];

function Navigation() {
  return (
    
  );
}

방법 6: 컴포넌트로 분리하여 key 관리

리스트 항목을 별도 컴포넌트로 분리하면 key 관리가 명확해집니다.

function TodoItem({ todo }) {
  return (
    

      
{todo.title}
      
{todo.content}
    
  );
}

function TodoList({ todos }) {
  return (
    

      {todos.map(todo => (
        
      ))}
    
  );
}

방법 7: 중첩 리스트의 key 관리

리스트 안에 리스트가 있는 경우, 각 레벨에서 고유한 key를 지정해야 합니다.

function NestedList({ categories }) {
  return (
    

      {categories.map(category => (
        

          
{category.name}
          

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

예방법과 베스트 프랙티스

“Warning: Each child in a list should have a unique “key” prop” 문제를 예방하려면 몇 가지 베스트 프랙티스를 따라야 합니다. 첫째, 데이터 모델 설계 단계부터 각 항목에 고유 식별자를 포함시키세요. 백엔드 API에서 데이터를 가져올 때 ID 필드가 포함되도록 요청하는 것이 좋습니다. 둘째, ESLint의 react/jsx-key 규칙을 활성화하여 key 누락을 자동으로 감지하세요. 셋째, 코드 리뷰 시 리스트 렌더링 부분을 특별히 체크하는 체크리스트를 만드세요. 넷째, 인덱스를 key로 사용하지 말라는 팀 컨벤션을 확립하고, 정말 필요한 경우에만 예외를 허용하세요. 다섯째, 테스트 코드를 작성할 때 리스트 항목의 추가, 삭제, 재정렬 시나리오를 포함시켜 key 관련 버그를 사전에 발견하세요.

마무리

React에서 “Warning: Each child in a list should have a unique “key” prop” 경고는 흔하지만 결코 무시해서는 안 되는 중요한 메시지입니다. 이 글에서 살펴본 것처럼, key의 역할을 정확히 이해하고 적절한 해결 방법을 적용하면 애플리케이션의 성능과 안정성을 크게 향상시킬 수 있습니다. 고유한 ID를 key로 사용하고, 인덱스 사용을 피하며, 팀 내 컨벤션을 확립하는 것만으로도 대부분의 문제를 예방할 수 있습니다. 지금 바로 프로젝트의 리스트 렌더링 코드를 점검하고, 이 가이드를 참고하여 개선해보세요.