Build된 React 파일을
HTTP 응답으로 바꾼다

입력과 출력

요청 하나에는 URL만 있는 것이 아니다

Browser가 GET /을 보낼 때 method, path, host와 여러 header가 함께 전달된다. Nginx는 어느 server block이 받을지 고르고, 그 안에서 가장 잘 맞는 location을 선택한 다음 response를 만든다.

현재 전체 코드

server {
    listen 80;
    server_name _;
    server_tokens off;

    root /usr/share/nginx/html;
    index index.html;

    location = /healthz {
        access_log off;
        default_type text/plain;
        return 200 "ok\n";
    }

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

    location ~* \.(?:css|js|svg|png|jpg|jpeg|gif|webp|ico|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        try_files $uri =404;
    }
}

설정이 실행되는 순서

try_files는 없는 파일을 무조건 성공시키는 규칙이 아니다

try_files $uri $uri/ /index.html은 요청 path와 같은 파일, 같은 directory, 마지막으로 index.html을 순서대로 시도한다. React의 client-side router는 최초 HTML과 JavaScript가 실행된 뒤 /chat/example 같은 경로를 화면으로 해석하므로 새로고침 요청에도 먼저 index.html을 보내야 한다.

반면 asset location은 try_files $uri =404를 사용한다. 존재하지 않는 JavaScript 요청에 index.html을 돌려주면 status는 200이어도 Browser가 HTML을 JavaScript로 해석하려다 오류가 난다. 현재는 정규식에 나열한 css, js, svg, png, jpg, jpeg, gif, webp, ico, woff, woff2에 해당하는 경로만 없는 파일이면 404를 반환한다. /missing.json처럼 정규식에 없는 확장자는 location /로 들어가 index.html fallback이 될 수 있다. “확장자가 있는 모든 asset을 404로 처리한다”는 설명은 현재 설정과 다르다.

1년 cache가 가능한 이유는 filename에 내용의 지문이 있기 때문이다

Vite는 보통 내용에서 계산한 hash를 filename에 포함한다. JavaScript 내용이 바뀌면 index-a1b2.js가 index-c3d4.js처럼 새 이름이 되고 새 index.html은 새 파일을 가리킨다. 그래서 기존 asset을 오래 보관해도 새 배포와 섞일 가능성이 낮다.

expires 1y는 Expires와 max-age를 설정하고 add_header는 public, immutable을 추가하므로 실제 응답에는 Cache-Control이 여러 줄로 표시될 수 있다. 위 header 예시는 설명용 일부이며 실제 전체 응답을 그대로 복사한 기록은 아니다.

immutable은 저장 기간 동안 파일이 바뀌지 않을 것이라고 Browser에 알린다. 이 정책을 hash가 없는 index.html에 똑같이 적용하면 이전 HTML이 새 asset 이름을 알지 못할 수 있으므로 HTML cache 정책은 별도로 설계해야 한다.

FastAPI가 추가되면 정적 파일 요청과 API 요청이 갈라진다

Nginx를 reverse proxy로 사용한다면 Browser는 하나의 origin만 알면 되어 CORS 구성이 단순해진다. 대신 streaming 응답이 중간에서 buffering되지 않도록 timeout과 proxy buffering 설정을 검토해야 한다. 이 규칙은 FastAPI endpoint가 실제로 정해진 뒤 추가하는 것이 안전하다.