이 글에서 정리하는 내용
App Router에서 useSearchParams를 쓴 클라이언트 컴포넌트 때문에 production build가 실패하는 상황을 기준으로 원인을 좁히고, 실제 프로젝트에서 어떤 설정과 코드 구조를 확인해야 하는지 정리합니다. 단순 개념 소개가 아니라 오류가 난 순간 바로 확인할 순서와 선택 기준을 중심으로 설명합니다.
이 글은 Next.js SEO 완전 가이드: App Router metadata부터 배포 확인까지의 세부 항목입니다. 전체 설정 흐름과 관련 오류 해결 순서는 대표 허브 글에서 함께 확인할 수 있습니다.
- useSearchParams 오류가 빌드에서 터지는 이유
- App Router에서 클라이언트 훅을 쓰는 위치
- Suspense로 감싸야 하는 컴포넌트 기준
- 검색·필터 UI에서 안전한 구조
- Vercel 배포 전 체크리스트
useSearchParams 오류가 빌드에서 터지는 이유
App Router에서 useSearchParams를 쓴 클라이언트 컴포넌트 때문에 production build가 실패하는 상황에서는 처음에 보이는 증상만 보고 바로 해결책을 고르기 쉽습니다. 하지만 이 단계에서 중요한 것은 문제를 하나의 원인으로 단정하지 않고, 화면 상태와 설정 파일, 실행 환경을 나누어 보는 것입니다. 같은 오류 메시지라도 로컬 개발 서버, production build, 배포 환경에서 원인이 달라질 수 있습니다.
먼저 확인할 것은 “정말 코드가 실행되는 위치에서 그 값이나 요소를 볼 수 있는가”입니다. 프론트엔드 오류는 코드가 틀려서만 생기지 않습니다. 렌더링 타이밍, 빌드 도구의 규칙, 파일 위치, 서버와 클라이언트 경계가 어긋나도 같은 증상처럼 보입니다. 관련 흐름을 같이 잡으려면 프론트엔드 배포 로드맵도 함께 보면 좋습니다.
App Router에서 클라이언트 훅을 쓰는 위치
이 문제를 좁힐 때는 문법보다 기준을 먼저 잡아야 합니다. 어떤 값은 클라이언트에서 읽을 수 있고, 어떤 값은 서버에서만 안전합니다. 어떤 컴포넌트는 즉시 렌더링되지만, 어떤 컴포넌트는 데이터 준비나 사용자 상호작용 뒤에야 의미가 생깁니다. 이 구분이 흐려지면 코드는 맞아 보여도 결과가 예상과 다르게 나옵니다.
설정 파일을 다루는 글이라면 파일 이름, 경로, prefix, alias를 확인해야 합니다. 컴포넌트 구조를 다루는 글이라면 서버 컴포넌트와 클라이언트 컴포넌트, 접근성 이름, Suspense 경계처럼 실행 위치를 확인해야 합니다. 결국 해결 순서는 “보이는 증상 → 실행 위치 → 설정 기준 → 코드 수정 → 재검증”으로 잡는 것이 안전합니다.
function Page() {
return (
<Suspense fallback={<div>검색 조건을 불러오는 중</div>}>
<FilterBar />
</Suspense>
);
}위 예시는 완성 코드라기보다 확인해야 할 기준을 보여주는 형태입니다. 실제 프로젝트에서는 변수명이나 컴포넌트 이름이 달라도, 값이 어디서 만들어지고 어디서 소비되는지 추적하면 원인을 더 빨리 찾을 수 있습니다.
또 하나 봐야 할 것은 팀이나 프로젝트가 이미 정해 둔 규칙입니다. 같은 도구를 쓰더라도 폴더 구조, 환경변수 이름, 테스트 작성 방식, 컴포넌트 import 기준은 프로젝트마다 다릅니다. 오류 해결 글을 따라 할 때도 현재 프로젝트의 기준과 충돌하지 않는지 확인해야 합니다. 이 과정을 거치면 단순히 오류 하나를 없애는 데서 끝나지 않고, 다음 작업에서도 재사용할 수 있는 판단 기준이 남습니다.
Suspense로 감싸야 하는 컴포넌트 기준
실무에서 자주 놓치는 부분은 “기다려야 하는 것”과 “설정해야 하는 것”을 구분하지 못하는 지점입니다. 데이터가 늦게 들어오는 문제라면 기다리는 기준이 필요하고, 빌드 규칙이 맞지 않는 문제라면 설정을 바꿔야 합니다. 기다림으로 설정 문제를 해결할 수 없고, 설정 변경만으로 렌더링 타이밍 문제가 사라지지도 않습니다.
그래서 오류를 고칠 때는 먼저 재현 조건을 고정합니다. 로컬에서만 나는지, 빌드에서만 나는지, 배포 후에만 나는지 확인합니다. 그다음 변경 범위를 작게 유지합니다. 한 번에 여러 설정과 코드를 바꾸면 어떤 수정이 효과가 있었는지 알기 어렵습니다. 비교할 기준이 필요할 때는 Next.js fetch 캐시 문제 해결처럼 인접한 오류 해결 글과 함께 흐름을 잡아도 좋습니다.
검색·필터 UI에서 안전한 구조
이 섹션에서는 실제 수정 기준을 적용합니다. 오류가 사용자 입력, 목록 렌더링, 배포 환경, 컴포넌트 라이브러리 설정처럼 특정 화면과 연결되어 있다면 그 화면에서 가장 작은 실패 사례를 만들어 확인합니다. 예를 들어 버튼 하나, 폼 필드 하나, 환경변수 하나, 컴포넌트 하나로 줄이면 원인이 훨씬 선명해집니다.
수정 후에는 성공 화면만 보지 말고 실패 조건도 다시 확인해야 합니다. 값이 없을 때, 네트워크가 늦을 때, 배포 환경에서 값이 다를 때, 접근성 이름이 바뀔 때처럼 실제로 다시 깨질 수 있는 조건을 체크합니다. 이 과정이 있어야 같은 오류가 다음 작업에서 반복되지 않습니다.
Vercel 배포 전 체크리스트
마지막으로 체크리스트를 남겨두면 다음에 같은 증상을 만났을 때 훨씬 빠르게 움직일 수 있습니다. 첫째, 오류 메시지를 그대로 검색하기 전에 실행 환경을 확인합니다. 둘째, 설정 파일과 코드가 같은 기준을 바라보는지 봅니다. 셋째, 수정 후에는 로컬 실행, production build, 필요한 경우 배포 환경까지 나누어 검증합니다.
체크리스트를 만들 때는 “무엇을 바꿨는가”보다 “무엇을 확인했는가”를 먼저 적는 편이 좋습니다. 예를 들어 파일 위치를 확인했는지, 빌드 명령으로 재현했는지, 배포 환경에서도 같은 값이 들어가는지, 변경 후 다시 실패 조건을 실행했는지처럼 검증 행동을 남깁니다. 이런 기록이 있으면 다음에 비슷한 문제가 생겼을 때 해결 과정이 훨씬 짧아집니다.
가능하면 수정 전후를 한 줄로 기록해 두세요. 예를 들어 “환경변수 prefix 수정 후 dev server 재시작”, “클라이언트 훅을 별도 컴포넌트로 분리하고 Suspense로 감쌈”, “alias 기준을 components.json과 tsconfig에서 동일하게 맞춤”처럼 남기면 됩니다. 이런 기록은 글을 읽는 독자에게도 그대로 적용 가능한 문제 해결 패턴이 됩니다.
반대로 피해야 할 방식은 오류가 사라질 때까지 설정을 무작위로 바꾸는 것입니다. 당장은 통과하더라도 왜 해결됐는지 모르면 다음 배포나 협업 환경에서 같은 문제가 다시 생깁니다. 작은 단위로 가설을 세우고 하나씩 확인하는 방식이 느려 보여도, 결과적으로는 가장 빠른 해결에 가깝습니다.
마지막으로, 해결이 끝났다고 판단하기 전에는 같은 증상을 일부러 한 번 더 재현해 보는 것이 좋습니다. 실패 조건을 다시 만들 수 있고, 수정 후 그 조건이 사라졌다면 해결 근거가 생깁니다. 이 확인 없이 화면이 한 번 정상으로 보였다는 이유만으로 끝내면, 실제 배포나 다른 브라우저에서 문제가 다시 나타날 수 있습니다.
이 글의 핵심은 특정 옵션 하나를 외우는 것이 아닙니다. 오류가 났을 때 어디서부터 확인해야 하는지 순서를 갖는 것입니다. 그 순서가 있으면 비슷한 문제가 다시 나와도 무작정 코드를 바꾸지 않고, 원인을 작게 나누어 안정적으로 해결할 수 있습니다.