import 지시문

원문 보기 위키 갱신 2026.10.03

import 지시문 (스니펫/파일 포함)

import 지시문은 스니펫이나 파일을 포함해서, 이 지시문을 그 스니펫이나 파일의 내용으로 대체해요. 구조가 파싱되기 전에 평가되는 특수한 지시문이라 Caddyfile 어디에나 쓸 수 있어요.

출처: Caddy 공식 문서

본문

스니펫이나 파일을 포함해서, 이 지시문을 그 스니펫이나 파일의 내용으로 대체해요.

이 지시문은 특별한 경우예요. 구조가 파싱되기 전에 평가되며 Caddyfile 어디에나 나타날 수 있어요.

문법 (Syntax)

import <pattern> [<args...>] [{block}]

****은 포함할 파일 이름, glob 패턴 또는 스니펫 이름이에요. 그 내용이 이 줄을 대체해, 마치 그 파일의 내용이 처음부터 여기 있었던 것처럼 돼요.

특정 파일을 찾을 수 없으면 에러예요. 다만 빈 glob 패턴은 에러가 아니에요.

특정 파일을 import할 때 그 파일이 비어 있으면 경고가 발생해요.

패턴이 파일 이름이나 glob이면 항상 import가 나타나는 파일을 기준으로 해요.

glob 패턴 *을 마지막 경로 세그먼트로 쓰면 숨김 파일(즉 .로 시작하는 파일)은 무시돼요. 숨김 파일을 import하려면 .*을 마지막 세그먼트로 사용해요.
**<args...>**는 import된 토큰에 전달할 선택적 인자 목록이에요. 이 placeholder는 특별한 경우로, 런타임이 아니라 Caddyfile 파싱 시점에 평가돼요. Go의 slice 문법과 비슷하게 다양한 형태로 쓸 수 있어요:
- {args[n]} — n은 0부터 시작하는 매개변수의 위치 인덱스
- {args[:]} — 모든 인자가 삽입됨
- {args[:m]} — m 이전의 인자들이 삽입됨
- {args[n:]} — n부터 시작하는 인자들이 삽입됨
- {args[n:m]} — n과 m 사이 범위의 인자들이 삽입됨
여러 토큰을 삽입하는 형태의 경우 placeholder는 반드시 자체적으로 토큰이어야 해요. 다른 토큰의 일부가 될 수 없어요. 즉 양쪽에 공백이 있어야 하고 따옴표 안에 있을 수 없어요.

v2.7.0 이전에는 문법이 {args.N}이었는데, 이 형태는 위의 더 유연한 문법을 위해 폐기됐어요.

⚠️ 실험적(Experimental) | v2.9.x+
**{block}**은 import된 토큰에 전달할 선택적 블록이에요. 이 placeholder는 특별한 경우로, 런타임이 아니라 Caddyfile 파싱 시점에 재귀적으로 평가돼요. 두 가지 형태로 쓸 수 있어요:
- {block} — 제공된 블록 전체 내용이 placeholder를 대체함
- {blocks.key} — key는 제공된 블록 안 매개변수의 첫 토큰

예시 (Examples)

인접한 sites-enabled 폴더의 모든 파일을 import해요(숨김 파일 제외):

import sites-enabled/*

import 인자를 사용해 CORS 헤더를 설정하는 스니펫을 import해요:

(cors) {
	@origin header Origin {args[0]}
	header @origin Access-Control-Allow-Origin "{args[0]}"
	header @origin Access-Control-Allow-Methods "OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE"
}

example.com {
	import cors example.com
}

프록시 업스트림 목록을 인자로 받는 스니펫을 import해요:

(https-proxy) {
	reverse_proxy {args[:]} {
		transport http {
			tls
		}
	}
}

example.com {
	import https-proxy 10.0.0.1 10.0.0.2 10.0.0.3
}

첫 번째 인자로 접두사 재작성 규칙이 있는 프록시를 만드는 스니펫을 import해요:

(proxy-rewrite) {
	rewrite {args[0]}{uri}
	reverse_proxy {args[1:]}
}

example.com {
	import proxy-rewrite /api 10.0.0.1 10.0.0.2 10.0.0.3
}

⚠️ 실험적(Experimental) | v2.9.x+

설정 가능한 "hello world" 메시지와 콘텐츠 타입으로 응답하는 스니펫을 import해요:

(hello-world) {
	header {
		Cache-Control max-age=3600
		X-Foo bar
		{blocks.content_type}
	}
	respond /hello-world 200 {
		{blocks.body}
	}
}

example.com {
	import hello-world {
		content_type {
			Content-Type text/html
		}
		body {
			body "<h1>hello world</h1>"
		}
	}
}

리버스 프록시를 위한 확장 가능한 옵션을 제공하는 스니펫을 import해요:

(extendable-proxy) {
	reverse_proxy {
		{blocks.proxy_target}
		{blocks.proxy_options}
	}
}

example.com {
	import extendable-proxy {
		proxy_target {
			to 10.0.0.1
		}
		proxy_options {
			transport http {
				tls
			}
		}
	}
}

사전 로드된 미들웨어와 함께 임의의 지시문 집합을 서빙하는 스니펫을 import해요:

(instrumented-route) {
	header {
		Alt-Svc `h3="0.0.0.0:443"; ma=2592000`
	}
	tracing {
		span args[0]
	}
	{block}
}

example.com {
	import instrumented-route example-com {
		respond "OK"
	}
}

더 알아보기 (Learn more)

Caddy 공식 문서