[Next.js] 넥스트 빌드파일 html id="__next_error__" 해결방법 (useSearchParams)

 

Next.js 14버전으로 개발한 웹사이트를 구글 서치 콘솔에 등록하려고 했지만,

robots 메타태그에서 noindex에 의해 제외되었다는 메시지가 표시되었습니다. 🤔

 

문제를 확인해 보니, 웹사이트는 정상적으로 동작하는 것처럼 보였지만
next build를 통해 생성된 빌드 파일이 Next.js 에러 페이지를 출력하고 있었습니다.

 

html id="__next_error__"

해결과정 함께 알아봅시다 😀

 

---

📝 문제 상황

html id="__next_error__"

 

페이지 소스 보기

 

⦁__next_error__

Next.js의 에러 페이지는 기본적으로 <meta name="robots" content="noindex"> 메타태그를 포함합니다.

따라서 noindex 메타태그가 자동으로 삽입되었기 때문에 구글의 검색엔진이 색인 작업을 하지 않았습니다.

 

해당 현상은 next dev를 통해 개발환경에서 실행했을 경우에는 재현되지 않습니다.

따라서 빌드 과정에서 에러가 발생했던 건데요,

슬프게도 빌드는 성공적으로 완료되고 next_error가 발생한 지점을 로그를 통해 따로 알려주지 않습니다.

 

모든 코드를 다 뒤져야 하나 머리가 아파지던 참에 구글링을 통해

비슷한 현상을 겪은 개발자들의 이슈를 몇 개 찾을 수 있었습니다. 😎

 

---

📝 문제 원인

https://nextjs-ko.org/docs/app/api-reference/functions/use-search-params

useSearchParams – Nextjs 한글 문서

 

✅ 여러 이슈에서 공통적으로 언급된 것은 Next.js의 useSearchParams를 사용하는 경우였습니다.

 

⦁ useSerachParams

 

useSearchParams는 Next.js에서 URL의 쿼리 스트링을 가져오는 데 사용하는 클라이언트 컴포넌트 훅입니다.

이 훅을 호출하면 가장 가까운 Suspense 경계까지 클라이언트 측에서 렌더링이 이루어지기 때문에, Suspense로 해당 컴포넌트를 감싸는 것이 권장됩니다.

 

❗️만약 useSearchParams 훅을 호출하는 컴포넌트에 Suspense 경계가 없다면 애플리케이션 루트까지 버블링되어 클라이언트 렌더링에 옵트인 하게 된다고 합니다. 

 

⦁ 문제 분석

Suspense 경계 없이 클라이언트 컴포넌트를 서버 컴포넌트 트리 내에서 사용할 경우,

렌더링이 중단되고 Next.js의 기본 에러 페이지인 __next_error__가 반환됩니다.

 

저희 코드 역시 해당 훅을 사용하지만, Suspense를 사용하지 않은 경우였습니다.

다행히 Suspense를 감싸주는 것만으로 해결할 수 있었습니다. 🥳

 

⦁ 예시 코드

// bad - Suspense 경계가 존재하지 않음
import { useSearchParams } from 'next/navigation';

export default function Page() {
  const searchParams = useSearchParams();
  const query = searchParams.get('query');

  return <div>검색어: {query}</div>;
}

// good - Suspense 추가 !
import { Suspense } from 'react';
import { useSearchParams } from 'next/navigation';

function SearchParamsComponent() {
  const searchParams = useSearchParams();
  const query = searchParams.get('query');

  return <div>검색어: {query}</div>;
}

export default function Page() {
  return (
    <div>
      <h1>검색 결과</h1>
      <Suspense fallback={<div>로딩 중...</div>}>
        <SearchParamsComponent />
      </Suspense>
    </div>
  );
}

 

---

---

📝 결과

 

Suspense로 감싸준 결과

더 이상 빌드 파일에서 에러 페이지를 출력하지 않는 걸 확인했습니다. 😎

 

---

참고 문헌 : 

https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout

https://nextjs-ko.org/docs/app/api-reference/functions/use-search-params

https://zenn.dev/yutakobayashi/articles/head-google-analytics

https://github.com/vercel/next.js/issues/44868