Thymeleaf + Nginx 환경에서 CSS/JS 로딩 및 404 라우팅 완벽 해결 가이드

Spring Boot 배포 시 발생하는 정적 리소스 미로딩 및 경로 유실 문제를 아키텍처 관점에서 분석하고 해결합니다.

1. 문제 현상 및 아키텍처 이해

로컬 환경(8080 포트)에서는 완벽하게 동작하던 애플리케이션이 Nginx 프록시를 거치면 정적 리소스를 찾지 못하거나, 새로고침 시 404 에러가 발생하곤 합니다. 이는 클라이언트의 요청이 서버에 도달하는 경로가 복잡해지면서 발생하는 경로 불일치(Path Mismatch) 문제입니다.

현상	주요 원인
CSS/JS 404 에러	Nginx가 요청을 Spring Boot로 넘기지 않고 직접 찾으려 하거나, 상대 경로가 깨짐
페이지 새로고침 시 404	Nginx가 해당 URL을 파일 경로로 오해하여 처리함

2. 핵심 해결 방안

① Nginx 설정 최적화 (Reverse Proxy)

단순한 proxy_pass 외에, 헤더 정보를 정확히 전달하여 Spring Boot가 원본 요청 주소를 알 수 있게 해야 합니다.


server {
    listen 80;
    server_name your-domain.com;

    # 1. 정적 리소스 직접 처리 (성능 향상)
    location /static/ {
        alias /var/www/app/static/; # 실제 정적 파일 경로
        expires 30d;
        access_log off;
    }

    # 2. 모든 요청을 Spring Boot로 포워딩
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SPA 혹은 복잡한 라우팅 대응
        try_files $uri $uri/ @proxy;
    }

    location @proxy {
        proxy_pass http://localhost:8080;
    }
}

② Spring Boot & Thymeleaf 경로 전략

Thymeleaf의 @{...} 문법은 컨텍스트 경로를 자동으로 계산하지만, Nginx 설정과 일치해야 합니다. 가장 권장되는 방식은 절대 경로 기반의 리소스 참조입니다.

Tip: spring.mvc.static-path-pattern 설정을 변경했다면 모든 템플릿의 링크 구조를 통일해야 합니다.


<!-- 추천 방식: 컨텍스트 경로를 포함하는 절대 경로 참조 -->
<link rel="stylesheet" th:href="@{/css/main.css}">
<script th:src="@{/js/app.js}"></script>

3. 성능 및 보안 강화 (추가 고려사항)

Gzip 압축: gzip on; 설정을 통해 JS/CSS 파일 크기를 줄여 로딩 속도를 개선하세요.
Cache Control: Nginx에서 정적 파일에 대해 Cache-Control 헤더를 설정하면 반복 방문 시 로딩 속도가 비약적으로 빨라집니다.
Strict-Transport-Security: HTTPS 적용 시 보안 헤더를 추가하여 중간자 공격을 방지하세요.

✅ 최종 체크리스트

Nginx 문법 검사: nginx -t 명령어로 오타가 없는지 확인했나요?
파일 권한: Nginx 실행 계정(www-data 등)이 정적 파일 폴더에 접근 권한이 있나요?
브라우저 캐시: Ctrl + Shift + R을 눌러 강력 새로고침으로 확인했나요?
Mixed Content: HTTPS 환경에서 HTTP 리소스를 호출하여 블락되고 있지 않나요?

Thymeleaf + Nginx 환경에서 CSS/JS 로딩 및 라우팅 문제 해결하기