화면 캡처 2025-11-24 233057.png

📌 이미지가 안 뜨는 문제 해결 과정

홈페이지를 처음 띄웠을 때, 분명 static/images 폴더에 파일이 있는데도 메인 화면에 이미지가 전혀 보이지 않는 문제가 있었다. 아래는 이 문제를 해결한 과정을 단계별로 정리한 것이다.

1단계 – 문제 확인

브라우저에서 개발자 도구(F12)를 열어 보니, 이미지 경로에서 404 에러가 발생하고 있었다. 즉, 경로 자체가 잘못되었다는 뜻이었다.

2단계 – 원인 추측

HTML 코드에서는 이미지를

<img src="images/product1.jpg">

처럼 상대 경로로만 작성해 두었다. Flask에서는 정적 파일을 static 폴더에서 서빙하기 때문에, 이 방식을 그대로 쓰면 실제 서버 경로와 어긋날 가능성이 높다고 판단했다.

3단계 – 코드 수정

Flask에서 권장하는 방식대로 url_for()를 사용해 경로를 수정했다.

<img src="{{ url_for('static', filename='images/product1.jpg') }}">

이렇게 바꾸면 Flask가 실제 정적 파일 경로를 자동으로 만들어 주기 때문에, 폴더 구조가 바뀌어도 안전하다.

4단계 – 재실행 및 검증

서버를 다시 실행하고 새로고침을 하자, 404 에러가 사라지고 모든 이미지가 정상적으로 로딩되었다. 같은 방식으로 다른 템플릿의 이미지도 한 번에 수정할 수 있었다.

5단계 – 팁 정리

이 경험 이후로는 정적 파일을 사용할 때 항상 url_for('static', filename=...) 패턴을 기본으로 사용하고 있다. 작은 습관이지만, 경로 문제로 시간을 낭비하지 않게 해 준 중요한 디버깅 포인트였다.

화면 캡처 2025-11-24 233444.png

📌 팁

디버깅 과정에서 반복적으로 마주친 문제들을 해결하면서 자연스럽게 얻은 몇 가지 팁이 있다. 먼저, 정적 파일 경로는 반드시 url_for()로 관리하는 것이 가장 큰 도움이 되었다. 처음에는 이미지와 CSS가 정상적으로 표시되지 않아 원인을 찾느라 시간을 많이 썼다. 하지만 단순한 상대 경로 대신 url_for('static', filename='images/example.jpg') 방식을 사용하자, 경로 충돌이나 파일 미인식 문제가 한 번에 해결되었다. 이후로는 모든 정적 파일을 이 방식으로 통일해 안정적으로 관리할 수 있었다.

또한, 화면에 값이 비어 보이거나 예상과 다르게 출력될 때는 템플릿으로 넘기는 데이터를 print로 먼저 확인하는 습관이 큰 효과를 주었다. HTML 구조를 의심하기보다, return render_template() 직전에 변수값을 출력해 보면 어떤 단계에서 데이터가 누락되었는지 명확하게 파악할 수 있었다. 이 방법을 정착하고 나서는 디버깅 속도가 눈에 띄게 빨라졌다.

마지막으로, 수정한 내용이 화면에 반영되지 않을 때는 브라우저 캐시가 원인인 경우가 많기 때문에 Ctrl + Shift + R로 강력 새로고침을 하는 것이 안정적이다. 작은 팁들이지만, 실제 개발 과정에서는 시간을 아끼고 문제를 빠르게 해결하는 데 큰 도움이 되었다.