uri 지시문

원문 보기 위키 갱신 2026.10.03

uri 지시문 (URI 조작)

uri 지시문은 요청의 URI를 조작해요. 경로 접두사/접미사를 제거하거나, 전체 URI의 부분 문자열을 치환할 수 있어요.

출처: Caddy 공식 문서

본문

요청의 URI를 조작해요. 경로 접두사/접미사를 제거하거나 전체 URI의 부분 문자열을 치환할 수 있어요.

이 지시문은 rewrite와 다른 점이 있어요. uri는 URI를 차별적으로(differentiably) 바꾸는 반면, rewrite는 완전히 다른 값으로 재설정해요. rewrite는 내부 리다이렉트로 특별 취급되지만, uri는 그냥 또 하나의 미들웨어예요.

JSON 설정에서는 두 지시문 모두 같은 rewrite 핸들러를 만들어요. uri는 strip_path_prefix, strip_path_suffix, uri_substring, path_regexp, query 같은 필드를 설정하고, rewrite는 uri 필드를 설정해요.

문법 (Syntax)

여러 가지 다른 작업을 지원해요:

uri [<matcher>] strip_prefix <target>
uri [<matcher>] strip_suffix <target>
uri [<matcher>] replace      <target> <replacement> [<limit>]
uri [<matcher>] path_regexp  <target> <replacement>
uri [<matcher>] query        [-|+]<param> [<value>]
uri [<matcher>] query {
	<param> [<value>] [<replacement>]
	...
}

첫 번째(matcher가 아닌) 인자는 작업을 지정해요:

strip_prefix는 경로에서 접두사를 제거해요.
strip_suffix는 경로에서 접미사를 제거해요.
replace는 전체 URI에 걸쳐 부분 문자열 치환을 수행해요.
****은 접두사, 접미사 또는 검색 문자열/정규 표현식이에요. 접두사라면 경로는 항상 슬래시로 시작하므로 앞의 슬래시는 생략할 수 있어요.
****는 치환 문자열이에요. $name 또는 ${name} 문법, 또는 $1 같은 숫자 인덱스로 캡처 그룹을 쓸 수 있어요. 자세한 내용은 Go 문서를 참고해요. 치환 값이 ""이면 일치한 텍스트가 값에서 제거돼요.
****은 최대 치환 횟수에 대한 선택적 제한이에요.
path_regexp는 URI의 경로 부분에서 정규 표현식 치환을 수행해요.
query는 URI 쿼리에 대한 조작을 수행해요. 모드는 매개변수 이름 앞의 접두사나 인자의 개수에 따라 달라져요. 블록을 사용하면 여러 작업을 한 번에 지정할 수 있는데, 다음 순서로 그룹화되어 수행돼요: rename 🡒 set 🡒 append 🡒 replace 🡒 delete.
접두사가 없으면 쿼리에 주어진 값으로 매개변수를 설정해요.

예를 들어 uri query foo bar는 foo 매개변수 값을 bar로 설정해요.
-를 붙이면 쿼리에서 매개변수를 제거해요.

예를 들어 uri query -foo는 쿼리에서 foo 매개변수를 삭제해요.
+를 붙이면 주어진 값으로 매개변수를 쿼리에 추가해요. 같은 이름의 기존 매개변수를 덮어쓰지 않아요(덮어쓰려면 +를 생략해요).

예를 들어 uri query +foo bar는 쿼리에 foo=bar를 추가해요.
중위 연산자로 >를 쓰면 매개변수를 > 뒤의 값으로 이름을 바꿔요.

예를 들어 uri query foo>bar는 foo 매개변수를 bar로 이름을 바꿔요.
인자가 세 개면 쿼리 값 정규 표현식 치환이 수행돼요. 첫 인자는 쿼리 매개변수 이름, 두 번째는 검색 값, 세 번째는 치환이에요. 첫 인자(매개변수 이름)는 *일 수 있으며, 이 경우 모든 쿼리 매개변수에서 치환을 수행해요.

$name 또는 ${name} 문법, 또는 $1 같은 숫자 인덱스로 캡처 그룹을 쓸 수 있어요. 자세한 내용은 Go 문서를 참고해요. 치환 값이 ""이면 일치한 텍스트가 값에서 제거돼요.

예를 들어 uri query foo ^(ba)r $1z는 값이 bar로 시작하는 foo 매개변수 값을 바꿔 baz가 되게 해요.

URI 변형은 URI의 정규화된(unescaped) 형태에서 일어나요. 하지만 접두사나 접미사 패턴에 이스케이프 시퀀스를 사용해, 요청 경로의 해당 위치에서 그 리터럴 이스케이프만 매칭할 수 있어요. 예를 들어 uri strip_prefix /a/b는 /a/b/c와 /a%2Fb/c를 모두 /c로 재작성해요. 그리고 uri strip_prefix /a%2Fb는 /a%2Fb/c를 /c로 재작성하지만 /a/b/c는 매칭하지 않아요.

URI 경로는 수정 전에 디렉터리 트래버설 점을 정리해요. 또한 <target>도 여러 슬래시를 포함하지 않는 한 여러 슬래시(예: //)는 병합돼요.

접두사나 접미사를 제거한 후 남는 경로는 항상 /로 시작하고, 다시 디렉터리 트래버설 점을 정리해요. 예를 들어 uri strip_prefix /api는 /api를 /로, /apix를 /x로, /api../secret을 /secret으로 재작성해요.

비슷한 지시문 (Similar directives)

요청 URI를 조작할 수 있는 다른 지시문도 있어요.

rewrite는 값을 부분적으로 바꾸는 대신 전체 경로와 쿼리를 새 값으로 변경해요.
handle_path는 handle과 동일하지만, 핸들러를 실행하기 전에 요청에서 접두사를 제거해요. 많은 경우 uri strip_prefix 대신 사용해 설정 한 줄을 줄일 수 있어요.

예시 (Examples)

모든 요청 경로의 시작에서 /api를 제거해요:

uri strip_prefix /api

모든 요청 경로의 끝에서 .php를 제거해요:

uri strip_suffix .php

모든 요청 URI에서 "/docs/"를 "/v1/docs/"로 치환해요:

uri replace /docs/ /v1/docs/

요청 경로(쿼리는 아님)의 반복된 슬래시를 모두 하나의 슬래시로 접어요:

uri path_regexp /{2,} /

foo 쿼리 매개변수 값을 bar로 설정해요:

uri query foo bar

쿼리에서 foo 매개변수를 제거해요:

uri query -foo

foo 쿼리 매개변수를 bar로 이름을 바꿔요:

uri query foo>bar

쿼리에 bar 매개변수를 추가해요:

uri query +foo bar

값이 bar로 시작하는 foo 쿼리 매개변수 값을 baz로 치환해요:

uri query foo ^(ba)r $1z

여러 쿼리 작업을 한 번에 수행해요:

uri query {
	+foo bar
	-baz
	qux test
	renamethis>renamed
}

더 알아보기 (Learn more)

Caddy 공식 문서