Bun 은 pnpm 의 접근 방식과 유사한 엄격한 의존성 격리를 생성하는 격리된 설치 (isolated installs) 라는 대체 패키지 설치 전략을 제공합니다. 이 모드는 팬텀 의존성을 방지하고 재현 가능하고 결정론적인 빌드를 보장합니다.

이것은 새로운 워크스페이스/모노레포 프로젝트 (lockfile 에서 configVersion = 1) 의 기본 설치 전략입니다. 기존 프로젝트는 명시적으로 구성하지 않는 한 hoisted 설치를 계속 사용합니다.

격리된 설치란?

격리된 설치는 패키지가 명시적으로 선언된 의존성에만 액세스할 수 있는 비 hoisted 의존성 구조를 생성합니다. 이는 의존성이 공유 node_modules 디렉토리로 평평해지는 npm 과 Yarn 이 사용하는 기존 "hoisted" 설치 전략과 다릅니다.

주요 이점

• 팬텀 의존성 방지 — 패키지가 선언하지 않은 의존성을 실수로 가져올 수 없음
• 결정론적 해결 — 다른 설치 내용에 관계없이 동일한 의존성 트리
• 모노레포에 적합 — 워크스페이스 격리로 패키지 간 교차 오염 방지
• 재현 가능한 빌드 — 환경 전반에서 더 예측 가능한 해결 동작

격리된 설치 사용

명령줄

--linker 플래그를 사용하여 설치 전략을 지정합니다.

# 격리된 설치 사용
bun install --linker isolated

# 기존 hoisted 설치 사용
bun install --linker hoisted

구성 파일

bunfig.toml 또는 $HOME/.bunfig.toml 에 기본 링커 전략을 설정합니다.

[install]
linker = "isolated"

기본 동작

기본 링커 전략은 프로젝트의 lockfile configVersion 에 따라 달라집니다.

configVersion	workspaces 사용?	기본 Linker
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

새 프로젝트: 기본적으로 configVersion = 1. 워크스페이스에서 v1 은 기본적으로 격리된 링커를 사용하고 그렇지 않으면 hoisted 링커를 사용합니다.

기존 Bun 프로젝트 (v1.3.2 이전에 생성): 기존 lockfile 에 아직 버전이 없는 경우 bun install 을 실행할 때 Bun 이 configVersion = 0 으로 설정하여 이전 hoisted 링커 기본값을 유지합니다.

다른 패키지 관리자에서 마이그레이션:

• pnpm 에서: configVersion = 1 (워크스페이스에서 격리된 설치 사용)
• npm 또는 yarn 에서: configVersion = 0 (hoisted 설치 사용)

--linker 플래그를 명시적으로 지정하거나 구성 파일에서 설정하여 기본 동작을 재정의할 수 있습니다.

격리된 설치 작동 방식

디렉토리 구조

의존성을 hoisting 하는 대신 격리된 설치는 2 계층 구조를 생성합니다.

node_modules/
├── .bun/                          # 중앙 패키지 저장소
│   ├── package@1.0.0/             # 버전별 패키지 설치
│   │   └── node_modules/
│   │       └── package/           # 실제 패키지 파일
│   ├── @scope+package@2.1.0/      # 스코프된 패키지 (/를 + 로 대체)
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # 심볼릭 링크

해결 알고리즘

1. 중앙 저장소 — 모든 패키지는 node_modules/.bun/package@version/ 디렉토리에 설치됩니다.
2. 심볼릭 링크 — 최상위 node_modules 에는 중앙 저장소를 가리키는 심볼릭 링크가 포함됩니다.
3. 피어 해결 — 복잡한 피어 의존성은 특수한 디렉토리 이름을 생성합니다.
4. 중복 제거 — 동일한 패키지 ID 와 피어 의존성 세트를 가진 패키지는 공유됩니다.

워크스페이스 처리

모노레포에서 워크스페이스 의존성은 특별하게 처리됩니다.

• 워크스페이스 패키지 — 저장소가 아닌 소스 디렉토리로 직접 심볼릭 링크됨
• 워크스페이스 의존성 — 모노레포의 다른 워크스페이스 패키지에 액세스할 수 있음
• 외부 의존성 — 적절한 격리와 함께 격리된 저장소에 설치됨

hoisted 설치와 비교

