[트러블 슈팅] Next.js generateStaticParams 정적 경로 생성의 오해와 해결 과정

 

라이엇 도감 만들기 프로젝트에서 발생한 트러블 슈팅입니다.

발생한 오류 🔥

Next.js에서 `/champions/[id]`와 같은 동적 경로 페이지를 빌드할 때, 정적 경로가 아닌 동적 경로로 처리되며 `dynamic`으로 표시되는 문제가 발생했습니다.

// app > champions > page.tsx

export const generateStaticParams = async () => {
  const { data: allChampions }: { data: ChampionsList } =
    await fetchAllChampions();

  return Object.keys(allChampions).map((champion) => ({
    id: champion,
  }));
};

 

`generateStaticParams`를 사용해 빌드 타임에 정적 페이지를 미리 생성하고자 했으나, 페이지가 여전히 동적으로 처리되는 상황이었습니다.

 

해결 과정 🔎

문제의 근본 원인은 `generateStaticParams`의 역할을 잘못 이해한 것에서 시작됐습니다.

 

`/champions`페이지에 `generateStaticParams`함수를 작성해 모든 챔피언 데이터를 기반으로 정적 페이지를 생성하려고 했습니다. 하지만 `/champions`페이지는 고정된 경로로, 동적 파라미터가 없기 때문에 함수가 동작하지 않았습니다.

 

이를 해결하기 위해 `generateStaticParams`가 동적 경로인 `/champions/[id]`파일 내에 작성되어야 한다는 점을 인지하게 되었습니다. 이 함수는 동적 경로에 필요한 파라미터 값들을 빌드 타임에 미리 생성하는 데 사용되기 때문에, 동적 경로에서만 유효합니다.

 

해결 방법 ✨

동적 경로 파일 내로 `generateStaticParams`함수 이동

// app > champions > [id] > page.tsx

export const generateStaticParams = async () => {
  const { data: allChampions }: { data: ChampionsList } =
    await fetchAllChampions();

  return Object.keys(allChampions).map((champion) => ({
    id: champion,
  }));
};

 

`/champions/[id]`파일 내로 이동시킴으로써 next.js가 `id`에 해당하는 정적 경로를 미리 생성할 수 있도록 했습니다. 

정적 페이지 생성

 

이후 제대로 동작되는 걸 확인할 수 있었습니다.

 

어려웠던 점 ❓

처음에는 `generateStaticParams`의 역할을 잘못 이해해, 동적 경로가 아닌 정적 경로 페이지에서 사용하려다 보니 원하는 결과를 얻지 못했습니다. 이 과정에서 동적 경로와 정적 경로의 차이점을 명확히 인식하지 못했던 것이 살짝 아쉬웠습니다.

 

깨달은 점 ❕

`generateStaticParams`가 동적 경로 파일 내에서만 작동한다는 점을 확실히 깨달았습니다.

 

느낀 점 🧐

이번 경험을 통해 정적 경로 생성과 동적 경로 처리에 대한 next.js의 동작 방식을 이해할 수 있었고, 경로에 맞는 렌더링 전략을 잘 수립하는 것이 빌드 최적화에 얼마나 중요한지를 배우게 되었습니다.