try_files 지시문

try_files 지시문 (존재하는 파일로 재작성)

try_files 지시문은 요청 URI 경로를 사이트 루트에 실제로 존재하는 파일 목록 중 첫 번째 파일로 재작성해요. 조건에 맞는 파일이 없으면 재작성하지 않아요.

출처: Caddy 공식 문서

본문

요청 URI 경로를 사이트 루트에 존재하는 나열된 파일 중 첫 번째 파일로 재작성해요. 조건에 맞는 파일이 없으면 재작성하지 않아요.

문법 (Syntax)

try_files <files...> {
	policy first_exist|first_exist_fallback|smallest_size|largest_size|most_recently_modified
}

• **<files...>**는 시도할 파일 목록이에요. URI 경로는 존재하는 첫 번째 파일로 재작성돼요.

  디렉터리를 매칭하려면 경로 끝에 슬래시 /를 붙여요. 모든 파일 경로는 사이트 root를 기준으로 하며, glob 패턴도 확장돼요.

  각 인자는 쿼리 문자열을 포함할 수도 있는데, 그 파일에 일치하면 쿼리 문자열도 함께 바뀌어요.

  try_policy가 first_exist(기본값)이면 목록의 마지막 항목은 =로 시작하는 숫자(예: =404)일 수 있어요. 이는 폴백으로, 해당 코드로 에러를 발생시켜요. 이 에러는 handle_errors로 잡아 처리할 수 있어요.

• policy는 파일 목록 중에서 파일을 고르는 정책이에요.

  기본값: first_exist

확장 형태 (Expanded form)

try_files 지시문은 기본적으로 다음의 단축 형태예요:

@try_files file <files...>
rewrite @try_files {file_match.relative}

이 지시문은 matcher 토큰을 받지 않아요. 더 복잡한 매칭 로직이 필요하면 위의 확장 형태를 기반으로 사용해요.

file matcher에 대한 자세한 내용은 여기를 참고해요.

예시 (Examples)

요청이 어떤 정적 파일에도 맞지 않으면 PHP index/router 진입점으로 재작성해요:

try_files {path} /index.php

같은 동작이지만 원래 경로를 쿼리 문자열에 추가해요(일부 레거시 PHP 앱에서 필요):

try_files {path} /index.php?{query}&p={path}

같은 동작이지만 디렉터리도 매칭해요:

try_files {path} {path}/ /index.php?{query}&p={path}

파일이나 디렉터리가 존재하면 재작성하고, 없으면 404 에러를 발생시켜요(handle_errors로 잡아 처리할 수 있어요):

try_files {path} {path}/ =404

정적 파일의 가장 최근에 배포된 버전을 선택해요(예: index.html 요청 시 index.be331df.html을 서빙):

try_files {file.base}.*.{file.ext} {
	policy most_recently_modified
}

더 알아보기 (Learn more)

• Caddy 공식 문서