화면에 이미지가 비어 보이거나 이미지 리소스 누락 상태가 표시될 때는 파일 존재 여부만 확인해서는 해결되지 않습니다. 상대경로 기준점, 대소문자, 배포 산출물 포함 여부, CDN 캐시와 접근 권한을 분리해 점검하는 방법을 정리합니다.
이미지 리소스를 찾지 못할 때 확인하는 경로·권한·배포 순서
깨진 이미지 아이콘이 보이거나 화면 일부가 빈 영역으로 남는다면, 파일을 다시 올리기 전에 브라우저가 실제로 어디에 요청했는지부터 확인해야 합니다. 로컬에서는 정상인데 운영 화면에서만 실패하는 경우에는 경로 기준점과 서버 환경의 차이가 원인일 수 있습니다. 배포 직후 같은 증상이 반복된다면 이전 파일이 남은 캐시인지, 새 산출물에 파일이 빠진 것인지도 분리해야 합니다.
연다산동 STATUS_IMAGE_NOT_FOUND처럼 이미지 누락 상태가 표시될 때는 단순 파일 삭제로 단정하지 말고 요청 주소, 응답 코드, 배포 목록을 차례로 대조하는 편이 안전합니다. 특정 페이지에서만 비거나 관리자 화면에서만 나타나는 증상은 라우팅과 권한 정책까지 함께 봐야 합니다. 초기 확인이 필요하면 동네형컴퓨터 010-6833-8119 로 오류가 발생한 시각과 화면 상태를 먼저 알려주시면 됩니다.
요청 주소와 실제 파일 위치가 어긋나는 지점
가장 먼저 브라우저 개발자 도구의 Network 탭을 열고 실패한 이미지 요청을 찾습니다. 여기서 확인할 항목은 요청 URL, 응답 코드, Initiator 또는 Referer, 응답 크기입니다. 404 라면 요청한 위치에 파일이 없거나 주소가 달라진 경우가 많고, 403 이면 파일은 있어도 접근 권한이나 차단 규칙을 의심해야 합니다.
상대경로는 작성한 코드만 보고 판단하면 안 됩니다. images/banner.png는 현재 페이지 URL을 기준으로 계산되며, 라우트가 /notice/12인지 /notice/12/edit인지에 따라 실제 요청 위치가 달라질 수 있습니다. SPA 환경에서는 화면 전환 뒤 경로가 바뀌면서 이미지 기준점도 달라질 수 있습니다.
| 확인 결과 | 우선 점검할 범위 |
|---|---|
| 404 Not Found | 상대경로, 업로드 위치, 배포 산출물 누락, 파일명 변경 |
| 403 Forbidden | 폴더 권한, 인증 정책, 핫링크 차단, 보안 규칙 |
| 200 인데 이미지가 깨짐 | 잘못된 MIME 형식, 손상 파일, HTML 오류 응답 반환 여부 |
| 로컬만 정상 | 대소문자, 운영 경로, 빌드 결과물, CDN 캐시 |
파일은 있는데 운영 화면에서만 비는 이유
운영 서버는 파일명 대소문자를 구분하는 경우가 많습니다. 개발 PC에서 Logo.PNG와 logo.png가 같은 파일처럼 처리되더라도, 서버에서는 전혀 다른 주소가 됩니다. 코드에는 소문자로 적었는데 실제 업로드 파일은 대문자가 섞여 있다면 배포 후에만 이미지가 사라질 수 있습니다.
확장자와 공백도 확인 대상입니다. 이미지 원본명에 공백, 한글, 특수문자가 포함되면 인코딩 과정이나 업로드 처리 방식에 따라 요청 주소가 달라질 수 있습니다. 가능하면 영문 소문자, 숫자, 하이픈 중심의 파일명으로 정리하고, 실제 서버의 파일명과 HTML 또는 CSS에서 호출한 이름을 한 글자씩 비교하는 것이 좋습니다.
빌드 도구를 쓰는 프로젝트라면 정적 자산이 산출물에 포함됐는지도 별도로 봐야 합니다. 사용하지 않는 파일로 판단된 리소스가 제외되거나, 파일명 뒤에 해시값이 붙으면서 기존 주소가 무효가 될 수 있습니다. 소스 폴더에는 이미지가 있어도 배포 폴더에 없다면 서버 문제가 아니라 빌드 설정과 참조 방식의 문제입니다.
또한 이미지가 존재한다는 사실만으로 브라우저 접근이 보장되지는 않습니다. 업로드 디렉터리 읽기 권한, 로그인 사용자만 접근 가능한 정책, 외부 도메인 Referer 차단, 핫링크 방어 규칙이 있으면 이미지 요청은 실패합니다. 특히 다른 도메인에서 이미지를 불러오는 구성은 원본 서버의 접근 정책을 함께 확인해야 합니다.
캐시를 지우기 전에 비교할 배포 기록
캐시 삭제를 먼저 하면 원인 추적에 필요한 단서가 사라질 수 있습니다. 이전 배포본과 현재 배포본의 정적 파일 목록을 비교해 이미지 경로가 바뀌었는지, 매니페스트 파일이 새 해시명을 가리키는지 확인합니다. 배포 시점과 오류 발생 시점이 일치한다면 현재 운영 서버에 올라간 파일 목록이 기준입니다.
CDN을 사용하는 경우에는 원본 서버에 새 파일이 있어도 엣지 서버가 이전 주소나 삭제된 파일 정보를 일정 시간 유지할 수 있습니다. 이때 무효화 범위가 특정 파일인지, 폴더인지, 전체 경로인지 구분해야 합니다. 새 주소로 요청했는데도 오래된 응답이 돌아오는지 확인하려면 개발자 도구에서 캐시 사용을 끈 상태로 강력 새로고침을 진행하고, Network 탭에 새 요청이 기록되는지 봅니다.
수정 후에는 “화면이 보인다”는 결과만 확인하지 말고 새 파일 주소가 실제로 요청됐는지 확인해야 합니다. 이전 URL이 여전히 호출되면 소스 코드, 템플릿, CSS, 데이터베이스에 남은 참조를 찾아야 합니다. 반대로 새 URL 요청은 정상인데 이전 화면이 보인다면 CDN 또는 브라우저 캐시 잔존 가능성이 큽니다.
재현 화면이 필요한 경우
사내망, 관리자 전용 화면, 특정 계정 권한에서만 이미지가 비는 경우에는 일반 브라우저 테스트만으로 원인을 확정하기 어렵습니다. 원격 점검에서는 오류 화면, 개발자 도구 Console 내용, Network 의 요청 URL과 응답 정보, 가능하면 HAR 파일을 함께 준비하면 확인 범위가 크게 줄어듭니다.
화면 공유나 관리자 접근이 가능하면 경로 계산, 배포 설정, 권한 규칙을 원격으로 점검할 수 있습니다. 다만 내부망에서만 재현되거나 장비별 정책 차이가 있는 환경은 현장 확인이 필요할 수 있으며, 연다산동 방문 점검은 재현 조건과 일정을 먼저 확인한 뒤 진행합니다. 출장 점검은 09:00~18:00 서울·경기·인천·세종 범위에서 가능하고, 원격 점검은 새벽 시간을 제외하고 조율할 수 있습니다.
수정 전 남겨둘 오류 자료
이미지를 교체하거나 캐시를 비우기 전에 오류 자료를 남겨두면 같은 문제가 반복될 때 훨씬 빨리 판단할 수 있습니다. 특히 특정 페이지에서만 발생하거나 배포 직후마다 반복된다면 아래 자료가 경로 문제와 권한 문제를 가르는 기준이 됩니다.
- 오류가 보이는 전체 화면과 주소창이 포함된 캡처
- 문제가 발생한 정확한 시각과 사용한 브라우저
- 페이지 주소, 이미지 원본명, 이미지가 저장된 것으로 예상한 경로
- 배포 버전 또는 배포 시각, 변경한 파일 목록
- Network 탭의 요청 URL, 응답 코드, 응답 헤더 또는 HAR 파일
이미지 표시 실패는 파일 하나를 다시 업로드해 우연히 해결되는 경우도 있지만, 경로 기준점과 배포 산출물을 확인하지 않으면 다음 업데이트에서 다시 나타날 수 있습니다. 브라우저 요청 주소와 운영 서버의 파일 목록을 먼저 대조하고, 그 다음 권한과 캐시를 분리해 점검하는 순서가 안정적입니다. 수정 후에는 새 주소 요청과 이전 캐시 잔존 여부를 함께 검증해야 마무리됩니다.
자주 묻는 질문
이미지 리소스를 찾지 못했다는 상태는 무엇을 뜻하나요?
브라우저 또는 서비스가 요청한 주소에서 이미지 파일을 받지 못했다는 뜻입니다. 파일 삭제 외에도 잘못된 경로, 접근 권한 제한, 배포 누락, 캐시 불일치가 원인이 될 수 있습니다.
로컬에서는 보이는데 운영 사이트에서만 이미지가 안 보입니다. 왜 그런가요?
운영 서버의 대소문자 구분, 빌드 산출물 누락, CDN 캐시, 운영 경로 설정 차이가 대표적입니다. 실제 운영 URL의 응답 코드와 배포된 파일 목록을 먼저 비교해야 합니다.
원격으로 확인할 수 있는 범위는 어디까지인가요?
관리자 권한 또는 화면 공유가 가능하면 요청 URL, 브라우저 콘솔, 네트워크 응답, 배포 설정을 원격으로 점검할 수 있습니다. 사내망이나 서버 접근 제한으로 재현이 불가능한 경우에는 현장 환경 확인이 필요할 수 있습니다.
경로·권한·배포 기록을 기준으로 이미지 표시 오류를 정리하고 싶다면 동네형컴퓨터 010-6833-8119 로 문의해 주세요. 점검 자료 전달과 상담 안내는 https://udns.kr/에서 확인할 수 있습니다.