Cloudflare Worker 오류, 원본 파일·줄 번호로 읽는 법

배포에 쓰는 Wrangler 버전과 소스맵부터 확인한다

Cloudflare Worker의 오류가 거대한 index.js 한 파일만 가리킨다면, 원본 TypeScript와 번들 사이를 연결하는 소스맵이 필요하다. 10월 20일 발표된 변경으로 Wrangler 4.150.0부터는 배포할 때 이 맵을 기본으로 생성하고 업로드한다.

대상 명령은 wrangler deploy, wrangler versions upload, wrangler preview다. 기존 설정에서 업로드를 명시적으로 꺼 두지 않았다면 새 기본값을 사용할 수 있다. 그보다 이전 Wrangler에서는 지원 버전을 확인하고 upload_source_maps: true를 지정해야 한다.

반영된 스택은 Workers Logs·실시간 로그·Tail Workers와 Workers Issues에서 확인할 수 있다. 다만 소스맵 업로드와 오류 수집 기능의 활성화는 별개다. 예를 들어 Issues는 따로 켜야 하며, 활성화 후 새 트래픽에서 발생한 실패를 처리한다.

직접 잡은 오류는 Error 객체를 넘긴다

애플리케이션이 예외를 잡아 대체 응답을 돌려준다면, 잡은 값을 console.error()에 넘겨야 오류 정보를 남길 수 있다. Cloudflare의 예외 로그 지원은 예외 객체의 이름·메시지·스택을 보존한다. 오류 문자열만 조합해 기록하는 것과 차이가 있다.

// 요청 처리 코드의 catch 블록
catch (error) {
  console.error("Request failed:", error);
  return new Response("Service unavailable", { status: 503 });
}

소스맵이 있다고 Worker 실행 중의 error.stack 값이 원본 위치로 바뀌지는 않는다. 역매핑은 실행이 끝난 뒤 처리된다. 런타임에서 스택 속성만 출력하고 그 문자열이 그대로라는 이유로 맵 업로드 실패를 단정할 수는 없다.

Issues로 확인한다면 잡힌 오류를 기록한 뒤 새 요청의 발생 건을 열어 스택을 살펴본다. 소스맵을 켜기 전의 과거 실패가 새로 수집되는 기능은 아니다.

배포 성공이 모든 소스맵의 업로드 성공을 뜻하지는 않는다

Vite나 별도 도구가 Worker를 번들링한다면, 그 도구가 소스맵도 만들어야 한다. Wrangler는 이미 만들어진 외부 맵을 업로드한다. Cloudflare Vite plugin 1.64.0부터는 Worker 환경의 외부 맵 생성이 기본이며, 다른 빌드 도구에서는 맵 파일과 이를 가리키는 sourceMappingURL을 유지해야 한다.

인라인 data: 맵이나 존재하지 않는 파일을 가리키는 참조는 건너뛰기 대상이다. 배포가 성공했는데도 위치가 맞지 않으면 외부 맵 생성과 참조 경로부터 점검해야 한다. 맵이 있어도 매핑하지 못하는 개별 스택 줄은 원래 표시로 남을 수 있다.

Worker 실행 부담 때문에 끌 필요는 없다

Cloudflare에 따르면 이 처리는 Worker의 CPU 시간·번들 크기·콜드 스타트에 영향을 주지 않는다. 오류 위치를 찾는 데 필요한 맵을 실행 비용 절감 목적으로 끌 이유는 없다.

업로드를 끄기로 했다면 도구에 맞는 설정을 쓴다. Wrangler에서는 upload_source_maps: false로 끈다. cf deploy는 빌드 결과의 소스맵을 모두 올리므로, cf 프로젝트에서는 Worker의 Vite 환경에 build.sourcemap: false를 지정해 생성을 꺼야 한다.

새 기본값은 Worker용 맵을 위한 것이며 Vite의 클라이언트 자산에 자동으로 맵을 추가하지 않는다. 별도 빌드에서는 서버 맵을 공개 자산 폴더 밖에 두고, 새 오류가 실제 원본 파일과 줄 번호를 가리키는지 확인하면 된다.