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”라는 경고 메시지를 마주치게 될 때가 있습니다. 이 에러는 주로 리스트를 렌더링할 때 발생하며, 경험이 부족한 초보 개발자들에게는 혼란스러울 수 있습니다. 예를 들어, 당신이 여러 개의 사용자 프로필을 렌더링하는 컴포넌트를 만들고 있다고 가정해봅시다. 각 프로필을 목록으로 나타내는 과정에서 이 경고 메시지를 보게 된다면, 처음에는 당황스러울 수 있습니다.

또 다른 시나리오는, 동적으로 생성된 목록을 렌더링할 때 발생할 수 있습니다. 예를 들어, 서버에서 가져온 데이터로 구성된 상품 목록을 화면에 출력하고자 할 때, 각 상품 항목에 고유한 키를 부여하지 않으면 이 에러가 발생할 수 있습니다. 혹은, 상태 업데이트로 인해 목록이 갱신되면서 발생하기도 합니다. 이러한 경우, 이 글을 통해 왜 이러한 에러가 발생하는지, 그리고 어떻게 해결할 수 있는지를 배우게 될 것입니다.

이 글을 통해 얻을 수 있는 구체적인 해결책들은 간단한 코드 수정부터, 더 나아가 리스트 렌더링의 최적화까지 포함됩니다. 예상 해결 시간은 약 5분에서 30분 정도이며, 난이도는 초급에서 중급 수준입니다.

🔍 에러 메시지 상세 분석

“Warning: Each child in a list should have a unique “key” prop”는 React에서 자주 발생하는 경고입니다. 이 메시지는 각 리스트 항목에 고유한 키 속성을 부여하지 않았을 때 발생합니다. 예를 들어, 다음과 같은 코드가 있을 수 있습니다:

const items = ['Apple', 'Banana', 'Cherry'];

