2025 . 오은

repo

localhost 모바일 테스트

문제 정의

Next.js를 사용하면서 모바일 기기에서 직접 테스트가 필요할 때가 있었습니다. 개발 중 localhost:3000으로 애플리케이션을 실행하면 데스크탑 브라우저에서는 정상적으로 작동하지만, 동일한 네트워크에 연결된 모바일 기기에서는 접근이 불가능하거나 API 요청이 실패하는 문제가 발생했습니다. 이는 모바일 기기가 localhost를 인식하지 못하고, 대신 실제 로컬 네트워크 IP 주소(예: 192.168.xx.xx)로 접근해야 하기 때문이었습니다.

또한, Next.js의 라우트 핸들러(route handler)를 사용하거나 서버사이드에서 fetch 요청을 보낼 경우, 기본적으로 localhost:3000을 대상으로 설정되어 있어 모바일 기기에서의 접근 시 API 요청이 실패하는 문제가 있었습니다. 이로 인해 로그인과 같은 기능에서 api/auth/login 요청이 제대로 작동하지 않아 "Load failed" 등의 오류가 발생하였습니다.

해결 과정

이 문제를 해결하기 위해 다음과 같은 단계를 통해 Next.js 애플리케이션을 로컬 네트워크에서 모바일 기기로 테스트할 수 있도록 설정을 변경했습니다.

1. package.json 수정

먼저, Next.js 개발 서버가 로컬 네트워크 IP 주소를 인식하도록 package.json 파일의 scripts 섹션을 수정했습니다. 이를 통해 개발 서버가 특정 호스트 IP 주소에서 실행되도록 설정할 수 있습니다.

"scripts": {
  "proxy": "next dev -H 192.168.xx.xx",
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "next lint"
},
  • proxy 스크립트는 개발 서버를 로컬 네트워크 IP 주소(192.168.xx.xx)에서 실행하도록 설정합니다. -H 플래그는 호스트를 지정하는 옵션으로, 자신의 테스트할 IP 주소를 정확히 입력해야 합니다.
  • 기본 dev 스크립트는 여전히 localhost:3000에서 개발 서버를 실행합니다.

2. 서버사이드 fetch URL 수정

클라이언트 사이드에서 /api/어쩌구저쩌구 형태로 fetch 요청을 보내는 경우, 별도의 수정이 필요 없었습니다. 그러나 서버사이드에서 fetch 요청을 보낼 경우, localhost 대신 실제 로컬 네트워크 IP 주소를 사용해야 합니다. 이를 위해 환경 변수를 활용하여 유연하게 설정할 수 있도록 했습니다.

NEXT_PUBLIC_BASE_URL="http://192.168.xx.xx:3000"
  • .env.local 파일에 NEXT_PUBLIC_BASE_URL 변수를 추가하여, 서버사이드 fetch 요청 시 사용할 기본 URL을 설정합니다.
  • 서버사이드 코드에서는 이 환경 변수를 참조하여 fetch 요청을 보냅니다.

3. 개발 서버 실행

위의 설정을 완료한 후, 모바일 기기에서 로컬 네트워크 IP 주소(192.168.xx.xx:3000)로 애플리케이션에 접속하면 모든 기능이 정상적으로 작동하게 되었습니다. 특히, 서버사이드 fetch 요청도 올바르게 처리되어 API 요청이 실패하지 않았습니다.

yarn proxy
  • yarn proxy 명령어를 실행하여, 수정한 package.json 스크립트를 통해 개발 서버를 로컬 네트워크 IP 주소에서 실행합니다.

결과

이러한 설정 변경을 통해 다음과 같은 개선 효과를 얻었습니다:

  • 모바일 기기에서의 원활한 접근: 모바일 기기에서 192.168.xx.xx:3000으로 접속하여 애플리케이션을 정상적으로 테스트할 수 있게 되었습니다.
  • API 요청의 성공적인 처리: 서버사이드 fetch 요청이 올바른 URL을 참조하게 되어, 로그인 등 중요한 기능에서 API 요청이 실패하지 않고 정상적으로 작동했습니다.
  • 개발 효율성 향상: 데스크탑과 모바일 기기 모두에서 동일한 로컬 개발 환경을 활용할 수 있어, 크로스 디바이스 테스트가 용이해졌습니다.
  • 코드 유지보수성 강화: 환경 변수를 활용한 유연한 설정으로, 개발 서버의 호스트 주소 변경 시 코드의 다른 부분을 수정할 필요 없이 환경 변수만 업데이트하면 되었습니다.

배운 점 (인사이트)

  • 환경 변수의 활용: .env.local 파일을 통해 서버사이드 fetch 요청의 기본 URL을 유연하게 설정함으로써, 개발 환경과 배포 환경 간의 설정을 손쉽게 관리할 수 있음을 배웠습니다.
  • 동적 호스트 설정의 중요성: 개발 서버를 로컬 네트워크 IP 주소에서 실행함으로써, 모바일 기기와 같은 다양한 디바이스에서 애플리케이션을 테스트할 수 있게 되었습니다.
  • Next.js의 호스트 옵션 이해: next dev -H 옵션을 활용하여 개발 서버의 호스트를 변경하는 방법을 학습하게 되었습니다. 이는 로컬 네트워크에서 애플리케이션을 테스트할 때 매우 유용한 기능입니다.
  • 디바이스 간 테스트의 중요성: 다양한 디바이스에서의 애플리케이션 동작을 테스트함으로써, 사용자 경험을 개선하고 잠재적인 문제를 사전에 발견할 수 있었습니다.