🛠️ 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에서 리스트를 렌더링할 때 가장 흔하게 발생하는 문제 중 하나로, 초보 개발자뿐만 아니라 숙련된 개발자도 종종 마주치는 상황입니다. 이 경고를 무시하면 애플리케이션의 성능 저하, 예상치 못한 UI 버그, 컴포넌트 상태 관리 오류 등 다양한 문제가 발생할 수 있습니다. 본 가이드에서는 이 경고가 왜 발생하는지, 어떻게 해결할 수 있는지, 그리고 앞으로 이러한 문제를 예방하는 방법까지 상세하게 다루어 보겠습니다.

에러 상세 분석

“Warning: Each child in a list should have a unique “key” prop” 경고는 React가 가상 DOM(Virtual DOM)을 효율적으로 관리하기 위해 발생시키는 메시지입니다. React는 리스트의 각 항목을 추적하고 변경 사항을 감지하기 위해 고유한 key prop을 필요로 합니다. key는 React가 어떤 항목이 변경, 추가, 삭제되었는지 식별하는 데 사용되는 특별한 속성입니다.

이 경고가 발생하는 주요 이유는 React의 재조정(Reconciliation) 알고리즘과 관련이 있습니다. key가 없으면 React는 리스트의 각 요소를 인덱스로만 판단하게 되어, 항목의 순서가 변경되거나 중간에 항목이 추가/삭제될 때 잘못된 컴포넌트를 업데이트하거나 불필요한 재렌더링을 발생시킬 수 있습니다. 이는 성능 문제뿐만 아니라 폼 입력값이 잘못된 항목에 유지되는 등의 심각한 버그를 야기할 수 있습니다. 따라서 이 경고를 단순한 경고로 치부하지 말고, 반드시 해결해야 하는 중요한 문제로 인식해야 합니다.

발생 원인 5가지

1. key prop을 전혀 제공하지 않은 경우

가장 기본적인 원인으로, 배열을 map() 함수로 렌더링할 때 각 요소에 key를 지정하지 않은 경우입니다. 이는 초보 개발자가 가장 자주 범하는 실수이며, React 문서를 읽지 않고 코딩을 시작했을 때 흔히 발생합니다.

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

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

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

배열의 인덱스를 key로 사용하는 것은 항목의 순서가 절대 변경되지 않는 정적인 리스트에서만 허용됩니다. 동적인 리스트에서 인덱스를 key로 사용하면 항목이 재정렬되거나 추가/삭제될 때 문제가 발생합니다.

// 권장하지 않는 예시
{items.map((item, index) => 
{item}
)}

3. 중복된 key 값을 사용한 경우

여러 항목이 동일한 key 값을 가지고 있으면 React는 어떤 항목이 어떤 것인지 구분할 수 없습니다. 이는 데이터베이스에서 중복된 ID를 사용하거나, 잘못된 속성을 key로 선택했을 때 발생합니다.

4. Fragment에 key를 누락한 경우

React Fragment(<> )를 사용할 때도 리스트 내에서 렌더링되는 경우 key가 필요합니다. 단축 문법(<> )은 key를 지원하지 않으므로 명시적으로 를 사용해야 합니다.

5. 중첩된 리스트에서 key를 잘못 적용한 경우

중첩된 리스트 구조에서 부모 리스트에만 key를 적용하고 자식 리스트에는 적용하지 않거나, 반대로 잘못 적용한 경우에도 이 경고가 발생합니다.

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

해결법 1: 고유한 ID를 key로 사용

가장 이상적인 방법은 데이터베이스에서 제공하는 고유한 ID를 key로 사용하는 것입니다.

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

