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’라는 경고 메시지를 한 번쯤은 마주하게 됩니다. 이 경고는 특히 리스트를 렌더링할 때 자주 나타나며, 처음에는 간단한 문제로 보일 수 있지만, 무시하고 넘어가면 성능 문제를 야기할 수 있습니다. 개발자들이 이 에러를 처음 만났을 때 직면하는 좌절감은 이루 말할 수 없습니다. 컴포넌트를 반복해서 렌더링할 때, 데이터가 동적으로 변할 때, 혹은 조건부 렌더링을 할 때 등 다양한 시나리오에서 이 경고가 발생할 수 있습니다.

이 글에서는 이 경고의 원인을 상세히 분석하고, 실질적인 해결책을 제공합니다. 예상 해결 시간은 약 10분에서 30분 정도이며, 난이도는 초보자도 충분히 이해할 수 있는 수준입니다. 여러분이 이 글을 통해 얻을 수 있는 것은 명확한 경고 해결 방법, 다양한 발생 상황에 대한 이해, 그리고 예방책입니다. 함께 이 문제를 해결해봅시다!

🔍 에러 메시지 상세 분석

이 경고 메시지는 “Warning: Each child in a list should have a unique “key” prop”라는 형태로 나타납니다. 이와 유사한 변형으로는 “Warning: A component is changing an uncontrolled input to be controlled”이나 “Warning: Failed prop type: Invalid prop `key` of type `number` supplied” 등이 있습니다. 그러나 이 글에서는 첫 번째 경고에 집중하겠습니다.

이 경고는 주로 다음과 같은 상황에서 발생합니다:

• 리스트 컴포넌트를 반복적으로 렌더링할 때
• map 함수를 사용해 JSX 요소를 생성할 때
• 동적인 데이터로 컴포넌트를 렌더링할 때
• 조건부 렌더링에서 key 속성을 부여하지 않았을 때
• key 값이 중복되거나 고유하지 않을 때

경고 메시지의 각 부분을 해석해보면, “Each child”는 리스트 내의 각 항목을 의미하고, “should have a unique “key” prop”는 각 항목이 고유한 key 속성을 가져야 함을 말합니다. 초보자라면 이 경고를 처음 봤을 때 “key”라는 단어에 주목해야 합니다. React는 DOM 노드의 효율적인 업데이트를 위해 각 자식 요소에 고유한 key 값을 필요로 합니다. 비슷한 에러로는 key 대신 index를 사용하는 경우 발생하는 성능 관련 문제들이 있습니다.

🧐 발생 원인 분석

이 경고의 주된 원인들은 다음과 같습니다:

1. Key 속성 누락: map 함수를 사용할 때 key 속성을 잊기 쉽습니다. 예를 들어, 배열을 map으로 렌더링하면서 key를 지정하지 않으면 이 경고가 뜹니다.
2. 중복된 Key 값: key 값이 중복되면 React는 어떤 항목이 변경되었는지 알지 못합니다. 예를 들어, 데이터베이스에서 id가 없는 경우 인덱스나 다른 중복 가능한 값을 key로 사용할 수 있습니다.
3. 동적 데이터 변경: 데이터가 빈번하게 변경되면서 key 값이 변경되지 않으면 업데이트가 올바르게 이루어지지 않습니다.
4. 조건부 렌더링: 조건부로 렌더링되는 요소에 key를 할당하지 않으면 경고가 발생합니다.
5. 서버에서 가져온 데이터의 고유성 부족: 서버에서 가져온 데이터가 고유한 id를 제공하지 않으면 key 할당에 문제가 발생할 수 있습니다.

이러한 원인들은 보통 개발자가 데이터의 고유성을 고려하지 않았거나, key 속성의 중요성을 간과했을 때 발생합니다. 개발 환경에 따라 발생 빈도는 다를 수 있지만, 대부분의 React 버전에서 일관되게 발생하는 문제입니다. 각 원인은 다음과 같은 간단한 방법으로 확인할 수 있습니다:

