nginx 문법 정리

정혜인·2025년 7월 11일

클라우드

목록 보기

13/15

배포를 하기 위해 항상 nginx를 사용해왔지만, 정작 nginx에서 의미하는 문법은 정확히 모른 채 ‘그냥 이렇게 써야지’하면서, 혹은 ai에 의존해서 수정하며 사용해왔습니다.

그런데 하나의 origin url에 여러 레포를 라우팅하여 배포해야 한다거나 하는 복잡한 상황들이 생기면서 배포하는 데 시간을 점점 많이 쏟게 되었고, 처음부터 정확히 알아야겠다는 생각을 하게 되었고, 이번 기회에 정리를 해 두려고 합니다 ㅎㅎ,,

🧱 nginx는 왜 필요할까?

nginx는 기본적으로 HTTP 서버이자, Reverse Proxy 서버, Load Balancer, 정적 파일 서버 등의 기능을 가진 서버 소프트웨어입니다.

특히 docker 기반의 다중 서비스 배포 환경에서 nginx는 아래 역할을 수행하는 데 자주 사용됩니다.

정적 파일 제공 (예: React로 빌드된 /index.html 등)
API 서버와 클라이언트 서버 간 요청을 경로 기반으로 라우팅
WebSocket과 같은 특별한 프로토콜을 프록시로 전달
HTTPS 인증서와 연결된 SSL 처리

특히 제가 겪은 경우처럼 여러 레포를 하나의 origin에서 서브 경로(/user, /server 등)로 나눠 배포할 때 nginx의 설정은 핵심 역할을 하게 됩니다.

🔤 location 블록의 기본 문법

nginx 설정의 핵심은 location 블록입니다. 요청된 URI가 어떤 location과 매칭되는지에 따라 처리 로직이 달라집니다.

location [ = | ~ | ~* | ^~ ] uri {
    # 구성 지시어들
}

옵션 정리

= : 정확한 일치. URI가 딱 맞아떨어질 때만 적용됨
~ : 정규표현식, 대소문자 구분
~* : 정규표현식, 대소문자 구분 없음
^~ : 접두사 일치, 정규표현식보다 우선
(없음) : 일반적인 접두사 매칭. 가장 긴 접두사 우선

예시 정리

server {
    location / {
        # 모든 요청을 처리
    }

    location = / {
        # 정확히 '/'에 대한 요청만 처리
    }

    location /images/ {
        # '/images/'로 시작하는 요청 처리
    }

    location ~ \.(gif|jpg|png)$ {
        # .gif, .jpg, .png로 끝나는 요청 (대소문자 구분)
    }

    location ~* \.php$ {
        # .php로 끝나는 요청 (대소문자 구분 없음)
    }

    location ^~ /static/ {
        # '/static/'로 시작하는 요청은 정규식보다 우선
    }
}

🔍 nginx 예시

server {
    listen 80;
    server_name localhost;

    location = /user {
        return 301 /user/;
    }

    location ^~ /user/ {
        proxy_pass http://frontend-app;
        try_files $uri $uri/ /index.html;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/ {
        proxy_pass http://backend-api:3000/;
    }

    location / {
        root /usr/share/nginx/html;
        index index.html;
    }
}

한 줄씩 해석해보기

위의 nginx.conf 파일을 한 줄씩 해석해보자면 아래와 같습니다.

listen 80;: 80번 포트에서 HTTP 요청 수신
server_name localhost;: 도메인이 localhost일 때 해당 서버 블록 적용
location = /user { return 301 /user/; }: /user로 접속되면 /user/로 리디렉션
location ^~ /user/ { ... }: /user/ 경로로 시작하는 요청은 모두 프론트엔드로 프록시
try_files $uri $uri/ /index.html;: 정적 파일 없으면 index.html을 반환 (SPA 대응)
proxy_set_header: 프록시 대상에게 전달될 HTTP 헤더 설정
location /api/ { proxy_pass http://...; }: API 요청은 백엔드로 전달
location / { root /usr/share/nginx/html; index index.html; }: 루트 요청은 Nginx가 정적 파일로 응답

📘 자주 쓰는 지시어 설명

✅ proxy_pass

프록시로 요청을 넘길 서버 주소를 지정합니다. 내부적으로 경로 매칭 이후에 남은 URI를 붙이게 됩니다.

location /api/ {
    proxy_pass http://localhost:3000/;
}

/api/users 요청 → http://localhost:3000/users로 전달됨

✅ proxy_set_header

프록시로 요청을 보낼 때 헤더를 명시적으로 설정하는 것. 주로 보안 및 클라이언트 IP 확인을 위해 사용합니다.

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

✅ try_files

정적 파일 요청일 때 존재 여부를 확인해 응답할 파일을 지정합니다. 없을 경우를 위한 fallback 파일 지정 가능합니다.

try_files $uri $uri/ /index.html;

/user/dashboard로 접근 시 실제 파일이 없으면 index.html을 반환하여 SPA 라우팅 처리

✅ root

Nginx가 정적 파일을 직접 서빙할 때 참조하는 디렉토리 경로를 지정합니다.

location / {
    root /usr/share/nginx/html;
    index index.html;
}

nginx를 사용하여 배포할 때마다 다양한 기능과 옵션이 존재해서 상황에 맞게 잘 설정하지 않으면 예상하지 못한 동작이 발생합니다.

이번에 같은 origin에 여러 레포를 배포하며 내가 nginx를 제대로 알지 못하고 쓰고 있었다는 것을 느끼게 되었고, (너무 당연하지만;;) 제대로 이해하고 사용하는 게 진짜 중요하다는 것 .. 그리고 사실 nginx 설정은 자주 하는게 아니기 때문에 매번 잊어버려서 잘 정리해두는 것이 중요하다는 걸 실감했습니다….