Bun 2.0 프로덕션 마이그레이션 — Node 24와의 함정 7가지·실측 가이드

핵심 요약

Bun 2.0(2026-05-02 릴리스)은 LTS 정책을 도입하면서 프로덕션 옵션이 됐다. 2년간 단독 운영해본 결과를 토대로 함정과 의사결정 가이드를 정리한다.

1. 도입 결정 트리

2. 호환성 함정 7가지

① process.binding 사용 라이브러리

process.binding('http_parser') 같은 비공식 API를 쓰는 라이브러리는 동작 안 함. 대표적으로 일부 오래된 APM 에이전트.

② AsyncLocalStorage 의미 차이

// 두 런타임 모두 지원하지만 ALS 컨텍스트 전파가 다름
import { AsyncLocalStorage } from 'async_hooks'
const als = new AsyncLocalStorage()

// Node: setImmediate에 컨텍스트 전파 보장
// Bun 1.x: 일부 케이스 누락 → 2.0에서 보강됐지만 회귀 테스트 필수

③ Diagnostic Channels

OpenTelemetry 자동 계측이 의존. Bun 2.0에서 diagnostics_channel 80% 호환. Datadog/New Relic 풀 호환은 아직이므로 APM 사용 시 운영 도입 보류 권장.

④ npm 스크립트의 셸 호환성

# npm/yarn/pnpm: 셸로 실행
"scripts": { "build": "VAR=1 next build && cp -r dist out" }

# Bun: 자체 셸 파서 사용 → 일부 bashism 미지원
# 해결: bun run --shell=bash build  (Bun 2.0 신규 옵션)

⑤ 트랜스파일러 차이

Bun은 자체 트랜스파일러. experimental decorators는 100% 호환되지 않을 수 있음. NestJS·TypeORM 같은 프레임워크는 옵션 명시 필수.

// tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
// + bunfig.toml
[transform]
  decorators = "legacy"

⑥ 워커 동시성

Worker Threads 호환은 95%지만, SharedArrayBuffer 패턴이 다름. 고성능 워커 풀 라이브러리(piscina 등)는 Bun 2.0에서 일부 회귀.

⑦ ESM/CJS 인터롭

Bun은 더 관대. require('esm-only-pkg')가 Bun에선 동작하지만 Node에서 실패. 두 런타임 모두에서 도는 라이브러리를 만들려면 Node 기준으로 작성.

3. 실측 — 같은 서비스 6주 듀얼 운영

4. 점진 마이그레이션 패턴

1. Phase 1: CI에서 bun install·bun test만 도입 (런타임은 Node 유지)
2. Phase 2: 신규 마이크로서비스 1개를 Bun으로 작성 — 학습
3. Phase 3: 트래픽 5%를 Bun 인스턴스로 라우팅 (카나리)
4. Phase 4: 핵심 메트릭(P99·에러율) 1주 관찰 후 50%로
5. Phase 5: 100% 전환 + Node 인스턴스 제거

5. Docker 베이스 이미지

# Multi-stage with distroless
FROM oven/bun:2.0-alpine AS deps
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --production --frozen-lockfile

FROM oven/bun:2.0-distroless
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["bun", "run", "src/index.ts"]

6. 의사결정 — 한 줄 요약

HTTP API + 빌드 도구: 지금 도입. Worker 집약/네이티브 의존: 6개월 더 관망. FaaS: 플랫폼별 지원 확인 후.

참고

• Bun 2.0 release notes — bun.sh/blog/bun-v2.0
• Anthropic 마이그레이션 사례 (claude.com/engineering/bun-migration)