[Nginx] /etc/nginx/conf.d/default.conf 404 에러

1. 서론

React 로 웹 프로젝트를 만들고 Nginx 를 기본이미지로 하여 Docker Container 를 구동 후 테스트 중 새로고침시 404 Notfound 에러가 발생했다. 이를 해결한 방법을 기술한 내용이다.

 

2. 본론

2.1. 왜 404 에러가 발생할까?

가장 큰 이유는 서버 사이드 라우팅(SSR)과  클라이언트 사이드 라우팅(CSR) 의 차이 때문이다.

예를들면

 

• React/Vue 앱은 index.html(dist 하위 유일한 물리적 html 파일) 하나만 서버로부터 받고, 그 안에서 자바스크립트가 /mypage, /login 같은 가짜 주소를 만들어낸다(클라이언트 사이드 라우팅).
• 사용자가 /dashboard 경로에서 새로고침을 누르면, 브라우저는 Nginx 서버에 "야, /usr/share/nginx/html/dashboard 라는 파일 좀 줘!"라고 직접 요청을 보낸다.
• 하지만 실제 서버 폴더(root) 안에는 index.html 파일만 있을 뿐, dashboard라는 파일이나 폴더는 물리적으로 존재하지 않는다.
• Nginx는 "그런 파일 없는데?" 하고 404 Not Found를 띄우는 것이다.

 

 

2.2. 해결 방법

Nginx 를 기본이미지로 한 Container 내부의 /etc/nginx/conf.d/default.conf 경로에 다음과 같은 내용이 있으면 된다.

server {
    listen       80;
    listen  [::]:80;
    server_name  localhost;

    #access_log  /var/log/nginx/host.access.log  main;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
		
        # 다른 부분은 기본으로 생성
		# 이 부분이 추가되어야 함
        try_files $uri $uri/ /index.html =404;
    }

 

2.3. try_files ?

Nginx에게 "파일이 없더라도 당황하지 말고 일단 index.html을 보여줘!" 라고 명령을 내려야 한다. 그 명령어가 바로 try_files 이다.

다음 구문에 대한 상세 내용이다.

1. $uri: 사용자가 요청한 주소에 딱 맞는 실제 파일이 있는지 먼저 확인한다. (예: logo.png 요청 시 실제 파일이 있으면 바로 전송)
2. $uri/: 요청한 주소에 해당하는 디렉토리가 있는지 확인한다.
3. /index.html: 위 두 개가 다 없다면, 무조건 index.html 파일을 클라이언트에게 보낸다.
   • 일단 유일한 정적 파일 index.html 을 반환.
   • 내부의 자바스크립트(React/Vue Router)에서 정의된 엔드포인트의 컴포넌트 호출
   • /dashboard -> dashboard.jsx 를 표출
4. =404: 만약 index.html 마저 없다면 그때 비로소 404 에러를 냅니다.

 

React/Vue 같은 CSR 을 Nginx 웹서버를 이용하여 화면을 표출할 때 꼭 설정해야 하는 내용이다.