Wrangler 4.150 소스맵 자동 업로드 끄기: Workers 배포 설정과 스택 트레이스 확인

어느 버전과 명령부터 기본값이 바뀌었나요?

Cloudflare의 공식 발표일은 2026년 10월 20일입니다. 적용 기준은 날짜 자체보다 실제 빌드 도구 버전입니다. 개발 PC가 업데이트됐어도 CI가 이전 lockfile로 설치한다면 동작이 다를 수 있습니다. 근거: 기본 소스맵 업로드 변경 공지

실행 경로	적용 버전·기본 동작	업로드를 원하지 않을 때
Wrangler deploy·versions upload·preview	4.150.0부터 기본 생성·업로드	Wrangler 설정에서 명시적으로 false
Cloudflare Vite 플러그인의 Worker 빌드	1.64.0부터 Worker 소스맵 기본 생성	해당 Vite 환경의 build.sourcemap 확인
사용자 정의 빌드	기존 외부 소스맵을 찾아 업로드	외부 빌드의 생성 설정과 업로드 설정을 따로 확인

프로젝트 폴더와 CI에서 실제 사용하는 버전을 각각 남기세요. pnpm 프로젝트라면 다음 명령으로 로컬 의존성을 확인할 수 있습니다.

pnpm exec wrangler --version
pnpm list wrangler @cloudflare/vite-plugin vite --depth 0

이 글의 로컬 시험에는 Node.js 24.20.0과 Wrangler 4.151.1을 사용했습니다. 4.150.0부터라는 적용 기준과 Vite 1.64.0의 기본값은 공식 문서로 확인했으며, 두 버전을 직접 실행한 결과로 바꾸어 설명하지 않습니다.

TOML·JSONC·CLI로 자동 업로드 끄기

계속 유지할 정책이라면 현재 사용하는 Wrangler 설정 파일에 명시하는 편이 관리하기 쉽습니다. 아래는 기존 설정에 합칠 항목입니다. Worker 이름·진입점 등 나머지 설정을 지우고 파일 전체를 교체하는 예시는 아닙니다. 근거: 소스맵 비활성화 방법

wrangler.toml

upload_source_maps = false

wrangler.jsonc

{
  "upload_source_maps": false
}

문자열 "false"가 아닌 불리언 false를 사용하세요. TOML에서는 의도한 설정 위치에 넣고, 기존 [env.production] 같은 테이블 아래에 무심코 붙이지 않도록 확인합니다. 여러 설정 파일을 동시에 추가하기보다 실제 배포 명령이 읽는 파일을 수정하세요.

한 번의 명령에서 끄려면 다음 옵션을 사용할 수 있습니다. 아래 두 명령은 실제 배포·버전 업로드 명령이므로 대상 Worker와 환경을 확인한 뒤 필요한 쪽을 선택해 실행합니다.

pnpm exec wrangler deploy --no-upload-source-maps
pnpm exec wrangler versions upload --no-upload-source-maps

preview도 기본값 변경 대상이지만, 공식 소스맵 문서가 비활성화 CLI 예시로 명시한 것은 deploy·versions upload입니다. preview까지 일관되게 관리하려면 설정 파일의 upload_source_maps: false를 확인하세요. CLI에 다른 값이 지정되거나 별도 --config·--env를 쓰는지도 배포 스크립트에서 점검합니다.

Vite에서는 Worker 환경의 생성 설정도 확인하세요

Wrangler가 직접 번들링하는 경로와 Vite가 먼저 빌드하는 경로는 다릅니다. Vite 프로젝트에서 소스맵 생성을 끄려면 Worker가 속한 환경의 build.sourcemap을 false로 설정합니다.

예를 들어 Worker 이름이 my-worker이고 기본 환경 이름 my_worker를 사용하는 프로젝트의 설정 형태는 다음과 같습니다. 기존 플러그인·프레임워크 설정에 맞춰 합치세요.

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  plugins: [cloudflare()],
  environments: {
    my_worker: {
      build: {
        sourcemap: false,
      },
    },
  },
});

플러그인은 기본적으로 Worker 이름의 하이픈을 밑줄로 바꾼 환경 이름을 사용합니다. 프레임워크가 Worker를 ssr 환경에 연결했다면 그 환경을 확인해야 합니다. my_worker라는 예시 이름을 그대로 붙이는 것만으로 자신의 Worker에 적용되지는 않습니다. 근거: Worker·SSR 환경 이름

