캐시된 콘텐츠 무효화

원문 보기 위키 갱신 2026.10.07

캐시된 콘텐츠 무효화 (Invalidate cached content)

무효화(Invalidation)는 캐시된 콘텐츠를 stale(오래된)로 표시해요. 다음 요청에서 Cloudflare는 오리진과 콘텐츠를 재검증해요. 오리진이 304 Not Modified로 응답하면 Cloudflare는 다시 다운로드하는 대신 캐시된 콘텐츠를 재사용해요.

출처: 문서

본문

무효화는 소프트 제거(soft purge)라고도 해요.

제거(purge)와 무효화 중 선택

제거와 무효화는 같은 선택자를 사용해요: URL, 캐시 태그, 호스트명, URL 접두사, 또는 전체. 일치하는 콘텐츠에 일어나는 일에서 차이가 있어요:

동작	제거(Purge)	무효화(Invalidate)
캐시된 콘텐츠	제거됨	유지되고 stale로 표시됨
다음 요청	오리진에서 전체 응답을 가져옴	오리진과 재검증함
stale 콘텐츠	제공되지 않음	재검증 중 또는 오리진 실패 시 제공될 수 있음
API 엔드포인트	`purge_cache`	`invalidate_cache`

캐시된 콘텐츠가 다시는 제공되어서는 안 될 때 제거를 사용해요. 제거하기 전에 오리진에서 콘텐츠를 업데이트하거나 제거해요. 그렇지 않으면 다음 요청이 오래된 버전을 다시 캐시할 수 있어요.

변경되지 않았을 수 있는 콘텐츠를 새로 고치려면 무효화를 사용해요. 예를 들어 캐시 태그를 공유하는 자산 그룹 같은 경우요.

무효화 작동 방식

무효화는 새 콘텐츠를 미리 가져오지 않아요. 대신 무효화된 콘텐츠에 대한 다음 요청이 재검증을 트리거해요.

재검증을 위해 Cloudflare는 오리진에 조건부 요청을 보내요. 요청은 오리진이 콘텐츠와 함께 보낸 ETag 또는 Last-Modified 헤더를 사용해요. 오리진의 응답이 다음에 일어날 일을 결정해요:

오리진이 304 Not Modified로 응답하면 Cloudflare는 캐시된 콘텐츠를 재사용하고 새 TTL(수명)을 설정해요.
오리진이 새 캐시 가능 콘텐츠를 반환하면 Cloudflare는 캐시된 콘텐츠를 교체해요.
오리진이 5xx 오류를 반환하거나 도달할 수 없으면 Cloudflare는 캐시된 콘텐츠를 stale로 제공할 수 있어요. 자세한 내용은 재검증 중 stale 콘텐츠를 참고해요.

무효화는 콘텐츠가 재사용된다는 것을 보장하지 않아요. 콘텐츠가 더 이상 캐시되지 않았거나, 오리진이 어느 헤더도 보내지 않았거나, 오리진이 조건부 요청을 지원하지 않으면 Cloudflare는 전체 응답을 가져와요.

304 Not Modified 응답은 Cache Response Rules가 설정한 캐시 태그를 새로 고치지 않아요. 오리진의 Cache-Tag 헤더의 캐시 태그는 오리진이 304 응답에 그 헤더를 포함한 경우에만 업데이트돼요. 그 외에 캐시 태그를 새로 고치려면 콘텐츠를 제거해요.

재검증 중 stale 콘텐츠

방문자가 Cloudflare가 재검증하는 동안 stale 콘텐츠를 받는지 여부는 캐시 설정과 오리진의 상태에 따라 달라져요:

stale-while-revalidate가 있으면 Cloudflare는 백그라운드에서 재검증하는 동안 stale 콘텐츠를 제공할 수 있어요.
stale-while-revalidate가 없으면 요청은 재검증이 완료될 때까지 기다려요.
오리진이 5xx 오류를 반환하거나 도달할 수 없으면, Cloudflare는 콘텐츠가 캐시에 있는 동안 stale 콘텐츠를 제공할 수 있어요. 이는 응답에 stale-if-error 지시어가 없어도 발생해요. 이를 제한하려면 응답에 stale-if-error를 설정해요. 막으려면 stale-if-error=0을 설정해요. Origin Cache Control이 활성화되면 must-revalidate, proxy-revalidate, s-maxage도 이를 막아요.

