Builderlog ·빌더로그 편집팀 ·운영 시스템 ·빌더로그 필드 매뉴얼 202 ·2026.09.12 ·6 분 읽기

Cloudflare Workers 호환성 날짜 변경: 바꾸기 전 체크리스트

#cloudflare workers#호환성 날짜#런타임 업그레이드#호환성 플래그#배포 체크리스트

Cloudflare Workers 호환성 날짜 변경은 하위 호환성을 깨뜨릴 수 있는 런타임 동작을 선택하므로, 다음 배포 전에 검토해야 해요. Cloudflare에 따르면 날짜와 플래그가 동작 변경을 결정해요. 따라서 "최신" 날짜로 바꾸는 건 대가 없는 업그레이드가 아니에요.

세 줄 답변: 날짜는 버전 번호가 아니라 스위치예요. 날짜마다 런타임 동작 묶음이 정해져 있어, 날짜를 앞당기면 Worker 동작이 조용히 달라질 수 있어요. Cloudflare는 현재 날짜와 목표 날짜 사이의 호환성 플래그를 검토하고 영향을 받는 동작을 테스트한 뒤 배포하라고 안내해요. 공식 문서는 검토 절차를 설명할 뿐, 검증된 성능·안정성 수치나 개선을 보장하지 않아요.

자동완성에 “Cloudflare Workers compatibility date”가 계속 보여요. 사람들이 설정법뿐 아니라 날짜의 역할을 찾는다는 뜻으로 보고, 이 글에서 그 빈틈을 다뤄요.

직접 실행 기록

실행 명령: npx --yes wrangler --version
환경: Darwin 25.5.0 / python 3.12.13
실행 시각: 2026-09-12T09:45:54+09:00
종료 코드: 0

4.129.0

아래는 위 환경에서 실제로 실행한 결과를 그대로 붙인 것이다. 다른 환경에서는 다르게 나올 수 있다.

검증한 실행

명령: npx --yes wrangler --version
환경: Darwin 25.5.0 / python 3.12.13
실행 시각: 2026-09-12T09:45:54+09:00
종료 코드: 0

4.129.0

아래 블록은 해당 실행에서 캡처한 출력을 그대로 붙인 거예요. 환경이 다르면 결과도 달라질 수 있어요.

”일단 날짜부터 갱신”하면 안 되는 이유

날짜가 적힌 설정은 오늘로 바꾸고 싶어져요. robots.txt의 사이트맵 타임스탬프라면 괜찮지만, 호환성 날짜는 위험해요. Cloudflare 문서는 이 설정이 런타임 동작 변경 묶음을 선택하며, 일부 변경은 코드의 기존 전제를 깨뜨린다고 명시해요.

호환성 날짜는 패치 수준이 아니라 동작 변경 묶음이에요. 일부 변경은 코드를 망가뜨릴 수 있어요.

공식 페이지(developers.cloudflare.com/workers/configuration/compatibility-dates/)는 선택의 대가를 설명해요. 새 런타임 동작을 얻는 대신 이전 날짜와 새 날짜 사이의 변경도 받아들여요. 속도 향상, 비용 절감, 오류 감소를 약속하지 않아요. 동작이 달라진다는 것이며, 내 Worker에 도움이 될지 해가 될지는 직접 확인해야 해요.

설정을 건드리기 전에 확인할 것

wrangler.toml의 compatibility_date나 대시보드의 해당 설정을 바꾸기 전에, Cloudflare가 구분하는 세 가지를 나눠 확인해요.

현재 설치 조건 — 현재 날짜와, 해당 날짜의 기본 동작을 덮어쓰는 플래그가 있는지 확인해요.
이전·새 날짜 사이의 동작 변경 — 버전 상승이 아니라, 현재 날짜부터 목표 날짜 사이에 적용된 구체적인 런타임 변경 목록이에요.
배포 시점 — 저장 즉시가 아니라 다음 배포에 적용돼요. 스테이징과 프로덕션의 적용 순서에 중요해요.

변경 기록에 복사해 쓸 수 있는 판단 표예요.