측면	Hoisted (npm/Yarn)	Isolated (pnpm 스타일)
의존성 액세스	패키지는 모든 hoisted 의존성 액세스 가능	패키지는 선언된 의존성만 볼 수 있음
팬텀 의존성	❌ 가능	✅ 방지
디스크 사용량	✅ 낮음 (공유 설치)	✅ 유사함 (심볼릭 링크 사용)
결정론	❌ 덜 결정론적	✅ 더 결정론적
Node.js 호환성	✅ 표준 동작	✅ 심볼릭 링크를 통해 호환
적합한 용도	단일 프로젝트, 레거시 코드	모노레포, 엄격한 의존성 관리

고급 기능

피어 의존성 처리

격리된 설치는 정교한 해결을 통해 피어 의존성을 처리합니다.

# 피어 의존성이 있는 패키지는 특수 경로 생성
node_modules/.bun/package@1.0.0_react@18.2.0/

디렉토리 이름은 패키지 버전과 피어 의존성 버전을 모두 인코딩하여 각 고유한 조합이 자체 설치를 갖도록 보장합니다.

백엔드 전략

Bun 은 성능을 위해 다양한 파일 작업 전략을 사용합니다.

• Clonefile (macOS) — 최대 효율을 위한 copy-on-write 파일시스템 복제
• Hardlink (Linux/Windows) — 디스크 공간 절약을 위한 하드링크
• Copyfile (폴백) — 다른 방법을 사용할 수 없을 때 전체 파일 복사

격리된 설치 디버깅

설치 프로세스를 이해하려면 상세 로깅을 활성화합니다.

bun install --linker isolated --verbose

이것은 다음을 표시합니다.

• 저장소 항목 생성
• 심볼릭 링크 작업
• 피어 의존성 해결
• 중복 제거 결정

문제 해결

호환성 문제

일부 패키지는 다음과 같은 이유로 격리된 설치에서 제대로 작동하지 않을 수 있습니다.

• 하드코딩된 경로 — 평평한 node_modules 구조를 가정하는 패키지
• 동적 가져오기 — Node.js 해결을 따르지 않는 런타임 가져오기
• 빌드 도구 — node_modules 를 직접 스캔하는 도구

문제가 발생하면 다음을 수행할 수 있습니다.

1. 특정 프로젝트에 대해 hoisted 모드로 전환:

   bun install --linker hoisted

2. 격리된 설치 지원을 개선하기 위해 호환성 문제 보고

성능 고려 사항

• 설치 시간 — 심볼릭 링크 작업으로 인해 약간 더 느릴 수 있음
• 디스크 사용량 — hoisted 와 유사함 (파일 복사 대신 심볼릭 링크 사용)
• 메모리 사용량 — 복잡한 피어 해결로 인해 설치 중 더 높음

마이그레이션 가이드

npm/Yarn 에서

# 기존 node_modules 및 lockfile 제거
rm -rf node_modules package-lock.json yarn.lock

# 격리된 링커로 설치
bun install --linker isolated

pnpm 에서

격리된 설치는 개념적으로 pnpm 과 유사하므로 마이그레이션이 간단해야 합니다.

# pnpm 파일 제거
rm -rf node_modules pnpm-lock.yaml

# Bun 의 격리된 링커로 설치
bun install --linker isolated

주요 차이점은 Bun 이 node_modules 에 심볼릭 링크를 사용하는 반면 pnpm 은 심볼릭 링크가 있는 전역 저장소를 사용한다는 점입니다.

격리된 설치 사용 시기

격리된 설치를 사용하는 경우:

• 여러 패키지가 있는 모노레포에서 작업할 때
• 엄격한 의존성 관리가 필요할 때
• 팬텀 의존성 방지가 중요할 때
• 결정론적 의존성이 필요한 라이브러리 빌드

hoisted 설치를 사용하는 경우:

• 평평한 node_modules 구조를 가정하는 레거시 코드로 작업할 때
• 기존 빌드 도구와의 호환성이 필요할 때
• 심볼릭 링크가 잘 지원되지 않는 환경에서 작업할 때
• 더 간단한 기존 npm 동작을 선호할 때

관련 문서

• 패키지 관리자 > 워크스페이스 — 모노레포 워크스페이스 관리
• 패키지 관리자 > Lockfile — Bun 의 lockfile 형식 이해
• CLI > install — 전체 bun install 명령 참조