Next.js 페이지가 안 뜰 때 체크해야 할 핵심 항목 7가지
Next.js 페이지가 안 뜰 때 체크해야 할 핵심 항목 7가지
Next.js로 웹 프로젝트를 진행하다 보면, 잘 작동하던 페이지가 어느 날 갑자기 열리지 않는 상황을 겪는 경우가 있어요. 특히 배포 후에는 사소한 설정 실수 하나가 전체 페이지를 마비시킬 수 있기 때문에 빠르고 정확한 점검이 필요합니다.
📌 목차
- 1. 빌드 에러 확인
- 2. 페이지 라우팅 확인
- 3. next.config.js 설정 확인
- 4. 정적 파일 접근 오류
- 5. API 라우트 문제
- 6. 서버 시작 명령어 점검
- 7. 배포 환경 변수 누락
그럼 지금부터 각 항목에 대해 실제 사례를 바탕으로 차근차근 살펴보겠습니다.
1. 빌드 에러 확인
Next.js는 프로덕션 모드에서 next build를 통해 정적 페이지를 생성하는데요, 이 단계에서 오류가 발생하면 페이지가 정상적으로 생성되지 않습니다. 터미널에서 에러 메시지를 꼼꼼히 확인해 보세요. 종종 TypeScript 오류나 SSR에 적합하지 않은 코드 때문에 빌드가 실패하는 경우가 많습니다.
Error: getInitialProps is missing for page "/about"→ 서버사이드 렌더링이 필요한데, 적절한 함수가 빠져있을 경우 발생합니다.
2. 페이지 라우팅 확인
Next.js는 파일 기반 라우팅을 사용하기 때문에, pages 디렉토리 내의 구조가 매우 중요합니다. 파일 이름을 잘못 입력하거나 대소문자가 일치하지 않으면 라우팅이 되지 않아 404 페이지가 뜰 수 있어요.
예를 들어, pages/Blog.js로 작성했는데 실제 주소를 /blog로 접근하면 라우팅이 실패합니다. 특히 Windows와 달리 리눅스 환경은 대소문자를 구분하기 때문에 주의해야 합니다.
3. next.config.js 설정 확인
next.config.js 파일에는 다양한 설정이 담겨 있어요. basePath나 assetPrefix 같은 설정이 잘못되면 정적 리소스가 로딩되지 않아 화면이 흰색으로만 보일 수 있습니다.
또한, reactStrictMode나 experimental 플래그로 인해 특정 컴포넌트의 렌더링이 막히는 경우도 있기 때문에 해당 설정을 주석 처리해보는 것도 좋습니다.
module.exports = { basePath: '/my-app' } 설정 시, 실제 접근 경로는 https://도메인/my-app이 되어야 합니다.이어서 정적 파일, API 라우팅, 서버 명령어, 환경 변수 이슈까지 살펴보겠습니다.
4. 정적 파일 접근 오류
Next.js에서는 public 폴더에 넣은 파일만 정적 리소스로 접근할 수 있어요. 예를 들어, public/images/logo.png에 있는 이미지는 /images/logo.png로 접근해야 하며, pages나 src 디렉토리에 있는 리소스는 직접 접근할 수 없습니다.
만약 이미지나 CSS 파일이 로딩되지 않는다면, 파일 경로가 정확한지, 그리고 브라우저에서 해당 리소스를 열었을 때 404 오류가 나는지 꼭 확인해보세요.
5. API 라우트 문제
Next.js는 pages/api 디렉토리 하위에 API 라우트를 구성할 수 있습니다. 하지만 이 디렉토리 구조가 잘못되었거나, 내부에 잘못된 import가 있을 경우 전체 앱이 실패할 수 있어요.
import db from '../../lib/db';위 코드에서
lib/db.js 파일이 존재하지 않으면, 서버가 시작조차 되지 않습니다.또한, 클라이언트에서 API 호출 시 CORS 정책 오류가 발생하거나, HTTP 메서드를 잘못 사용하는 경우도 많습니다. API 라우트는 백엔드처럼 작동하므로 HTTP 상태 코드와 응답 포맷을 명확히 설정해야 합니다.
6. 서버 시작 명령어 점검
Next.js를 실행할 때는 개발용과 배포용 명령어가 달라요. 로컬에서는 next dev를 사용하지만, 실제 배포 시에는 next build 후 next start를 사용해야 합니다.
빌드 후에도 next dev로 실행하면 개발 모드로 동작하게 되어 실제 환경과 다른 버그가 발생할 수 있어요. 반드시 배포용 명령어를 명확히 구분해서 실행하세요.
7. 배포 환경 변수 누락
마지막으로 가장 흔하면서도 놓치기 쉬운 문제가 바로 환경 변수입니다. .env 파일은 로컬에서는 잘 작동하더라도, 배포 시 클라우드 환경에서는 이 값을 따로 설정해줘야 해요.
예를 들어, Vercel에서는 프로젝트 설정에서 환경 변수를 입력해야 하며, Netlify나 AWS에서도 각각의 방식에 맞게 지정해줘야 합니다. 환경 변수가 없으면 API 키나 DB 연결 정보가 누락되어 앱이 정상적으로 실행되지 않아요.
중요한 환경 변수에는
process.env.NEXT_PUBLIC_ 접두사를 붙여 클라이언트에서도 접근 가능하게 설정하세요.이제 위 항목들을 기반으로 실무에서 어떻게 활용할 수 있을지, 그리고 앞으로의 예측에 대해 정리해보겠습니다.
🔍 정리하며: 실전에서 바로 쓸 수 있는 체크리스트
Next.js 페이지가 보이지 않을 때 당황하지 마세요. 위에서 다룬 7가지 항목을 하나씩 점검해보면 대부분의 문제는 비교적 쉽게 해결할 수 있어요. 특히 배포 환경과 로컬 개발 환경이 다르다는 점을 인식하고, 설정 파일과 환경 변수를 신중하게 관리하는 것이 핵심입니다.
실제 기업에서도 작은 오타나 경로 문제로 인해 서비스 장애가 발생하는 경우가 빈번하기 때문에, 이 글의 체크리스트를 프로젝트 초기에 팀원들과 공유하고 사전에 점검하는 문화를 갖는 것이 중요해요.
앞으로는 Next.js의 App Router 방식이 점차 보편화되면서, 구성 방식 자체도 조금씩 바뀌게 될 것입니다. 따라서 최신 문서와 릴리즈 노트를 꾸준히 확인하고, 공식 문서를 주기적으로 살펴보는 습관이 필요합니다.
🏷️ 태그
Next.js 오류, 페이지 안 뜸, next build, next start, 배포 오류, nextjs 디버깅, 개발자 팁