[Nginx] location 우선순위 정리

Nginx location 우선순위 요약

Nginx의 location은 설정 파일에 작성된 순서대로 단순히 위에서 아래로 적용되는 것이 아니라, 정해진 매칭 규칙에 따라 선택된다.

먼저 결론부터 정리하면 다음과 같다.

# 1. 정확히 일치하는 URI가 있으면 즉시 선택
location = /path {
    # /path 요청만 정확히 매칭
}

# 2. prefix 매칭 후 정규식 location 검사를 생략
location ^~ /path/ {
    # /path/ 로 시작하는 요청 매칭
    # 매칭되면 ~, ~* 정규식 location은 검사하지 않음
}

# 3. 대소문자를 구분하는 정규식 매칭
location ~ \.php$ {
    # .php 로 끝나는 요청 매칭
}

# 4. 대소문자를 구분하지 않는 정규식 매칭
location ~* \.(png|jpg|jpeg)$ {
    # .png, .jpg, .jpeg 확장자 요청 매칭
}

# 5. 일반 prefix 매칭
location /path/ {
    # /path/ 로 시작하는 요청 매칭
    # prefix 중 가장 긴 경로가 후보가 됨
}

# 6. 최후의 기본 location
location / {
    # 위 location에 매칭되지 않은 요청 처리
}

 

주의할 점은 위 순서가 설정 파일에 반드시 이렇게 작성해야 한다는 의미는 아니라는 것이다.
Nginx가 요청 URI를 보고 어떤 location을 최종 선택하는지 이해하기 위한 우선순위로 보면 된다.

 

조금 더 정확한 실제 매칭 흐름은 다음과 같다.

 

실제 매칭 흐름

1. 정확히 일치하는 location = 이 있는지 확인한다.
2. prefix location 중 가장 긴 경로를 찾는다.
3. 가장 긴 prefix location이 ^~ 이면 정규식 검사를 생략하고 해당 location을 사용한다.
4. ^~가 아니면 정규식 location을 설정 파일에 작성된 순서대로 검사한다.
5. 정규식 location이 매칭되면 해당 location을 사용한다.
6. 정규식이 하나도 매칭되지 않으면 처음에 찾았던 가장 긴 prefix location을 사용한다.

 

자세한 내용은 Nginx 공식 문서 - location을 참고하면 된다.

 

핵심은 이것이다.

일반 prefix location보다 정규식 location이 최종적으로 우선될 수 있다.
특정 경로를 정규식 location보다 우선 처리하고 싶다면 ^~를 사용해야 한다.

 

---

location이란?

location은 클라이언트가 요청한 URI에 따라 어떤 처리를 할지 결정하는 Nginx 설정 블록이다.

예를 들어 아래 설정은 /api/로 시작하는 요청을 백엔드 서버로 전달한다.

 

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

 

반면 아래 설정은 .png, .jpg, .jpeg로 끝나는 이미지 요청을 Nginx가 직접 처리하도록 한다.

 

location ~* \.(png|jpg|jpeg)$ {
    root /usr/share/nginx/html;
}

 

이처럼 location을 이용하면 요청 경로에 따라 백엔드로 프록시할 수도 있고,

Nginx가 직접 정적 파일을 내려줄 수도 있다.

문제는 location 설정이 많아질수록 요청이 어느 블록에 매칭되는지 헷갈리기 쉽다는 점이다.

 

 

---

location 문법 종류

Nginx에서 자주 사용하는 location 문법은 다음과 같다.

location = /exact {
    # 정확히 /exact 요청만 매칭
}

location /images/ {
    # /images/ 로 시작하는 요청 매칭
}

location ^~ /static/ {
    # /static/ 로 시작하면 정규식 location 검사 생략
}

location ~ \.php$ {
    # 대소문자 구분 정규식 매칭
}

location ~* \.(png|jpg|jpeg)$ {
    # 대소문자 구분 없는 정규식 매칭
}

location / {
    # 최후의 기본 location
}

각 문법을 표로 정리하면 다음과 같다.

 

문법	의미
location = /path	요청 URI가 정확히 일치할 때만 매칭
location /path/	해당 경로로 시작하는 요청 매칭
location ^~ /path/	해당 prefix가 매칭되면 정규식 location 검사 생략
location ~ regex	대소문자를 구분하는 정규식 매칭
location ~* regex	대소문자를 구분하지 않는 정규식 매칭
location /	어떤 location에도 걸리지 않을 때 사용하는 기본 location

 

