[Django] 배포 후 Admin 페이지 CSS 깨짐 현상

안녕하세요. 배트맨입니다.🦇

오늘 내용은 트러블 슈팅 과정입니다.

---

Django 프로젝트를 Nginx와 Gunicorn으로 배포한 후, 다른 페이지는 정상적으로 보이지만 Admin 페이지의 UI(CSS)만 깨져 보이는 현상에 대한 원인 분석 및 해결 과정.

현상

• 웹사이트의 일반 페이지들은 CSS가 정상적으로 적용되어 보임.
• Django 관리자 페이지(/admin/)에 접속하면 CSS가 전혀 적용되지 않은 순수 HTML 페이지만 나타남.
• 브라우저 개발자 도구(F12)의 '네트워크' 탭을 확인하면, admin 관련 CSS 파일들이 404 (Not Found) 오류를 반환함.
•  

원인 분석

→ collectstatic 명령어는 프로젝트의 모든 정적 파일(앱 내부의 파일 + Django 자체의 admin용 파일)을 하나의 디렉토리(예: /home/ubuntu/project/staticfiles/)로 모은다.

→ Nginx는 /static/ URL로 들어오는 요청을 이 디렉토리로 연결해줘야 하는데, nginx 설정 파일에서 이 부분이 잘못되면 파일을 찾지 못한다.

→ Nginx가 Django Admin의 정적 파일을 찾지 못하기 때문이다.

진단 과정

collectstatic 실행 여부 확인

가장 먼저, admin의 정적 파일들이 staticfiles 디렉토리에 제대로 복사되었는지 확인한다.

ls -l [STATIC_ROOT 경로]/admin/css/
ls -l /home/ubuntu/[project]/staticfiles/admin/css/

결과: 첫 번째 명령어에서 base.css, dark_mode.css 등 다수의 CSS 파일 목록이 정상적으로 출력됨.

→ collectstatic 명령어는 성공적으로 실행되었고, 파일 자체는 올바른 위치에 존재한다.

 

Nginx 설정 파일 확인

현재 적용된 Nginx 설정 내용에서 static 파일 처리 로직을 점검한다.

cat /etc/nginx/sites-available/[project]

⚠️ 확인된 설정 (문제의 원인):

location /static/ {
   root /home/ubuntu/[project]/staticfiles/;
}

❌ 문제점:

Nginx의 root 지시어는 요청된 URI를 root 경로 뒤에 그대로 이어 붙인다.

 

(예시)

• 요청 URL:
  /static/admin/css/base.css
• Nginx가 찾는 파일 경로:
  /home/ubuntu/[project]/staticfiles/ + /static/admin/css/base.css

👉 결과:

/home/ubuntu/ [project] /staticfiles/static/admin/css/base.css 라는 잘못된 경로를 찾게 되므로 404 오류가 발생한다.

💡 해결:

Nginx의 location 블록에서 root 대신 alias를 사용하여 정확한 경로를 매핑해준다.

sudo nano /etc/nginx/sites-available/[project]

# 수정 전:
location /static/ {
    root /home/ubuntu/[project]/staticfiles/;
}

# 수정 후:
location /static/ {
    alias /home/ubuntu/[project]/staticfiles/;
}

결과

브라우저에서 강력 새로고침을 실행한 후,

Admin 페이지의 CSS가 정상적으로 로드되어 UI가 잘 나온다!