return (
  

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

해결법 2: 고유한 속성 조합으로 key 생성

ID가 없는 경우, 여러 속성을 조합하여 고유한 key를 만들 수 있습니다.

const products = [
  { category: '과일', name: '사과' },
  { category: '채소', name: '당근' }
];

return (
  

    {products.map(product => (
      

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

해결법 3: uuid 라이브러리 사용

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

import { v4 as uuidv4 } from 'uuid';

const items = ['사과', '바나나', '오렌지'].map(item => ({
  id: uuidv4(),
  name: item
}));

return (
  

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

해결법 4: Fragment에 key 적용

Fragment를 리스트 내에서 사용할 때는 명시적 문법으로 key를 추가해야 합니다.

import React from 'react';

const data = [
  { id: 1, title: '제목1', desc: '설명1' },
  { id: 2, title: '제목2', desc: '설명2' }
];

return (
  

    {data.map(item => (
      
        
{item.title}
        
{item.desc}
      
    ))}
  
);

해결법 5: 정적 리스트에서만 인덱스 사용

순서가 절대 변경되지 않는 정적 리스트에서는 인덱스를 key로 사용할 수 있습니다.

// 정적이고 변경되지 않는 리스트에서만 허용
const staticMenu = ['홈', '소개', '연락처'];

return (
  
);

해결법 6: 중첩 리스트 처리

중첩된 리스트에서는 각 레벨마다 고유한 key를 제공해야 합니다.

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

return (
  

    {categories.map(category => (
      

        
{category.name}
        

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

해결법 7: useMemo로 안정적인 key 보장

컴포넌트가 재렌더링될 때마다 새로운 key가 생성되는 것을 방지하기 위해 useMemo를 활용할 수 있습니다.

import { useMemo } from 'react';
import { v4 as uuidv4 } from 'uuid';

function MyComponent({ rawData }) {
  const dataWithIds = useMemo(
    () => rawData.map(item => ({ ...item, id: uuidv4() })),
    [rawData]
  );

  return (
    

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

예방법과 베스트 프랙티스

“Warning: Each child in a list should have a unique “key” prop” 문제를 예방하기 위해서는 몇 가지 베스트 프랙티스를 따라야 합니다. 첫째, 데이터 모델 설계 단계에서부터 모든 엔티티에 고유 ID를 포함시키는 것이 중요합니다. 데이터베이스에서 가져온 데이터는 일반적으로 기본 키(Primary Key)를 가지고 있으므로 이를 활용하세요. 둘째, 배열 인덱스를 key로 사용하는 것은 최후의 수단으로만 고려해야 하며, 동적인 리스트에서는 절대 사용하지 마세요. 셋째, ESLint 플러그인인 eslint-plugin-react를 설치하여 key 누락을 자동으로 감지하도록 설정하세요. 이 플러그인은 코드 작성 중에 실시간으로 경고를 표시하여 문제를 조기에 발견할 수 있게 해줍니다. 넷째, 코드 리뷰 시 리스트 렌더링 부분을 특별히 주의 깊게 검토하고, 새로운 팀원에게는 key의 중요성을 교육하세요. 마지막으로, TypeScript를 사용하는 경우 타입 정의에 id 필드를 필수로 지정하여 컴파일 타임에 문제를 방지할 수 있습니다.

마무리

React에서 “Warning: Each child in a list should have a unique “key” prop” 경고는 단순한 경고 메시지가 아니라 애플리케이션의 성능과 안정성에 직접적인 영향을 미치는 중요한 이슈입니다. 이 가이드에서 다룬 원인 분석과 7가지 해결 방법을 통해 여러분은 이제 이 문제를 완벽하게 해결할 수 있을 것입니다. 고유한 ID를 사용하고, 인덱스를 key로 사용하는 것을 피하며, ESLint와 같은 도구를 활용하여 코드 품질을 유지하세요. 올바른 key 사용은 React 애플리케이션의 성능 최적화와 버그 예방의 핵심입니다. 이제 자신 있게 React 리스트를 렌더링하고, 깨끗한 콘솔과 함께 안정적인 애플리케이션을 구축하세요.