공식 문서는 명시적인 upload_source_maps: false가 업로드를 비활성화한다고 안내합니다. 별도 cf deploy 경로는 빌드 출력의 소스맵을 업로드하므로 빌드 단계의 생성 설정을 확인해야 합니다. 이는 클라이언트 번들의 공개 소스맵과 Worker 소스맵을 같은 대상으로 보지 말아야 하는 이유이기도 합니다. 근거: Vite·사용자 정의 빌드와 비활성화 범위

로컬 dry-run으로 확인한 여섯 가지 조합

편집부는 같은 최소 Worker와 분리된 출력 폴더로 다음을 확인했습니다. 외부 소스맵 누락은 의도적으로 만든 시험 입력이며, 운영 장애 로그가 아닙니다. 모두 Wrangler 4.151.1의 로컬 dry-run 결과로 실제 Cloudflare 배포·업로드는 수행하지 않았습니다.

시험 조건	로컬 출력·종료 코드	확인한 범위
upload_source_maps 설정 생략	index.js.map 생성, 0	내장 번들링의 기본 생성
JSON 설정 false	index.js.map 없음, 0	해당 JSON 설정 적용
TOML 설정 false	index.js.map 없음, 0	해당 TOML 설정 적용
설정 true + CLI --no-upload-source-maps	index.js.map 없음, 0	해당 명령의 비활성화 옵션 적용
사전 빌드 JS가 없는 .map 참조, 설정 생략	dry-run 계속 진행, 0	해석할 수 없는 외부 맵의 기본 처리
같은 누락 입력 + 명시적 true	Invalid source map path 오류, 1	누락 맵의 엄격한 검증 실패

실제 로컬 명령·결과 JSON · 같은 시험 입력과 실행 안내 ZIP. 로컬 절대 경로와 ANSI 색상 코드는 결과 기록에서 정리했습니다. 용량 표시는 CLI의 준비물 안내이며 CPU·콜드 스타트 측정 결과가 아닙니다.

자신의 프로젝트에서 업로드 없이 번들 결과를 확인할 때는 다음처럼 실행할 수 있습니다. 출력 폴더는 시험마다 구분하고 실제 환경에 맞는 설정 파일을 지정하세요.

pnpm exec wrangler deploy --dry-run \
  --no-upload-source-maps \
  --outdir .wrangler/source-map-off-check

--dry-run은 컴파일·검사를 수행하고 Worker를 실제 업로드하지 않는 옵션입니다. 따라서 맵 파일 유무와 dry-run 성공만으로 원격 업로드 상태까지 확인했다고 판단할 수는 없습니다. 다른 빌드가 이미 만든 맵이 남아 있는 경우도 별도로 구분해야 합니다. 근거: Wrangler 명령과 dry-run

사용자 정의 빌드: 외부 .map과 참조 경로를 확인하세요

Vite·다른 빌드 도구가 먼저 Worker를 번들링한다면 해당 도구가 소스맵을 만들어야 합니다. Wrangler가 없는 원본 맵을 대신 복원해 주는 것은 아닙니다. 생성된 JavaScript와 외부 맵 파일을 함께 보존하고 sourceMappingURL이 실제 파일을 가리키는지 확인하세요.

1. 빌드가 외부 .map을 출력하는지 확인합니다. 빌드 성공과 맵 생성 성공을 구분합니다.
2. 생성 JS의 sourceMappingURL과 맵의 상대 경로가 맞는지 확인합니다.
3. 빌드 후 복사·압축·산출물 정리 단계에서 맵만 빠지지 않는지 확인합니다.
4. inline data: 맵인지 확인하고, 업로드 경로에 맞게 외부 맵을 생성하도록 조정합니다.
5. 서버용 맵이 공개 정적 자산 디렉터리로 복사되지 않도록 빌드 출력을 구분합니다.

기본값은 해석할 수 없는 맵을 건너뛰고 업로드를 계속하는 동작입니다. 맵 누락을 실패로 처리하려면 upload_source_maps = true를 명시할 수 있습니다. 이때의 ‘생략’과 ‘명시적 true’는 오류 처리까지 같은 의미가 아닙니다. 소스맵이 있어야 하는 조직은 배포 성공만 보지 말고 경고·맵 누락도 확인하세요. 근거: 외부 맵·해석 실패·명시적 true

원본 스택 트레이스는 배포 후 로그에서 따로 검증