여전히 신선한 콘텐츠의 경우 stale-while-revalidate와 stale-if-error 기간은 만료되었을 때가 아니라 무효화할 때 시작돼요. 무효화는 이미 끝난 stale 기간을 늘리지 않아요.

예를 들어 만료 전에 다음 헤더가 있는 캐시된 응답을 무효화한다고 가정해요:

Cache-Control: public, max-age=3600, stale-while-revalidate=30
ETag: "product-v1"

Cloudflare는 재검증하는 동안 무효화 후 최대 30초까지 이 응답을 stale로 제공할 수 있어요. 이 응답에는 stale-if-error 지시어가 없어요. 오리진이 5xx 오류를 반환하거나 도달할 수 없으면 Cloudflare는 그 30초를 넘어서도 응답을 stale로 제공할 수 있어요. 응답이 캐시에 있는 동안 계속 그렇게 할 수 있어요.

다른 지시어와 Cache Rules 설정은 Cloudflare가 재검증하는 동안 stale 콘텐츠를 제공하는 것을 막을 수 있어요. 자세한 내용은 Revalidation을 참고해요.

Cache Reserve

무효화는 일치하는 콘텐츠를 Cache Reserve에 유지하며, 그곳에서 스토리지 비용이 계속 발생해요. 오리진이 304 Not Modified로 응답하면 Cloudflare는 오리진에서 다시 가져오는 대신 저장된 콘텐츠를 재사용해요. Cache Reserve에서 제공되는 콘텐츠는 stale-while-revalidate가 있어도 재검증 중에 stale로 제공되지 않아요.

제거와 비교해 무효화는 오리진 이그레스를 줄이지만 Cache Reserve 작업은 줄이지 않아요. 304 응답 후 저장된 콘텐츠를 업데이트하는 것은 Class A 작업이에요. URL로 무효화하면 요청을 보낼 때 저장된 콘텐츠도 업데이트되는데, 이것도 Class A 작업이에요. 자세한 내용은 Cache Reserve 작업을 참고해요.

제거는 일치하는 Cache Reserve 콘텐츠에 대해 캐시 미스를 강제해요. 자세한 내용은 Cache Reserve 제거 동작을 참고해요.

Workers Cache

대시보드 또는 invalidate_cache 엔드포인트의 무효화는 Workers Cache에 영향이 없어요. Workers Cache는 존이 아니라 Worker에 속해요. Worker의 캐시에서 응답을 제거하려면 Worker에서 ctx.cache.purge()를 호출해요.

시작하기 전에

콘텐츠를 무효화하기 전에 다음 요구 사항을 확인해요:

오리진 검증기: 캐시된 콘텐츠를 재사용하려면 오리진이 ETag 또는 Last-Modified 헤더를 반환하고 조건부 요청을 지원해야 해요.
권한: API 요청의 경우 존에 대한 Cache Purge 권한이 있는 토큰을 사용해요. 대시보드에서 무효화하려면 역할에 같은 권한이 포함되어야 해요.
속도 제한: 무효화 요청은 계정의 제거 한계에 포함돼요. 자세한 내용은 한계를 참고해요.

대시보드에서 무효화

Cloudflare 대시보드에서 Configuration 페이지로 이동해요. Configuration 열기 ↗
존이 Version Management를 사용하면 Global 탭을 선택해요. 그런 다음 Invalidate Cache에서 Choose the environment 아래에 환경을 선택해요. 대시보드가 환경을 미리 선택하므로 계속하기 전에 선택을 확인해요.
Invalidate Cache에서 Custom Invalidation을 선택해요. 존이 Version Management를 사용하면 이 버튼은 Select Content로 표시돼요.
Select content by 아래에서 URL, Hostname, Tag, 또는 Prefix를 선택하고 무효화할 값을 입력해요.
Invalidate를 선택해요.

모든 캐시된 콘텐츠를 무효화하려면 Invalidate Everything을 선택한 다음 확인해요.

존이 Version Management를 사용하면 Invalidate Everything은 사용할 수 없어요. 대신 Select content by 아래에서 Everything: All cached content를 선택한 다음 Invalidate를 선택해요. 대시보드는 이 옵션에 대해 확인을 요청하지 않아요. Production 환경에서 모든 것을 무효화하면 모든 환경에 적용돼요.

