nginx location 매칭 우선순위: 접두사, ^~, 정규식이 헷갈릴 때

nginx에서 location을 여러 개 걸어두면 어떤 블록이 잡히는지 헷갈릴 때가 많습니다. 순서대로 위에서 아래로 매칭되는 게 아니라 규칙이 정해져 있습니다. 공식 문서 기준으로 nginx는 먼저 접두사(prefix) location들을 모두 검사해 가장 긴 접두사를 기억합니다. 그다음 정규식(~, ~*)을 설정 파일에 나온 순서대로 검사하고, 첫 번째로 매칭되는 정규식이 채택됩니다. 정규식이 하나도 안 맞으면 아까 기억해둔 가장 긴 접두사 location을 씁니다. 즉 정규식이 존재하면 접두사보다 우선합니다.

예외가 두 개 있습니다. =(정확히 일치)는 매칭되는 즉시 검색을 끝내고 그 블록을 씁니다. ^~는 그 접두사가 가장 긴 매칭이면 뒤에 오는 정규식 검사를 건너뛰게 만듭니다. 정적 파일 경로를 정규식 handler보다 먼저 확정하고 싶을 때 ^~를 씁니다.

location = / { [ A ] }
location / { [ B ] }
location /documents/ { [ C ] }
location ^~ /images/ { [ D ] }
location ~* \.(gif|jpg|jpeg)$ { [ E ] }

# /                       -> A  (정확히 일치)
# /index.html             -> B  (가장 긴 접두사 /)
# /documents/document.html-> C  (가장 긴 접두사 /documents/)
# /images/1.gif           -> D  (^~ 가 정규식 검사를 건너뜀)
# /documents/1.jpg        -> E  (접두사 기억 후 정규식이 우선)

주의할 점은 /documents/1.jpg가 C가 아니라 E로 간다는 것입니다. 접두사 /documents/가 가장 길게 잡혀도 ^~가 없으면 정규식 검사가 계속 돌아가고, 매칭되는 정규식이 있으면 그쪽이 채택됩니다. 접두사로 확정하고 싶으면 ^~를 붙여야 합니다.

🔗 https://nginx.org/en/docs/http/ngx_http_core_module.html#location