function FruitList() {
  return (
    

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

이 코드에서 각 <li> 요소에 고유한 키가 없습니다. React는 DOM 요소의 변경 사항을 효율적으로 감지하기 위해 각 자식 요소에 고유한 키 속성이 필요합니다. 이 경고는 특히 목록의 항목이 자주 변경되는 경우에 유용합니다.

에러가 발생하는 다양한 상황은 다음과 같습니다:

• 동일한 데이터 구조를 가진 리스트를 여러 번 렌더링할 때
• 컴포넌트가 상태 변화를 통해 목록을 갱신할 때
• 동적으로 생성된 요소가 있을 때
• 서버에서 데이터를 받아와 렌더링할 때
• 중첩된 리스트를 렌더링할 때

초보자를 위한 팁으로, 에러 메시지를 읽을 때는 “key”가 필요한 위치를 주의 깊게 살펴보세요. 이 에러는 “key” 속성을 통해 React가 각 리스트 항목을 고유하게 식별할 수 있도록 도와주기 위해 존재합니다. 이와 혼동하기 쉬운 비슷한 에러로는 “unique key prop”과 관련된 경고 메시지들이 있습니다.

🧐 발생 원인 분석

이 경고 메시지가 발생하는 주요 원인은 다음과 같습니다:

1. 리스트 항목에 키가 없을 때: 가장 흔한 원인으로, <li key={index}>와 같은 형태로 고유한 키를 부여하지 않아서 발생합니다.
2. 키 속성이 중복될 때: 같은 키 값을 여러 요소에 부여하면 React는 이를 고유하게 식별할 수 없습니다.
3. 데이터가 변경될 때: 목록이 갱신되면서 기존의 키가 변경되어야 하는 경우가 있습니다.
4. 비동기 데이터 패치: 서버로부터 데이터를 받아오는 과정에서 키가 설정되지 않은 상태로 렌더링할 때 발생합니다.
5. 중첩된 리스트: 복잡한 구조의 중첩 리스트에서 각 레벨마다 고유한 키가 필요할 수 있습니다.

각 원인이 발생하는 시나리오를 좀 더 구체적으로 살펴보겠습니다. 예를 들어, 키가 없을 때는 다음과 같은 코드로 인해 발생할 수 있습니다:

const data = ['Dog', 'Cat', 'Bird'];

function AnimalList() {
  return (
    

      {data.map((animal) => (
        
{animal}
      ))}
    
  );
}

이 경우, 각 <li> 요소에 고유한 키 속성이 없습니다. 키 속성이 중복될 때의 예는 다음과 같습니다:

const data = ['Dog', 'Cat', 'Bird'];

function AnimalList() {
  return (
    

      {data.map((animal, index) => (
        
{animal}
      ))}
    
  );
}

여기서는 인덱스를 키로 사용하고 있지만, 데이터가 변할 경우 키가 중복될 가능성이 있습니다. 비동기 데이터 패치의 경우, 데이터를 받아오고 나서 렌더링하는 순간에 키를 부여하지 않으면 문제가 됩니다.

개발 환경별 차이점도 존재합니다. 예를 들어, 개발 모드에서는 경고가 표시되지만, 프로덕션 모드에서는 무시될 수 있습니다. 각 원인을 확인하는 방법은 콘솔에서 경고 메시지를 주의 깊게 살펴보는 것입니다.

✅ 해결 방법

이제 문제를 해결할 방법을 살펴보겠습니다.

즉시 해결: 1분 내 적용 가능한 빠른 방법

1. 인덱스를 사용하여 키 부여하기: key={index}를 사용하여 각 항목에 고유한 키를 부여합니다.
2. 간단한 데이터 변환: 각 항목의 고유한 속성을 사용해 키를 설정합니다.
3. 고유 ID 사용: 데이터 자체에 고유한 ID가 있는 경우 이를 사용합니다.

예를 들어, 다음과 같이 고쳐볼 수 있습니다:

const items = ['Apple', 'Banana', 'Cherry'];

function FruitList() {
  return (
    

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

여기서 index를 사용하여 각 항목에 고유한 키를 부여했습니다.

표준 해결: 일반적이고 안전한 해결법

1. 데이터의 고유 속성 사용: 데이터에 고유한 식별자가 있는 경우 이를 키로 사용합니다.
2. React의 uuid 라이브러리 사용: 고유한 ID를 생성할 수 있습니다.
3. 고유한 키 생성 함수 작성: 데이터의 특정 부분을 이용해 고유한 키를 생성합니다.

코드 예제는 다음과 같습니다:

import { v4 as uuidv4 } from 'uuid';

const items = [
  { id: 1, name: 'Apple' },
  { id: 2, name: 'Banana' },
  { id: 3, name: 'Cherry' }
];

function FruitList() {
  return (
    

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

여기서는 item.id를 키로 사용하여 문제를 해결했습니다.

고급 해결: 복잡한 상황을 위한 해결법

1. 중첩 리스트의 키 설정: 각 레벨에서 고유한 키를 부여합니다.
2. 데이터베이스의 고유 ID 사용: 서버 데이터의 고유 식별자를 사용하는 방법입니다.
3. 데이터의 변동성에 대비한 키 로직 작성: 데이터가 자주 변하는 경우 이를 반영할 수 있도록 키 로직을 설계합니다.

예를 들어, 중첩 리스트의 경우:

const categories = [
  {
    categoryName: 'Fruits',
    items: ['Apple', 'Banana', 'Cherry']
  },
  {
    categoryName: 'Vegetables',
    items: ['Carrot', 'Lettuce', 'Spinach']
  }
];

function CategoryList() {
  return (
    

      {categories.map((category) => (
        

          
{category.categoryName}
          

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

이 코드는 각 카테고리와 그 안의 항목에 적절한 키를 부여하여 중첩된 리스트의 문제를 해결합니다.

🛡️ 예방법 및 베스트 프랙티스

이 에러가 재발하지 않도록 하기 위한 방법은 다음과 같습니다:

• 리스트 항목에 항상 고유한 키를 부여하는 습관을 들이세요.
• 데이터에 고유 식별자가 없을 경우, uuid와 같은 라이브러리를 사용하세요.
• 코드를 검토할 때 키 설정 여부를 확인하는 체크리스트를 만드세요.
• 팀 개발 시, 코드 리뷰에서 키 설정을 확인하는 가이드라인을 마련하세요.

또한, ESLint의 react/jsx-key 규칙을 활성화하여 키 누락을 방지할 수 있습니다.

🎯 마무리 및 추가 팁

이제 이 에러를 해결하기 위한 방법을 충분히 이해하셨을 것입니다. 핵심 내용 세 가지를 요약하면 다음과 같습니다:

• 항상 리스트 항목에 고유한 키를 부여해야 함
• 고유한 식별자를 사용하여 에러를 방지할 수 있음
• 팀 개발 시 키 설정에 대한 가이드라인 마련

비슷한 에러로는 “Warning: Failed prop type” 등이 있으며, 이에 대한 해결법도 학습해보세요. 추가 학습 리소스로는 React 공식 문서나 온라인 튜토리얼을 추천합니다. 독자 여러분, 이 에러가 더 이상 두렵지 않기를 바랍니다. 함께 해결해나가는 과정에서 성장할 수 있습니다!