nginx proxy_pass에 URI를 붙이냐 안 붙이냐로 백엔드 경로가 달라지는 이유

리버스 프록시 설정하다가 백엔드에서 404가 뜨는데 location은 분명히 맞는 상황, 대부분 proxy_pass의 URI 유무 때문입니다. 공식 문서 규칙은 딱 두 가지입니다. proxy_pass에 URI(끝의 / 포함)가 있으면 location에 매칭된 부분이 그 URI로 치환되고, URI 없이 호스트만 적으면 클라이언트가 보낸 요청 URI가 그대로 넘어갑니다.

아래 두 설정을 비교해봅시다. 같은 /api/users 요청인데 백엔드가 받는 경로가 달라집니다. 위는 /users, 아래는 /api/users로 갑니다. 흔히 말하는 트레일링 슬래시 함정이 바로 이 치환 규칙입니다.

# location 매칭분(/api/)이 /로 치환 -> 백엔드는 /users 받음
location /api/ {
    proxy_pass http://127.0.0.1:8080/;
}

# URI 없음 -> 요청 URI 그대로 -> 백엔드는 /api/users 받음
location /api/ {
    proxy_pass http://127.0.0.1:8080;
}

단, location이 정규식이거나 named location, 또는 rewrite ... break로 URI를 바꾼 경우, upstream 이름 뒤에 변수를 쓴 경우에는 치환 규칙을 적용할 수 없어서 proxy_pass에 URI를 쓸 수 없습니다. 이때는 호스트만 적고 rewrite로 경로를 맞추세요. 무작정 슬래시 붙이지 말고 백엔드 access log에서 실제 들어온 경로부터 확인합시다.

🔗 https://nginx.org/en/docs/http/ngx_http_proxy_module.html