handle 지시문

원문 보기 위키 갱신 2026.10.03

handle 지시문 (그룹 처리)

handle 지시문은 같은 중첩 단계의 다른 handle 블록과 상호 배타적으로 지시문 그룹을 평가해요. 여러 handle 지시문이 연속으로 나오면, 처음으로 일치하는 handle 블록만 평가돼요.

출처: Caddy 공식 문서

본문

같은 중첩 단계의 다른 handle 블록과 상호 배타적으로 지시문 그룹을 평가해요.

즉, 여러 handle 지시문이 연속으로 나오면 처음으로 일치하는 handle 블록만 평가돼요. matcher가 없는 handle은 폴백(fallback) 라우트처럼 동작해요.

handle 지시문은 그 matcher에 따라 지시문 정렬 알고리즘으로 정렬돼요. handle_path 지시문은 경로 matcher가 있는 handle과 같은 우선순위로 정렬되는 특수한 경우예요.

필요하면 handle 블록을 중첩할 수 있어요. handle 블록 안에는 HTTP 핸들러 지시문만 사용할 수 있어요.

문법 (Syntax)

handle [<matcher>] {
	<directives...>
}

**<directives...>**는 한 줄에 하나씩 나열하는 HTTP 핸들러 지시문 또는 지시문 블록 목록이에요. handle 블록 밖에서 쓰는 것과 동일해요.

비슷한 지시문 (Similar directives)

HTTP 핸들러 지시문을 감쌀 수 있는 다른 지시문도 있는데, 전달하려는 동작에 따라 각각 용도가 달라요:

handle_path는 handle과 동일하지만, 핸들러를 실행하기 전에 요청에서 접두사를 제거해요.
handle_errors는 handle과 비슷하지만, 요청 처리 중 Caddy가 에러를 만났을 때만 호출돼요.
route는 handle처럼 다른 지시문을 감싸는데 두 가지 차이가 있어요:
1. route 블록은 서로 상호 배타적이지 않아요.
2. route 안의 지시문은 재정렬되지 않아서, 필요하면 더 많은 제어가 가능해요.

예시 (Examples)

/foo/ 요청은 정적 파일 서버로, 그 외 요청은 리버스 프록시로 처리해요:

example.com {
	handle /foo/* {
		file_server
	}

	handle {
		reverse_proxy 127.0.0.1:8080
	}
}

같은 사이트에서 handle과 handle_path를 섞어 쓸 수 있고, 여전히 서로 상호 배타적이에요:

example.com {
	handle_path /foo/* {
		# 경로에서 "/foo" 접두사가 제거됨
	}

	handle /bar/* {
		# 경로는 여전히 "/bar"를 유지함
	}
}

handle 블록을 중첩해 더 복잡한 라우팅 로직을 만들 수 있어요:

example.com {
	handle /foo* {
		handle /foo/bar* {
			# 이 블록은 /foo/bar 아래 경로만 매칭함
		}

		handle {
			# 이 블록은 /foo/ 아래의 나머지를 매칭함
		}
	}

	handle {
		# 이 블록은 나머지 전부를 매칭함(폴백 역할)
	}
}

더 알아보기 (Learn more)

Caddy 공식 문서