SPA에서 새로고침할 때 404가 나는 이유는 무엇인가요?

브라우저가 현재 경로를 서버에 직접 요청할 때 서버가 해당 파일을 찾지 못하면 404가 발생합니다.

Cloudflare Pages에서 SPA 404를 해결하려면 어떻게 하나요?

public/_redirects 파일에 /* /index.html 200 규칙을 추가해 모든 경로를 index.html로 전달합니다.

Choorai | 문서

KO EN

배포 후 자주 발생

SPA 404 에러 해결하기

React/Vue 앱 배포 후 새로고침하면 404가 뜨나요? SPA(Single Page Application)의 라우팅 설정 문제입니다.

TL;DR (핵심 요약)

모든 경로를 index.html로 리다이렉트하도록 설정하세요. 호스팅 서비스마다 설정 방법이 다릅니다.

심각

404 Page Not Found

원인

SPA는 클라이언트 사이드 라우팅을 사용합니다. 서버는 /about, /dashboard 같은 경로를 모르기 때문에 404를 반환합니다.

해결책

호스팅 서비스 설정에서 모든 경로를 index.html로 리다이렉트
Cloudflare Pages: _redirects 파일 생성
Vercel: vercel.json rewrites 설정
Nginx: try_files 설정

호스팅별 해결 방법

Cloudflare Cloudflare Pages

프로젝트 루트 또는 public 폴더에 _redirects 파일을 생성하세요.

public/_redirects

/* /index.html 200

Vercel

vercel.json

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Netlify

public/_redirects

/*    /index.html   200

또는 netlify.toml 파일:

netlify.toml

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Nginx

nginx.conf

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

왜 이런 문제가 발생하나요?

SPA는 JavaScript가 브라우저에서 URL을 처리합니다. 하지만 새로고침하면 브라우저가 서버에 해당 경로를 요청하고, 서버는 그 경로에 실제 파일이 없으니 404를 반환합니다. 해결책은 모든 요청을 index.html로 보내서 JS가 라우팅을 처리하게 하는 것입니다.

Prerequisites

React/Vue Router 등 클라이언트 라우팅을 사용 중이어야 합니다.
배포 대상 플랫폼 설정 파일(_redirects, vercel.json, nginx.conf)을 수정할 수 있어야 합니다.
실제 배포 URL에서 새로고침 동작을 테스트할 수 있어야 합니다.

Validation

서브 경로(/about, /dashboard)로 직접 진입해도 index.html이 로드됩니다.
새로고침(F5) 시 404가 발생하지 않습니다.
정적 파일(js/css) 응답이 정상이며 라우팅만 리라이트됩니다.

Troubleshooting

리라이트 규칙 파일이 빌드 산출물에 포함되는지 확인하세요.
플랫폼별 우선순위(redirect/rewrite/order)가 예상과 같은지 확인하세요.
API 경로까지 모두 index.html로 보내고 있지 않은지 분리 규칙을 확인하세요.

References

피드백 보내기

입력한 내용으로 새 이슈 페이지를 엽니다.

GitHub 이슈로 보내기