소스맵은 Workers Logs·실시간 로그·Tail Workers·Workers Issues에서 원본 위치를 읽는 데 쓰입니다. Cloudflare는 Worker 실행이 끝난 뒤 맵을 적용한다고 설명합니다. Worker 내부에서 console.log(error.stack)을 출력하는 것과 로그 시스템에서 원본 파일·행으로 변환된 결과를 보는 것은 다릅니다. 근거: 스택 트레이스 적용 시점과 제한

직접 확인하려면 운영과 분리된 테스트 Worker에서 아래 순서로 비교하세요. 이 글에서는 원격 예외·변환 전후 스택을 확보하지 않았으므로 성공 사례나 재현 화면을 제시하지 않습니다.

1. 같은 코드·의존성·번들 설정으로 업로드 활성화·비활성화 버전을 준비합니다.
2. 각 배포의 Worker·버전 ID·커밋·시각과 업로드 설정을 기록합니다.
3. 테스트 전용 요청에서 의도한 미처리 예외를 발생시키고 요청 시각을 남깁니다.
4. 로그에서 오류가 해당 배포의 것인지 확인하고 원본 파일·함수·행 번호를 대조합니다.
5. 변환되지 않은 줄은 맵 존재·빌드 일치·참조 경로와 함께 조사합니다.

일부 줄만 변환될 수도 있습니다. 로그가 여전히 압축된 위치를 보여도 원인을 모두 기본값 문제로 돌리지 말고, 보고 있는 배포와 소스맵이 같은 빌드에 대응하는지 확인하세요. 소스 위치를 찾은 뒤 CPU·메모리 병목을 조사한다면 Cloudflare Workers CPU 프로파일링 안내로 이어서 볼 수 있습니다.

배포 설정과 검증 결과를 함께 남기세요

버전·설정·배포·스택 검증 기록 양식을 제공합니다. 원문 소스·토큰·실제 사용자 데이터를 넣기보다 필요한 파일명·버전·검증 상태를 기록하는 빈 양식입니다.

확인 시각 / 시간대 / 커밋:
Node·Wrangler·Vite·Cloudflare 플러그인 버전:
실제 명령 / --config·--env / Worker 환경 이름:
설정 생략·false·true / CLI 옵션:
내장 번들·사용자 정의 빌드 / 외부 .map·참조 확인:
dry-run 종료 코드 / 실제 업로드 수행 여부:
Worker·배포 버전 ID / 로그의 해당 버전 확인:
예외 위치 / 원본 파일·행 변환 여부:
실패·누락·미확인 / 다음 확인:

자주 묻는 질문

upload_source_maps를 설정하지 않아도 4.150부터 업로드되나요?

네. Wrangler 4.150.0부터 해당 배포 명령은 기본 생성·업로드합니다. 사용자 정의 빌드에서는 기존 외부 맵을 찾으며, 해석하지 못하는 맵을 기본적으로 건너뛴다는 점도 확인하세요.

소스맵이 번들 크기나 Workers 콜드 스타트에 영향을 주나요?

Cloudflare는 맵을 실행 후 스택 변환에 적용하므로 Worker의 CPU 시간·번들 크기·콜드 스타트에 영향을 주지 않는다고 설명합니다. 이 안내를 빌드·파일 생성·업로드 시간도 항상 같다는 보장으로 확대해석하지 마세요. 자체 성능 측정값은 아닙니다. 근거: 공식 발표의 성능 범위

사용자 정의 빌드에서 소스맵이 업로드되지 않으면 무엇을 확인하나요?

외부 .map 생성 여부, sourceMappingURL 경로, 산출물 복사 과정, inline data: 맵 여부를 확인합니다. 엄격히 실패시키려면 명시적 true를 검토하고, 배포 후 해당 버전의 로그까지 대조하세요.

확인 범위와 업데이트 기록

2026년 10월 22일 공식 변경 공지·소스맵·Wrangler 명령·Vite 환경 문서를 검수했습니다. 로컬 Wrangler 4.151.1의 여섯 dry-run에서 정상 종료 5건과 의도한 누락 맵 오류 1건을 확인했습니다. 실제 Cloudflare 업로드·스택 변환·Vite 빌드·성능은 미검증입니다.

Wrangler·Vite 플러그인의 기본값, 환경별 설정 처리, 맵 오류 처리나 로그 화면이 바뀌면 갱신합니다. 공식 분석과 로컬 확인을 실제 운영 배포 후기로 표현하지 않습니다.