단계	질문	확인 위치
1. 기준선	현재 운영 중인 호환성 날짜는?	`wrangler.toml` / 대시보드 설정
2. 변경분	이전·새 날짜 사이에 바뀌는 동작은?	호환성 날짜 페이지에 연결된 Cloudflare 호환성 플래그 참조
3. 플래그	기본값을 덮어쓰도록 직접 설정한 플래그는?	같은 설정 파일
4. 영향받는 코드	Worker가 변경된 API나 동작을 사용하는가?	변경 목록과 코드를 직접 대조
5. 테스트	프로덕션 외 환경에서 영향받는 동작을 테스트했는가?	자체 스테이징 환경
6. 배포	다음 배포에 새 날짜가 적용되는가?	Cloudflare 확인: 다음 배포에만 적용

문서를 생략하는 지름길이 아니라, 배포 전에 문서의 필요한 부분을 읽었는지 확인하는 표예요.

하지 않을 주장

이 Worker 런타임 변경의 전후를 통제된 조건에서 테스트하지 않았고, 했다고 꾸미지 않을 거예요. 이 글은 문서 기반 판단 자료이며 프로덕션 실험 기록이 아니에요. “업그레이드했더니 X가 좋아졌다”는 결론은 Cloudflare 자료가 뒷받침하지 않으며, 저도 주장하지 않아요.

출처가 뒷받침하는 건 테스트 원칙이에요. 플래그 검토, 코드의 사용 범위 식별, 해당 범위 테스트, 배포 순서예요. 결과가 아닌 절차에 관한 주장이에요. 많은 업그레이드 가이드가 2단계(변경분)를 건너뛰고 1단계(기준선)에서 6단계(배포)로 넘어가요. 하위 호환성을 깨는 변경이 모르는 사이 프로덕션에 들어가는 방식이에요.

새 호환성 날짜는 저장한 순간이 아니라 다음 배포에 적용돼요.

실패와 한계를 분명히 밝히기

검증된 설치 성공률, 특정 Worker를 망가뜨린 구체적인 플래그 목록, 검토 소요 시간은 없어요. 오늘 확인할 수 있는 근거에 없는 수치를 만들지 않을 거예요. 여러 Workers API를 사용하는 큰 코드베이스라면 4단계 수동 검토가 단일 엔드포인트 Worker보다 오래 걸릴 거예요. 측정된 시간이 아니라 논리적 추론이에요.

또 다른 한계는 이 체크리스트가 Cloudflare 표준 Workers 런타임을 전제한다는 점이에요. Next.js on Workers처럼 프레임워크를 얹었다면 그 프레임워크의 호환성 전제도 별도로 확인해야 해요. 호환성 날짜 페이지만으로 다룰 수 없으며, 모든 구성에서 검증하지도 않았어요.

변경분 확인을 건너뛴 체크리스트는 클릭만 늘어난 배포 버튼이에요.

최종 판단 틀

“호환성 날짜를 바꿔야 할까”에 대한 솔직한 답은 먼저 변경분을 확인하고, 다음으로 테스트한 뒤, 배포하세요예요. 날짜가 오래돼 보여서 바꾸지 마세요. 필요한 동작을 식별하고, 현재와 목표 사이의 변경을 확인하고, 영향받는 범위를 테스트했기 때문에 바꾸세요.

위 표를 운영 노트에 저장하세요. compatibility_date를 건드릴 때마다 여섯 행을 순서대로 확인해요. 오늘 날짜를 입력하고 배포하는 것보다 느리지만, 업그레이드와 장애를 가르는 차이예요.

별도로, 설치 가이드의 연속성을 위해 이 시리즈에서 계속 언급하는 한국 사주 웹앱 소스 라이선스 구성을 다룬다면 같은 원칙이 적용돼요. 날짜 변경이 안전하다고 가정하기 전에 현재 런타임 설정을 확인해요. 판매 권유가 아닌 범위 설명이에요. 라이선스 페이지의 설치 요구사항도 독립적으로 확인해야 해요.

근거	뒷받침하는 내용	한계
Google 자동완성, 검토일 2026-09-12	현재 추천 영역에 정확한 검색어 `Cloudflare Workers compatibility date`가 나타났어요	검색어 노출 신호일 뿐, 검색량·순위·구매 의도·성과 근거가 아니에요
편집용 가상 예시	본문에서 다룬 설정 항목이나 판단 경로를 보여줘요	측정된 프로덕션 결과가 아니에요