• 콘솔 로그를 통해 key 값을 출력하여 중복 여부 확인
• 조건부 렌더링에서 key 속성 부여 여부 체크
• 서버로부터 받아온 데이터의 고유성 확인

✅ 해결 방법

이제 각 원인에 따른 해결 방법을 살펴보겠습니다.

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

1. 간단한 key 추가: map 함수를 사용하는 컴포넌트에 key 속성을 추가합니다.
2. 인덱스 사용: 임시로 인덱스를 key로 사용할 수 있지만, 이는 권장되지 않습니다.
3. 고유한 값 사용: 데이터에서 고유한 값을 찾아 key로 사용합니다.

// 각 child에 key prop을 추가하지 않은 경우
const items = ["apple", "banana", "cherry"];
const itemList = items.map(item => 
{item}
);

// 수정된 코드: 고유한 key를 추가합니다
const itemListWithKeys = items.map((item, index) => 
{item}
);

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

1. 고유한 식별자 사용: 데이터베이스에서 고유한 id를 가져와 key로 사용합니다.
2. UUID 활용: 고유한 식별자가 없는 경우 UUID를 생성하여 사용합니다.
3. 고유성 검사: key가 중복되지 않도록 검사합니다.
4. 조건부 렌더링에서도 key 부여: 조건부 렌더링 시에도 key 속성을 부여합니다.
5. 데이터 변경 시 key 업데이트: 데이터 변경 시 고유한 key 값을 유지하도록 합니다.

// 서버에서 가져온 데이터에 고유한 id가 있을 때
const data = [
  { id: 1, name: "apple" },
  { id: 2, name: "banana" },
];

// 수정된 코드: id를 key로 사용
const itemListWithKeys = data.map(item => 
{item.name}
);

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

1. 커스텀 키 생성 로직: 복합 키 생성 로직을 통해 고유성을 보장합니다.
2. 상태 관리 라이브러리 사용: Redux나 MobX를 사용하여 key 값을 중앙에서 관리합니다.
3. 고유 식별자 생성 라이브러리 사용: shortid, nanoid 등을 사용하여 고유한 key를 생성합니다.

// 고유한 키 생성 로직을 사용하는 경우
import { nanoid } from 'nanoid';

const items = ["apple", "banana", "cherry"];

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

각 해결법의 장단점을 고려하여 상황에 맞게 적용하세요. 예를 들어, 임시로 인덱스를 사용하는 것은 간단하지만, 데이터 변경 시 성능 문제를 일으킬 수 있습니다. 고유한 식별자를 사용하는 것이 가장 안전하며, 데이터가 동적으로 변하는 경우에도 안정성을 보장합니다.

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

이 경고를 예방하기 위해서는 다음과 같은 방법들을 권장합니다:

• 코드 리뷰 체크리스트에 추가: key 속성이 올바르게 사용되었는지 코드 리뷰 단계에서 확인합니다.
• ESLint 플러그인 사용: React용 ESLint 플러그인을 사용하여 key 관련 경고를 사전에 감지합니다.
• 개발 문서화: 팀 내에서 key 사용에 대한 가이드라인을 문서화하여 공유합니다.
• 테스트 케이스 작성: key 속성 사용 여부를 확인하는 테스트 케이스를 작성합니다.

이러한 예방책을 통해 팀 전체가 일관된 코드를 유지하고, 불필요한 경고를 줄일 수 있습니다.

🎯 마무리 및 추가 팁

마지막으로, 이 글을 통해 얻은 핵심 내용을 요약하겠습니다:

1. key 속성은 리스트 렌더링에서 반드시 필요합니다.
2. 고유한 식별자를 사용하여 key를 부여하세요.
3. 코드 리뷰와 린터를 통해 사전 예방하세요.

비슷한 에러로는 ‘A component is changing an uncontrolled input to be controlled’와 같은 경고가 있습니다. 추가 학습을 위해 React 공식 문서와 다양한 블로그를 참고하세요. 여러분의 디버깅 여정에 행운을 빕니다!