[20250916 웹개발 이슈] 한글 파일명 이미지

- 이슈 상황

웹페이지에서 이미지를 불러올 때 파일명이 운전면허증.jpg처럼 한글로 되어 있는 경우
개발 서버에서는 정상적으로 이미지를 불러오는데 운영 서버에서는 이미지를 정상적으로 불러 오지 못 했다.
는 걸 운영에 반영하고 나서야 깨달음 꺅 ! 

 

---

- 문제점 

<img src="https://www.site.com/images/운전면허증.jpg" />

위과 같이 <img> 태그에 한글 파일명을 썼을 때, 브라우저는 실제로 아래처럼 자동으로 URL 인코딩하여 요청한다. 즉, 파일명의 한글이 인코딩되어 서버에 요청이 된다는 것 

GET /images/%EC%9A%B4%EC%A0%84%EB%A9%B4%ED%97%88%EC%A6%9D.jpg

따라서 서버가 이 인코딩된 요청을 디코딩해주지 않으면, 실제 존재하는 운전면허증.jpg 파일과 일치하지 않아 404 Not Found 에러가 발생하게 됨.

코드가 완전히 똑같은데 개발과 운영. 서버의 차이라면 버전을 의심해 보아야 한다. 

환경 : 개발에서는 서버를 Tomcat 8을 사용하고 있고, 운영에서는 Tomcat 7를 사용하고 있어 (왜 다른 환경을 쓰고 있는지 물어보지 마라. 입사할 때부터 그랬다.) 확인해보니 8 버전에서는 자동으로 디코딩 처리를 하고 있어 정상적으로 동작이 되었다는 점 ! 

---

Tomcat 8
- 내부적으로 URL 디코딩하여 운전면허증.jpg로 매핑

Tomcat 7
- %EC%9A%B4...jpg 경로 그대로 찾음
- 해당 경로에 일치하는 파일 없으면 404

---

해결방법 : 

1. 한글을 쓰지 않는다 ( 띠 용 쓰 )

1_R250911-driver_license.jpg
1_R250911-운전면허증.jpg

장점:
브라우저 인코딩 문제 없음
서버 환경 무관하게 안정적
URL 인코딩/디코딩 따로 신경 쓸 필요 없음

2. 꼭 한글을 써야 한다면? 브라우저에서 인코딩 처리
JS 코드에서 태그의 src를 설정할 때, 한글이 포함된 파일명을 반드시 encodeURIComponent()로 감싸서 인코딩해줘야 한다. 그리고 서버도 이 요청을 디코딩해줄 수 있어야 정상 표시됨

const fileName = "운전면허증.jpg";
img.src = "/images/" + encodeURIComponent(fileName);
// → /images/%EC%9A%B4%EC%A0%84%EB%A9%B4%ED%97%88%EC%A6%9D.jpg

하지만 정적 리소스(/images/파일명)는 서버 로직 없이 바로 응답되기 때문에 톰캣 7 이하 환경에서는 이 디코딩이 자동으로 안 되어서 여전히 깨질 수 있다.
==> 그러니 걍 영어 파일명 쓰는 걸 추천 

---

챗지피티가 알려준 실무 팁 : 
파일 업로드 시, 서버에서 한글 파일명을 UUID, 영문 label, 숫자 조합 등으로 자동 변경하는 것이 일반적이라고 함 
ex) 운전면허증.jpg → 2_R250911_driver_license.jpg