[Next.js14 강의] 25강 - 배포 후 문제 해결 및 로그 확인

안녕하세요! 그레이 해커 월횽입니다. 이번 강의에서는 배포 후 발생할 수 있는 문제를 해결하는 방법과 Vercel에서 제공하는 로그 확인 기능을 통해 문제를 진단하는 방법을 다룹니다. 빌드 실패, 배포 오류, 환경 변수 문제 등과 같은 일반적인 문제를 해결하고 애플리케이션의 안정성을 유지하는 방법을 학습합니다.

 

 

1. 배포 후 문제 확인 방법

 

1-1. 배포 후 자주 발생하는 문제

배포가 완료된 후 애플리케이션에서 발생할 수 있는 문제들은 주로 다음과 같습니다.

· 빌드 오류: 빌드 단계에서 발생하는 문제로, 종종 코드나 의존성 충돌로 인해 발생합니다.
· 페이지 로드 오류: 배포 후 페이지가 정상적으로 로드되지 않거나 404, 500 에러가 발생할 수 있습니다.
· 환경 변수 오류: 잘못된 환경 변수가 설정되어 데이터베이스 연결 실패 또는 API 호출 실패 등의 문제가 발생할 수 있습니다.
· 의존성 문제: 프로젝트에 필요한 패키지가 누락되었거나 버전이 호환되지 않는 경우 빌드나 실행 시 오류가 발생할 수 있습니다.

반응형

1-2. 로그 확인의 중요성

문제를 해결하기 위해서는 정확한 원인을 파악하는 것이 중요한데, 이를 위해 로그(Log) 를 확인하는 것이 필수적입니다. Vercel은 배포 과정과 실행 중 발생한 로그를 실시간으로 제공하므로 이를 통해 빠르게 오류를 진단할 수 있습니다.

 

 

2. Vercel에서 로그 확인 방법

 

2-1. 빌드 및 배포 로그 확인

· Vercel 대시보드에서 배포된 프로젝트를 선택합니다.
· 배포 내역(Deployments)에서 각 배포의 빌드 로그를 확인할 수 있습니다.
Build Logs: 빌드 과정에서 발생한 오류나 경고를 확인할 수 있습니다.
Server Logs: 서버 측에서 발생하는 문제나 예외 처리, API 요청 등의 로그를 확인할 수 있습니다.

728x90

빌드 로그 예시

$ npm run build
> Error: Cannot find module 'react'
> This module is required for building the project.
> Build failed with error code 1

 

위와 같은 로그가 발생하면 해당 모듈이 설치되지 않았거나 의존성 버전이 맞지 않는 것을 의미합니다. package.json을 확인하고, 필요한 패키지를 다시 설치합니다.

 

2-2. API 로그 확인

Next.js의 API Routes 기능을 사용할 경우, Vercel의 Server Logs 탭에서 API 호출에 대한 로그를 확인할 수 있습니다.

API 요청 성공 여부, 에러 발생 시의 상세 로그를 통해 문제를 해결할 수 있습니다.

 

 

3. 배포 후 발생할 수 있는 일반적인 문제 해결

 

3-1. 빌드 실패 문제

빌드 실패의 주요 원인은 주로 코드 오류, 의존성 충돌, 파일 경로 문제 등에서 발생합니다.

 

해결 방법

의존성 설치 문제
· 패키지 의존성이 누락되었거나 충돌한 경우, package.json을 다시 확인하고 npm install 또는 yarn install 명령어를 실행합니다.
· 필요시 package-lock.json 또는 yarn.lock 파일을 삭제하고, 의존성을 다시 설치합니다.

코드 오류
· 컴파일 또는 타입 오류가 있는지 빌드 로그에서 확인합니다. 빌드 로그를 따라 문제를 수정합니다.

경로 오류
· 파일 경로를 잘못 지정했거나, 대소문자 구분이 제대로 이루어지지 않은 경우 발생할 수 있습니다. 파일 경로를 확인하여 수정합니다.

 

3-2. 404, 500 에러 문제

404 Not Found: 특정 페이지나 API가 배포 후에 로드되지 않을 때 발생하는 문제로, 라우팅 설정이 잘못되었거나 파일이 누락된 경우에 주로 발생합니다.
해결 방법: Next.js의 pages 디렉토리에서 파일이 정확히 위치해 있는지 확인하고, 동적 라우팅 설정을 점검합니다.

SMALL

500 Internal Server Error: 서버 측 오류로 주로 API 호출 실패, 데이터베이스 연결 문제, 또는 서버 코드를 실행하는 중 발생하는 오류입니다.
해결 방법: 서버 로그를 확인하여 문제를 진단하고, API 라우트나 서버 코드에서 예외 처리를 확인합니다.

 

3-3. 환경 변수 문제

환경 변수가 제대로 설정되지 않으면 API 키나 데이터베이스 연결 등에서 문제가 발생할 수 있습니다.

 

해결 방법
1. Vercel 대시보드에서 환경 변수를 설정할 수 있는지 확인합니다. 환경 변수는 Settings > Environment Variables에서 관리합니다.
2. next.config.js에서 환경 변수를 정확히 읽어오는지 확인합니다.
3. 환경 변수 사용법:
환경 변수는 process.env를 통해 접근합니다.

const apiKey = process.env.API_KEY;

 

3-4. 이미지 및 정적 파일 문제

이미지나 정적 파일이 배포 후 로드되지 않을 때는 파일 경로나 정적 자산 관리 설정이 잘못되었을 가능성이 있습니다.

해결 방법
이미지 최적화 설정: Next.js의 next/image를 사용할 경우 이미지 최적화 설정을 점검합니다.
정적 파일 관리: public 디렉토리 내의 파일 경로가 정확한지 확인합니다.

 

 

4. 문제 발생 시 롤백(Rollback) 기능 활용

배포 후 문제가 발생하면, Vercel의 롤백 기능을 사용하여 이전에 안정적으로 배포된 버전으로 되돌릴 수 있습니다. 롤백은 문제가 해결될 때까지 임시로 애플리케이션을 정상 상태로 유지하는 데 유용합니다.

롤백 방법
Vercel 대시보드에서 이전 배포 내역으로 이동합니다.
해당 배포 버전을 선택하고 Rollback 버튼을 클릭하여 이전 버전으로 되돌립니다.

 

 

5. 배포 후 문제를 예방하는 팁

· 테스트 환경 구축: 로컬에서 다양한 테스트 환경을 통해 문제가 발생하기 전에 미리 해결할 수 있도록 합니다. 특히 스테이징 환경에서 문제를 사전에 발견하는 것이 중요합니다.
·  자동화된 테스트 도입: CI/CD 파이프라인에서 자동화된 테스트를 통해 코드 품질을 유지하고 배포 후 발생할 수 있는 문제를 최소화합니다.
·  로깅 및 모니터링: Vercel과 같은 배포 플랫폼의 로그 확인 기능을 자주 활용하고, 외부 서비스(예: Sentry, Datadog)를 통해 애플리케이션을 모니터링하면 문제를 신속하게 대응할 수 있습니다.

이번 강의에서는 배포 후 발생할 수 있는 문제 해결과 로그 확인 방법을 배웠습니다. 빌드 실패, 환경 변수 문제, 페이지 로드 에러 등 다양한 문제를 어떻게 진단하고 해결할 수 있는지 살펴보았으며, Vercel의 로그 시스템과 롤백 기능을 통해 문제를 빠르게 해결할 수 있습니다.

 

 

 

 

 

- 이전 수업 목록