Django 이미지가 보이지 않는 이유? static 태그와 |add 필터의 함정

"이미지 경로도 제대로 넣었고, 이미지 파일도 static 폴더에 잘 들어있는데… 왜 안 나올까?"

장고(Django)를 공부하면서 블로그 프로젝트를 만들던 중, 정상적으로 나오던 이미지가 갑자기 보이지 않는 현상을 겪었다.

경로를 따져봤을 때 /static/blog/images/파일명.jpg는 틀림없었고, 이미지도 static 디렉토리에 정상적으로 존재했는데, 화면에는 아무것도 뜨지 않았다.

---

문제 코드

<img src="{% static "blog/images/"|add:post.image_name %}" alt="{{ post.title }}">

처음에는 |add 필터를 사용해서 static 경로 뒤에 이미지 파일명을 붙여주는 방식으로 코드를 작성했다. 하지만 이렇게 하면 템플릿 렌더링 과정에서 예상치 못한 동작이 발생할 수 있다.

---

에러 원인

|add 필터는 문자열 연결에 사용될 수 있지만, 다음과 같은 이유로 문제가 발생할 수 있다:

• |add:는 타입이 맞지 않거나 None일 경우 제대로 동작하지 않는다.
• static 템플릿 태그는 문자열 리터럴로 경로를 받아야 한다.
• 템플릿 내에서 변수와 static 경로를 섞어 쓰면 의도치 않게 필터가 먼저 처리될 수 있다.

결과적으로 이미지가 <img src="/static/">로만 출력되고, 뒤의 파일명이 붙지 않게 되는 것이다.

---

해결 방법

문제 해결은 간단하다. static 경로와 image_name 변수를 각각 분리해서 처리하면 된다:

<img src="{% static 'blog/images/' %}{{ post.image_name }}" alt="{{ post.title }}">

이렇게 하면 Django가 아래 순서로 정확하게 경로를 처리한다:

1. {% static 'blog/images/' %} → /static/blog/images/
2. {{ post.image_name }} → 예: mountains.jpg
3. 최종 결과: /static/blog/images/mountains.jpg

---

체크포인트 🔍

• 이미지가 안 나올 땐 브라우저 개발자 도구(F12) → 이미지 src 경로를 꼭 확인해보자.
• <img src="/static/">까지만 나온다면, image_name이 제대로 연결되지 않은 것이다.
• |add: 필터는 문자열 연결보다 숫자 덧셈에 주로 사용되며, 예외 처리에 취약하다.

---

마무리 ✨

장고 템플릿에서는 static 경로와 변수 조합을 할 때 |add를 피하고, 가능한 한 명확하게 분리해서 작성하는 것이 좋다.