Workers 모듈 레지스트리 11월 17일 기본 전환: compatibility_date를 올리기 전 점검할 것

모듈 로딩 경로를 비교한 뒤 전환하는 과정을 표현한 생성 이미지. 실제 시스템 구성도는 아니다.

Cloudflare는 November 2, 2026 공지에서, 호환성 날짜가 November 17, 2026 이상(당일 포함)인 JavaScript Workers에 새 모듈 레지스트리를 기본 적용한다고 예고했다. 레지스트리는 Worker의 모듈을 찾아 읽는 런타임 구성 요소다. 기존 Worker가 11월 17일이 됐다는 이유만으로 일괄 전환되는 것은 아니다. 현재 동작은 호환성 날짜나 관련 플래그를 바꾸기 전까지 유지되며, Python Workers는 기존 레지스트리를 계속 사용한다. 공식 전환 예고

이번 변경은 npm 의존성을 많이 쓰는 API, SSR 앱, AI 에이전트용 Worker에서 점검할 가치가 있다. 소스가 같아도 모듈을 불러오는 방식이나 번들 결과에 따라 실행 경로가 달라질 수 있기 때문이다. 지금 할 일은 급히 운영 날짜를 올리는 것이 아니라, 변경을 따로 시험하고 실제 배포물의 계약을 확인하는 것이다.

1. 달력 날짜와 compatibility_date를 구분한다

기존 설정에서 날짜를 유지하고 new_module_registry를 추가하면 새 레지스트리를 미리 시험할 수 있다. 다음은 설정 병합 예시다. 실제 프로젝트의 날짜·플래그·바인딩을 그대로 보존하고 새 플래그만 추가한다.

나중에 호환성 날짜를 2026-11-17 이상으로 올리면서 기존 레지스트리를 유지해야 한다면 legacy_module_registry가 탈출구다. 두 플래그를 함께 넣어 동작을 추측하지 말고, 어떤 레지스트리를 시험하는지 설정에 명확히 남긴다. 플래그 전환 방법

호환성 날짜를 올리면 그 날짜까지의 다른 기본 변경도 함께 적용된다. 따라서 ‘새 레지스트리만 켠 시험’과 ‘날짜를 올린 시험’을 분리하면 원인 파악이 쉬워진다. 프레임워크가 설정 파일을 생성한다면 원본 파일 외에 실제 배포에 사용되는 설정도 확인해야 한다. 호환성 날짜 문서 · 생성된 Wrangler 설정

2. require()가 돌려주는 값부터 확인한다

Node.js 호환성을 사용하는 Workers에서는 새 레지스트리의 require()로 ES 모듈을 읽을 수 있다. 반환값은 보통 모듈 네임스페이스이며, "module.exports"라는 이름으로 값을 내보내면 그 값을 반환한다. Workers 내장 node: 모듈은 default export를 반환하고, 기존 번들의 __cjsUnwrapDefault도 default export를 풀어 반환한다. 따라서 반환값을 예전과 같다고 가정하지 말고 실제 로딩 경로를 확인해야 한다. 새 레지스트리의 호환성 규칙

우선 다음 형태의 코드를 찾는다.

• 반환값을 곧바로 함수처럼 호출하는 코드

• .default를 무조건 꺼내는 래퍼

• 패키지 업그레이드에 따라 CommonJS와 ESM 진입점이 바뀌는 의존성

• 서버 시작 시 한 번만 실행되는 초기화 코드와 드물게 실행되는 동적 로딩 경로

검사는 require() 호출 성공 여부에서 끝내지 않는다. 실제로 필요한 함수나 객체가 어떤 위치에 있는지, 그 함수를 호출한 결과까지 비교한다. 값이 예상과 다르다고 모든 의존성에 일괄적으로 .default를 붙이는 수정도 피하자.

불러오는 모듈 또는 그 의존성 중 하나라도 최상위 await를 사용하면 require()는 실패한다. 해당 모듈 그래프의 평가가 이미 끝났어도 예외가 되지 않는다. 공식 문서는 이런 경우 동적 import()를 사용하도록 안내한다. 이때 호출부 역시 Promise를 기다리는 흐름으로 바뀌므로 초기화 시점과 오류 처리까지 점검해야 한다. 최상위 await 제한

3. 모듈 경로와 속성도 실행 계약이다

새 레지스트리는 import 속성을 검증한다. 알 수 없는 키, 지원하지 않는 타입, 가져오는 모듈과 맞지 않는 타입은 오류가 된다. 예전 런타임에서 무시되던 입력에 기대고 있지 않은지, 생성 코드와 의존성의 import까지 확인하자.

또한 URL 방식으로 모듈을 구분하므로 같은 소스라도 쿼리 문자열이나 fragment가 다르면 별도 모듈 인스턴스가 된다. ‘캐시를 갱신하려고 경로 뒤에 값을 붙인 코드’가 있다면 모듈 수준 상태와 초기화가 중복되지 않는지 살펴볼 이유가 생긴다. 검증·모듈 식별 규칙