캐시 키가 방문자의 기기 유형이나 국가를 포함하면, Enterprise 존은 대시보드에서 URL의 해당 변형을 무효화할 수 있어요. URL을 선택한 다음 Advanced (custom cache keys) 아래에서 기기 유형이나 국가를 설정해요. 다른 캐시 키 헤더는 API를 사용해요.

API로 무효화

콘텐츠를 무효화하려면 invalidate_cache 엔드포인트에 POST 요청을 보내요:

https://api.cloudflare.com/client/v4/zones/{zone_id}/invalidate_cache

요청 본문은 해당 제거 요청과 같은 형식을 사용해요. 엔드포인트가 Cloudflare가 콘텐츠를 제거할지 무효화할지 결정해요.

다음 예시에서 $ZONE_ID를 존 ID로, $CLOUDFLARE_API_TOKEN을 API 토큰으로 바꿔요.

URL로 무효화

특정 URL을 무효화하려면 files에 나열해요:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUD...OKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "files": ["https://www.example.com/images/product.jpg"]
  }'

캐시 키가 요청 헤더를 포함하면 캐시된 변형을 식별하는 헤더 값을 포함해요:

{
	"files": [
		{
			"url": "https://www.example.com/images/product.jpg",
			"headers": {
				"CF-Device-Type": "desktop",
				"CF-IPCountry": "US"
			}
		}
	]
}

URL 일치 요구 사항은 Purge by single-file을 참고해요.

태그, 호스트명, 접두사, 또는 전체로 무효화

무효화하려는 콘텐츠와 일치하는 요청 본문을 사용해요:

선택자	요청 본문
캐시 태그	`{"tags":["product-images"]}`
호스트명	`{"hosts":["images.example.com"]}`
URL 접두사	`{"prefixes":["www.example.com/images"]}`
전체	`{"purge_everything":true}`

접두사는 URL scheme 없이 호스트명과 경로를 포함해요.

예를 들어 product-images로 태그된 모든 콘텐츠를 무효화하려면 이 요청을 보내요:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUD...OKEN" \
  --header "Content-Type: application/json" \
  --data '{"tags":["product-images"]}'

모든 것을 무효화하면 요청이 도착할 때 많은 양의 콘텐츠에 대한 재검증을 트리거할 수 있어요. 요구 사항을 충족하는 가장 작은 콘텐츠 집합을 선택해요.

환경에서 콘텐츠 무효화

비프로덕션 Version Management 환경의 경우 경로에 환경 ID를 포함해요:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/environments/$ENVIRONMENT_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUD...OKEN" \
  --header "Content-Type: application/json" \
  --data '{"tags":["product-images"]}'

환경 ID를 찾으려면 Purge zone versions via API를 참고해요. 프로덕션의 경우 존 수준 엔드포인트를 사용해요.

비프로덕션 환경에서 모든 것을 무효화하는 요청은 해당 환경에만 적용돼요. 존 수준 엔드포인트에 대한 같은 요청은 모든 환경에 적용돼요.

한계

무효화 요청은 제거 요청과 같은 계정 수준 제거 한계에 포함돼요. 적용되는 한계는 콘텐츠를 어떻게 선택하느냐에 따라 달라져요:

선택자	적용되는 한계
URL	Single-file purge limits
캐시 태그, 호스트명, URL 접두사, 또는 전체	Hostname, tag, prefix URL, and purge everything limits

제거와 무효화 요청은 같은 한계를 사용해요. 하나를 많이 사용하면 다른 하나에 사용할 수 있는 용량이 줄어요. 제거 한계처럼 이 한계는 계정별로 적용되며 같은 요금제의 존이 공유해요.

각 무효화 요청은 제거 요청과 같은 최대 항목 수를 포함할 수 있어요.

무효화 검증

무효화를 검증하려면 오리진이 ETag 또는 Last-Modified 헤더를 반환하는 캐시 가능한 테스트 URL을 사용해요. 테스트 중에는 오리진의 콘텐츠를 변경하지 않은 상태로 유지해요. 재검증을 직접 관찰하려면 테스트 응답에서 stale-while-revalidate를 생략하고 양수 TTL을 설정해요.

