Nginx location 지시어의 URI 경로 매칭 규칙과 우선순위

Nginx의 location 경로 매칭 규칙

Nginx의 경로 매칭은 location 지시어로 구현합니다. location은 요청 URI(요청 경로)를 기준으로 특정 처리 블록을 선택하는 핵심 모듈이며, 정적/동적 요청 분리, URL 재작성, 리버스 프록시 등을 구성할 때 사용됩니다.

location 매칭 규칙 분류

location은 정확 일치, 프리픽스 일치, 정규식 일치 등 여러 매칭 방식을 지원합니다.

정확 일치(=)

우선순위가 가장 높습니다. 요청 URI가 location 뒤의 문자열과 완전히 같을 때 해당 location 블록이 선택됩니다.

예시:

location = /robots.txt {
    # /robots.txt 요청 처리
}

요청 URI가 정확히 /robots.txt인 경우에만 위 location 블록이 사용됩니다.

최장 프리픽스 일치(^~)

두 번째 우선순위입니다. 요청 URI가 특정 location의 문자열로 시작하고, 그 문자열이 가장 긴 프리픽스이거나 ^~ 수정자가 사용된 경우 해당 블록이 선택됩니다. ^~ 수정자는 이후의 정규식 검색을 중단시킵니다.

예시:

location ^~ /service {
    return 701;
}

location ^~ /services {
    return 702;
}

location ^~ /service/v1 {
    return 703;
}

location ~ /service {
    return 704;
}

요청 /service는 701과 704 조건을 모두 만족하지만, ^~가 정규식보다 우선하므로 701이 반환됩니다.

요청 /services는 701과 702 조건을 만족하며, 더 긴 프리픽스인 /services가 선택되어 702가 반환됩니다.

요청 /service/v1은 가장 긴 프리픽스인 /service/v1과 일치하므로 703이 반환됩니다.

정규식 일치(~, ~*)

세 번째 우선순위입니다. 정규식 매칭은 더 복잡한 URI 패턴을 정의할 수 있습니다. ~는 대소문자를 구분하는 정규식 일치이고, ~*는 대소문자를 구분하지 않는 정규식 일치입니다.

Nginx는 설정 파일에 작성된 순서대로 정규식 location 블록을 검사하며, 첫 번째로 일치하는 블록을 선택합니다. 따라서 정규식 location의 순서가 중요합니다.

예시:

location ~ \.(jpeg|webp|avif)$ {
    # .jpeg, .webp, .avif로 끝나는 요청 처리(대소문자 구분)
}

location ~* \.(JPEG|WEBP|AVIF)$ {
    # .JPEG, .WEBP, .AVIF로 끝나는 요청 처리(대소문자 구분 안 함)
}

요청 /media/banner.webp는 첫 번째 location 블록과 일치합니다. 대소문자가 다른 확장자 요청은 두 번째 location 블록에서 매칭될 수 있습니다.

일반 프리픽스 일치(수정자 없음)

네 번째 우선순위입니다. 수정자 없는 프리픽스 location 중에서는 가장 긴 URI 프리픽스가 선택됩니다. 동일한 길이의 프리픽스가 여러 개 존재하는 경우에는 설정 순서가 영향을 줄 수 있지만, 일반적으로 더 구체적인 긴 프리픽스가 우선합니다.

예시:

location /catalog {
    return 801;
}

location /catalog/items {
    return 802;
}

요청 /catalog/items는 801과 802 조건을 모두 만족하지만, 더 긴 프리픽스인 /catalog/items가 선택되어 802가 반환됩니다.

기본 일치(/)

우선순위가 가장 낮습니다. 요청 URI가 어떤 특정 location 블록과도 일치하지 않으면 기본 location 블록이 사용됩니다. 일반적으로 수정자가 없는 location / 블록이 기본 location 역할을 합니다.

예시:

location / {
    # 다른 location과 일치하지 않는 모든 요청 처리
}

우선순위 정리

  • 정확 일치(=)

  • 최장 프리픽스 일치(^~), 이후 정규식 검색 중단

  • 정규식 일치(~, ~*), 설정 순서대로 검사

  • 일반 프리픽스 일치(수정자 없음), 가장 긴 프리픽스 우선

  • 기본 일치(/)

주의 사항

  • 정규식 매칭과 순서: 정규식 location은 설정 파일에 정의된 순서대로 검사되므로 순서가 중요합니다.

  • proxy_pass 경로 치환: proxy_pass 설정 시 location 뒤 URI에 슬래시(/)가 포함되는지에 따라 요청 전달 경로가 달라질 수 있습니다. 일반적으로 location과 proxy_pass 모두 슬래시를 붙이거나 모두 붙이지 않는 것이 좋습니다.

  • 성능 최적화: 정확 일치를 앞에 배치하면 불필요한 정규식 검사를 줄여 Nginx 처리 효율을 높일 수 있습니다.

태그: nginx location URI-matching Regex prefix-matching

11월 1일 20:43에 게시됨