실무에서는 다음 두 질문을 테스트에 넣을 수 있다.

1. 같은 논리 모듈을 다른 경로 문자열로 읽는 곳이 있는가?

2. 그 모듈의 초기화가 여러 번 실행되면 연결·타이머·캐시·계측에 어떤 변화가 생기는가?

이 질문은 모든 앱에서 문제가 발생한다는 뜻이 아니다. 경로를 만드는 코드가 있는 프로젝트부터 확인하면 된다.

4. 소스 검사 다음에는 배포될 번들을 본다

Wrangler는 기본적으로 esbuild로 코드를 번들링한다. 런타임에 도달하기 전에 import와 import.meta가 변환될 수 있으므로, 소스에서 본 모듈 구조가 그대로 유지된다고 가정하면 안 된다. 다음 공식 dry-run 방식을 이용하면 업로드할 코드를 로컬 출력 폴더에서 살펴볼 수 있다. 출력 경로는 기존 산출물과 겹치지 않게 고른다. Wrangler 번들링 문서

이미 사용하는 프로젝트와 고정된 의존성 환경에서 실행한다. 이 명령은 실제 배포를 수행하지 않지만, 프로젝트에 사용자 정의 빌드 명령이 있다면 그 명령의 동작은 먼저 확인해야 한다.

번들에서 볼 항목은 다음과 같다.

• CJS와 ESM 사이의 래퍼 및 실제 반환값 처리

• import.meta가 남아 있는지, 빌드 과정에서 치환됐는지

• 동적 import 대상 파일이 업로드 목록에 포함되는지

• JSON·텍스트·Wasm 같은 별도 모듈의 처리 방식

• 원본 설정과 빌드 도구가 생성한 설정의 차이

import.meta.resolve()가 URL을 만들었다고 파일의 존재나 로딩 성공까지 확인된 것은 아니다. 새 레지스트리가 임의 인터넷 URL에서 모듈을 내려받거나 npm 패키지를 설치해 주는 것도 아니다. 공식 예제의 경계 · 런타임 로딩과 번들링

문제를 피하려고 곧바로 번들링을 끄는 것은 권장하지 않는다. --no-bundle은 Wrangler의 처리 일부를 건너뛰므로, 이미 다른 도구가 배포 가능한 산출물을 만드는 경우에 검토할 선택지다. 번들링 비활성화 주의사항

5. 변경을 한 번에 하나씩 비교한다

다음 순서는 공식 동작을 바탕으로 한 검증 제안이다.

1. 기준선 저장: 코드 커밋, lockfile, Wrangler 버전, 유효 설정과 기존 테스트 결과를 기록한다.

2. 레지스트리만 변경: 날짜와 의존성을 유지한 채 새 플래그로 로컬 시작·빌드·핵심 요청 경로를 확인한다.

3. 로딩 경계 검사: 초기화, 동적 import, 드문 오류 경로와 반환값 형태를 확인한다. Node.js에서의 성공만으로 Workers 검증을 대신하지 않는다.

4. 배포 조건 확인: 승인된 시험 환경에서 실제 번들·바인딩 조합을 검증한 다음 운영 전환을 판단한다.

5. 날짜 갱신은 별도 검토: 날짜를 올리는 단계에서는 레지스트리 외에 함께 활성화되는 변경도 회귀 검사한다.

6. 복구 기준 준비: 실패 시 되돌릴 코드·의존성·설정을 묶어 둔다. 레지스트리 플래그 하나만 되돌리는 것으로 다른 날짜 변경까지 취소되지는 않는다.

판정 기준은 ‘새 플래그로 빌드가 끝났는가’보다 구체적이어야 한다. 예를 들어 SSR 앱이면 서버 렌더링과 지연 로딩 경로, API라면 처음 호출될 때의 초기화와 오류 응답을 포함한다. 응답 코드뿐 아니라 출력 형식과 예외 로그도 기준선과 비교한다.

배포 전 체크리스트

• 현재 날짜·플래그와 실제 배포 설정을 확인했는가?

• require() 반환값과 전이 의존성의 최상위 await를 점검했는가?

• import 속성과 경로의 쿼리·fragment 사용을 확인했는가?

• 소스뿐 아니라 최종 번들과 동적 로딩 대상도 확인했는가?

• 레지스트리 전환과 날짜 갱신을 나눠 시험했는가?

• 되돌릴 코드·의존성·설정을 확보했는가?

11월 17일은 기존 Worker 전체의 강제 이관 기한이 아니다. 새 기본값을 받아들이는 배포에서 무엇이 달라지는지 확인하는 기준점으로 보는 편이 정확하다. 이번 점검을 배포 기록에 남기면 이후 호환성 날짜를 올릴 때도 변화의 원인을 좁히기 쉬워진다.

이 글은 November 6, 2026 KST 기준 공식 공개 자료를 바탕으로 작성했다. 예시 명령의 실제 실행, 유료 API 호출 또는 운영 Worker 배포는 수행하지 않았다. 소개한 점검 절차는 각 프로젝트에서 실행·검증해야 할 항목이다.