이미지 로딩이 환경마다 다를 때 체크리스트

이미지 로딩 문제는 복합적인 요인들이 겹쳐있을 수 있다. 컨테이너 환경, 네트워크 경로, 이미지 경로 설정, DNS 해석 등이 모두 영향을 미친다. 에뮬레이터와 실기기에서 다르게 동작할 수 있고, 로컬 개발과 운영 배포에서도 차이가 난다.

핵심 질문 먼저 정하기

이미지가 로드되지 않는가? 로드되지만 잘못된 이미지인가? 로드는 되지만 느린가? 각 상황에 따라 확인해야 할 것이 다르다.

제외할 원인부터 찾기

컨테이너 상태가 정상인지, 볼륨 마운트가 올바른지, 포트 매핑이 맞는지부터 확인한다.

docker ps
docker logs --tail=100 service-name
docker inspect service-name

환경 변수와 설정

이미지 서버 URL, 경로 prefix, CDN 설정이 각 환경에서 다를 수 있다. 로컬에서는 localhost, 운영에서는 프로덕션 도메인을 사용한다.

• 확인할 것: 볼륨 마운트, 포트 매핑, 컨테이너 상태
• 비교 기준: 정상 상태의 컨테이너
• 기록할 것: 이미지 경로, 환경 변수, 네트워크 설정

빌드 검증

이미지 태그가 정확한지, 컨테이너가 최신 이미지를 사용하는지 확인한다.

예상되는 정상 상태

컨테이너가 실행되고, 이미지 서버가 응답하고, 네트워크 경로가 정상이어야 한다. 로그에서 이 모든 단계가 완료되는지 확인한다.

비정상일 때 확인사항

에뮬레이터와 실기기의 네트워크 설정이 다를 수 있다. 에뮬레이터는 localhost를 특수한 IP 주소로 해석한다. 실기기는 실제 네트워크에 연결돼 있다.

# 에뮬레이터에서는 localhost 대신 10.0.2.2 사용
# 또는 실제 서버의 IP 주소와 포트 사용

마무리

Docker와 이미지 로딩의 조합은 네트워크와 파일시스템이 모두 관련되므로, 각 계층을 순서대로 확인해야 한다. 로그에서 정확히 어느 단계에서 실패하는지 찾으면 나머지는 자명하다.

완료 기준

1. 에뮬레이터와 실기기의 차이를 이해할 수 있는가
2. 각 환경의 네트워크 설정을 설명할 수 있는가
3. 이미지 로딩이 실제로 작동하는가

환경 간의 차이를 명확히 이해하면, 비슷한 문제가 나중에 생겨도 빨리 대응할 수 있다.