map 지시문

원문 보기 위키 갱신 2026.10.03

map 지시문 (입력값에 따른 placeholder 매핑)

map 지시문은 입력값에 따라 커스텀 placeholder의 값을 설정해요. 소스 값을 맵의 입력 쪽과 비교해 일치하는 항목의 출력 값을 각 목적지에 적용해요.

출처: Caddy 공식 문서

본문

입력값에 따라 커스텀 placeholder의 값을 설정해요.

소스 값을 맵의 입력 쪽과 비교하고, 일치하는 항목이 있으면 출력 값을 각 목적지에 적용해요. 목적지는 placeholder 이름이 돼요. 각 목적지에 대한 기본 출력 값도 지정할 수 있어요.

매핑된 placeholder는 사용되기 전까지 평가되지 않아서, 매우 큰 매핑에서도 이 지시문은 상당히 효율적이에요.

문법 (Syntax)

map [<matcher>] <source> <destinations...> {
	[~]<input> <outputs...>
	default    <defaults...>
}

****는 스위치할 입력 값이에요. 보통 placeholder예요.
**<destinations...>**는 출력 값을 담을 placeholder들이에요. 각 목적지는 {my_placeholder} 같은 단일 placeholder여야 하고 다른 것은 안 돼요.
****은 매칭할 입력 값이에요. ~로 시작하면 정규 표현식으로 처리돼요.

각 입력은 한 번만 사용할 수 있어요. 같은 텍스트의 리터럴 입력과 정규 표현식 입력(예: /foo와 ~/foo)은 서로 다른 입력으로 취급돼요.
**<outputs...>**는 관련 placeholder에 저장할 하나 이상의 출력 값이에요. 첫 번째 출력은 첫 번째 목적지에, 두 번째 출력은 두 번째 목적지에 쓰여요.

특수한 경우로, Caddyfile 파서는 리터럴 하이픈(-)인 출력을 null/nil 값으로 취급해요. 주어진 입력에 대해 그 특정 출력은 기본 값으로 폴백하고 싶지만, 다른 출력에는 기본이 아닌 값을 쓰고 싶을 때 유용해요.

출력은 가능하면 타입 변환돼요. true와 false는 불리언 타입으로, 숫자 값은 정수 또는 실수로 변환돼요. 이 변환을 피하려면 출력을 따옴표로 감싸면 문자열로 유지돼요.

각 매핑의 출력 수는 목적지 수를 넘을 수 없어요. 다만 편의상 목적지보다 출력이 적을 수 있으며, 빠진 출력은 암시적으로 채워져요.

입력으로 정규 표현식을 썼다면 ${group}으로 캡처 그룹을 참조할 수 있어요. 여기서 group은 표현식의 캡처 그룹 이름 또는 숫자예요. 캡처 그룹 0은 전체 정규식 일치, 1은 첫 번째 캡처 그룹, 2는 두 번째 캡처 그룹 등이에요.
****는 일치하는 입력이 없을 때 저장할 출력 값을 지정해요.

예시 (Examples)

다음 예시는 이 지시문의 대부분 측면을 보여줘요:

map {host}                {my_placeholder}  {magic_number} {
	example.com           "some value"      3
	foo.example.com       "another value"
	~(.*)\.example\.com$  "${1} subdomain"  5

	~.*\.net$             -                 7
	~.*\.xyz$             -                 15

	default               "unknown domain"  42
}

이 지시문은 {host} 값, 즉 요청의 도메인 이름에 따라 스위치해요.

요청이 example.com이면 {my_placeholder}를 some value로, {magic_number}를 3으로 설정해요.
그렇지 않고 요청이 foo.example.com이면 {my_placeholder}를 another value로 설정하고, {magic_number}는 기본값 42를 쓰게 해요.
그렇지 않고 요청이 example.com의 아무 서브도메인이면 {my_placeholder}를 첫 번째 정규식 캡처 그룹 값(즉 전체 서브도메인)을 담은 문자열로 설정하고, {magic_number}를 5로 설정해요.
그렇지 않고 요청 호스트가 .net이나 .xyz로 끝나면 {magic_number}만 각각 7이나 15로 설정해요. {my_placeholder}는 설정하지 않아요.
그 외(다른 모든 호스트)에는 기본 값이 적용돼요. {my_placeholder}는 unknown domain으로, {magic_number}는 42로 설정돼요.

더 알아보기 (Learn more)

Caddy 공식 문서