Source Map — 번들된 코드를 원본으로 디버깅하는 원리

번들러가 코드를 압축하고 합치면 디버깅이 어려워집니다. Source Map은 번들된 코드와 원본 코드 사이의 "지도" 역할을 하여, 프로덕션에서도 원본 코드 기준으로 디버깅할 수 있게 해줍니다.

Source Map이 필요한 이유

// 원본 코드 (src/utils.ts)
export function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// 번들된 코드 (dist/bundle.js)
function n(e){return e.reduce((e,t)=>e+t.price*t.quantity,0)}
// 에러가 발생하면 "n at line 1, column 42" → 원본을 추적할 수 없음!

Source Map이 있으면 DevTools가 자동으로 src/utils.ts의 원래 위치를 보여줍니다.

Source Map 연결 방법

// 방법 1: 파일 끝에 주석으로 연결
//# sourceMappingURL=bundle.js.map

// 방법 2: HTTP 헤더로 연결
// SourceMap: /path/to/bundle.js.map

// 방법 3: 인라인 (Data URL) — 개발 환경에서 유용
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9u...

Source Map 파일 구조

JSON

{
  "version": 3,
  "file": "bundle.js",
  "sourceRoot": "",
  "sources": ["src/utils.ts", "src/main.ts"],
  "sourcesContent": ["원본 코드 내용..."],
  "names": ["calculateTotal", "items", "reduce"],
  "mappings": "AAAA,SAAS,cAAc..."
}

필드	설명
`version`	항상 3 (현재 버전)
`file`	번들된 파일 이름
`sources`	원본 파일 경로 목록
`sourcesContent`	원본 코드 내용 (선택)
`names`	원본에서 사용된 식별자
`mappings`	VLQ 인코딩된 매핑 데이터

빌드 도구별 설정

webpack

// webpack.config.js
module.exports = {
  // 개발
  devtool: "eval-source-map", // 빠르고 정확

  // 프로덕션
  devtool: "source-map",       // 별도 .map 파일 생성
  // 또는
  devtool: "hidden-source-map", // .map 파일 생성하지만 주석 없음
};

Vite

// vite.config.js
export default {
  build: {
    sourcemap: true,           // true | "inline" | "hidden"
  },
};

TypeScript

JSON

// tsconfig.json
{
  "compilerOptions": {
    "sourceMap": true,
    "declarationMap": true
  }
}

프로덕션 보안 전략

PLAINTEXT

1. hidden-source-map
   → .map 파일은 생성하지만 번들에 주석을 넣지 않음
   → 에러 모니터링 서비스(Sentry 등)에만 업로드

2. 접근 제한
   → .map 파일을 내부 네트워크에서만 접근 가능하게 설정
   → nginx: location ~* \.map$ { deny all; }

3. nosources-source-map
   → 스택 트레이스 매핑은 가능하지만 원본 코드는 포함하지 않음

Sentry에 Source Map 업로드

BASH

# Sentry CLI로 Source Map 업로드
sentry-cli releases files VERSION upload-sourcemaps ./dist \
  --url-prefix "~/static/js"

// 에러 모니터링에서 원본 코드 위치로 스택 트레이스 확인 가능
// bundle.js:1:42 → src/utils.ts:5:12

CSS Source Map

CSS

/* styles.css (컴파일된 CSS) */
.button { color: red; }
/*# sourceMappingURL=styles.css.map */

Sass, Less 같은 CSS 전처리기도 Source Map을 생성하여 원본 .scss 파일을 디버깅할 수 있습니다.

DevTools에서 활용

PLAINTEXT

1. Sources 탭에서 원본 파일 트리 확인
2. 원본 코드에 브레이크포인트 설정
3. 에러 스택 트레이스에서 원본 위치 클릭
4. Network 탭에서 .map 파일 로딩 확인
5. Settings → Preferences → "Enable JavaScript source maps" 확인

devtool 옵션 비교

옵션	빌드 속도	정확도	프로덕션 적합
`eval`	가장 빠름	낮음	X
`eval-source-map`	빠름	높음	X
`source-map`	느림	높음	O
`hidden-source-map`	느림	높음	O (권장)
`nosources-source-map`	느림	중간	O

**기억하기 **: Source Map은 번들된 코드의 위치를 원본 코드의 위치로 매핑하는 파일입니다. 개발 환경에서는 eval-source-map, 프로덕션에서는 hidden-source-map이 일반적인 선택입니다. 프로덕션에서는 Source Map을 공개하지 않고 Sentry 같은 서비스에만 업로드하는 것이 보안상 안전합니다.