CF-Cache-Status 헤더가 HIT를 반환할 때까지 테스트 URL을 요청해요.
URL을 무효화해요.

URL을 다시 요청하고 응답 헤더를 확인해요:

curl --silent --show-error --dump-header - --output /dev/null \
  "https://www.example.com/images/product.jpg"

오리진 로그에서 Cloudflare가 조건부 요청을 보냈고 오리진이 304를 반환했는지 확인해요.

캐시된 콘텐츠에 대해 다음 결과를 기대해요:

결과	`CF-Cache-Status`
오리진이 콘텐츠가 변경되지 않았음을 확인	`REVALIDATED`, 그다음 `HIT`
오리진이 새 콘텐츠를 반환	`EXPIRED`, 그다음 `HIT`
오리진이 `ETag` 또는 `Last-Modified` 헤더를 보내지 않음	`EXPIRED`, 그다음 `HIT`
Cloudflare가 재검증 중에 stale 콘텐츠 제공	`UPDATING`, 그다음 `HIT`
오리진이 `5xx` 오류를 반환하거나 도달할 수 없음	`STALE`
콘텐츠가 더 이상 캐시되지 않음	`MISS`

오리진의 ETag 또는 Last-Modified 헤더가 없으면 Cloudflare가 재검증할 수 있는 것이 없으므로 전체 응답을 가져와요. 오리진이 304를 반환하면 Cloudflare는 캐시된 콘텐츠로 방문자에게 여전히 200 OK를 반환할 수 있어요.

Tiered Cache를 사용하면 하위 티어 데이터 센터가 상위 티어 데이터 센터와 재검증해요. 오리진이 304를 반환했어도 방문자가 EXPIRED나 MISS를 볼 수 있어요. 동시 요청도 관찰하는 상태에 영향을 줄 수 있어요. 재검증을 확인하려면 오리진 로그를 사용해요. 상태 정의는 Cloudflare cache responses를 참고해요.

무효화 문제 해결

오리진이 전체 응답을 반환

콘텐츠가 캐시되었고 선택자가 일치하는지 확인해요. 또한 오리진이 ETag 또는 Last-Modified 헤더를 반환하고 조건부 요청에 304 Not Modified로 응답하는지 확인해요.

Cloudflare가 아닌 오리진에 직접 보내는 요청에서 이 헤더들을 확인해요. 오리진이 어느 헤더도 보내지 않으면, 사용자 방향 스마트 재검증 덕분에 Cloudflare의 응답에 Last-Modified 헤더가 여전히 포함될 수 있어요. Cloudflare는 오리진과 재검증할 때 그 헤더를 사용하지 않아요.

콘텐츠가 캐시된 후에 제거된 경우, 제거가 우선하고 다음 요청이 전체 응답을 가져와요.

방문자가 stale 콘텐츠를 받음

Cloudflare는 재검증하는 동안 캐시된 응답에 stale-while-revalidate가 포함된 경우에만 stale 콘텐츠를 제공해요. Cache Rules의 Serve stale content while revalidating 설정으로 이를 끌 수 있어요.

오리진이 5xx 오류를 반환하거나 도달할 수 없으면, Cloudflare는 기본적으로 콘텐츠가 캐시에 있는 동안 무효화된 콘텐츠를 stale로 제공해요. Cache Rules 설정은 이를 바꾸지 않아요. 오리진이 실패할 때 Cloudflare가 stale 콘텐츠를 제공하는 시간을 제한하려면 오리진 응답에 stale-if-error를 설정해요. 막으려면 stale-if-error=0을 설정해요. Origin Cache Control이 활성화되면 must-revalidate, proxy-revalidate, s-maxage도 이를 막아요.

캐시된 콘텐츠 제공을 중단하려면 대신 제거(purge)해요.

더 알아보기 (Learn more)

무효화(소프트 제거)는 캐시된 콘텐츠를 제거하지 않고 stale로 표시해, 다음 요청 시 오리진과 재검증하도록 해요. 오리진이 304로 응답하면 캐시를 재사용해 오리진 트래픽을 아낄 수 있어요. 제거와 무효화의 선택 기준과 API·대시보드 사용법을 정리한 페이지예요.