---

일반 prefix location과 정규식 location

가장 헷갈리는 부분은 일반 prefix location과 정규식 location의 관계다.

아래 설정을 보자.

server {
    location /resource/data/ {
        proxy_pass http://backend;
    }

    location ~* \.(png|jpg|jpeg)$ {
        root /usr/share/nginx/html;
    }
}

 

이 상태에서 아래 요청이 들어온다고 가정해보자.

 

/resource/data/sample.jpg

 

겉으로 보면 /resource/data/로 시작하기 때문에 아래 location에 매칭될 것 같다.

 

location /resource/data/ {
    proxy_pass http://backend;
}

 

하지만 요청 URI가 .jpg로 끝나기 때문에 아래 정규식 location에도 매칭된다.

 

location ~* \.(png|jpg|jpeg)$ {
    root /usr/share/nginx/html;
}

 

Nginx는 먼저 prefix location 중 가장 긴 /resource/data/를 후보로 기억한다.
그다음 정규식 location을 검사한다.
그리고 정규식 location이 매칭되면 최종적으로 정규식 location을 사용한다.

즉, 위 요청은 /resource/data/ location이 아니라 이미지 정규식 location으로 처리될 수 있다.

---

^~를 사용해야 하는 경우

특정 경로는 정규식 location보다 무조건 먼저 처리하고 싶을 수 있다.

예를 들어 /resource/data/로 시작하는 요청은 파일 확장자가 .jpg든 .png든 무조건 백엔드로 보내고 싶다고 하자.

이럴 때는 ^~를 사용하면 된다.

 

location ^~ /resource/data/ {
    proxy_pass http://backend;
}

location ~* \.(png|jpg|jpeg)$ {
    root /usr/share/nginx/html;
}

 

이렇게 설정하면 아래 요청은 .jpg로 끝나더라도 정규식 location 검사를 하지 않는다.

/resource/data/sample.jpg

즉, 최종적으로 아래 location에 매칭된다.

location ^~ /resource/data/ {
    proxy_pass http://backend;
}

 

^~는 단순히 prefix 매칭을 의미하는 것이 아니라,

해당 prefix가 매칭되면 정규식 location 검사를 건너뛰게 만드는 역할을 한다.

 

그래서 특정 경로를 정규식보다 우선 처리하고 싶다면

일반 prefix location이 아니라 ^~ prefix location을 사용해야 한다.

 

---

예시

다음과 같은 설정이 있다고 가정해보자.

 

server {
    location = /health {
        return 200 "ok";
    }

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

    location ^~ /static/ {
        root /usr/share/nginx/html;
    }

    location ~* \.(png|jpg|jpeg)$ {
        root /usr/share/nginx/html/images;
    }

    location / {
        proxy_pass http://web-backend;
    }
}

 

각 요청은 다음과 같이 매칭된다.

 

요청 URI	매칭되는 location	이유
/health	location = /health	정확히 일치
/api/users	location /api/	/api/ prefix 매칭, 정규식 매칭 없음
/static/logo.png	location ^~ /static/	^~ 매칭으로 정규식 검사 생략
/upload/test.jpg	location ~* \.(png|jpg|jpeg)$	이미지 확장자 정규식 매칭
/board/list	location /	다른 location에 매칭되지 않아 기본 location 사용

 

여기서 중요한 예시는 /static/logo.png다.

이 요청은 .png로 끝나기 때문에 이미지 정규식 location에도 매칭될 수 있다.

 

하지만 /static/ location에 ^~가 붙어 있으므로

정규식 검사를 하지 않고 바로 /static/ location이 선택된다.

 

---

마무리

Nginx의 location 우선순위는 단순히 설정 파일에 작성된 순서대로 결정되지 않는다.

특히 일반 prefix location과 정규식 location이 함께 있을 때는 예상과 다른 location이 선택될 수 있다.

핵심은 다음과 같다.

 

핵심

1. 정확히 일치하는 location = 이 있는지 확인한다.
2. prefix location 중 가장 긴 경로를 찾는다.
3. 가장 긴 prefix location이 ^~ 이면 정규식 검사를 생략하고 해당 location을 사용한다.
4. ^~가 아니면 정규식 location을 설정 파일에 작성된 순서대로 검사한다.
5. 정규식 location이 매칭되면 해당 location을 사용한다.
6. 정규식이 하나도 매칭되지 않으면 처음에 찾았던 가장 긴 prefix location을 사용한다.