Bun bietet eine alternative Paketinstallationsstrategie namens isolierte Installationen, die eine strikte Abhängigkeitsisolation ähnlich wie pnpms Ansatz erstellt. Dieser Modus verhindert Phantom-Abhängigkeiten und stellt reproduzierbare, deterministische Builds sicher.

Dies ist die Standard-Installationsstrategie für neue Workspace/Monorepo-Projekte (mit configVersion = 1 in der Lockfile). Bestehende Projekte verwenden weiterhin gehoisste Installationen, sofern nicht explizit konfiguriert.

Was sind isolierte Installationen?

Isolierte Installationen erstellen eine nicht-gehoisste Abhängigkeitsstruktur, bei der Pakete nur auf ihre explizit deklarierten Abhängigkeiten zugreifen können. Dies unterscheidet sich von der traditionellen "gehoissten" Installationsstrategie, die von npm und Yarn verwendet wird, bei der Abhängigkeiten in ein gemeinsames node_modules-Verzeichnis geglättet werden.

Hauptvorteile

• Verhindert Phantom-Abhängigkeiten — Pakete können nicht versehentlich Abhängigkeiten importieren, die sie nicht deklariert haben
• Deterministische Auflösung — Gleicher Abhängigkeitsbaum unabhängig davon, was sonst installiert ist
• Besser für Monorepos — Workspace-Isolation verhindert Kreuzkontamination zwischen Paketen
• Reproduzierbare Builds — Vorhersehbareres Auflösungsverhalten über Umgebungen hinweg

Verwendung isolierter Installationen

Befehlszeile

Verwenden Sie das --linker-Flag, um die Installationsstrategie anzugeben:

# Isolierte Installationen verwenden
bun install --linker isolated

# Traditionelle gehoisste Installationen verwenden
bun install --linker hoisted

Konfigurationsdatei

Legen Sie die Standard-Linker-Strategie in Ihrer bunfig.toml oder global in $HOME/.bunfig.toml fest:

[install]
linker = "isolated"

Standardverhalten

Das Standard-Linker-Verhalten hängt von der configVersion Ihrer Lockfile ab:

configVersion	Workspaces verwendet?	Standard-Linker
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

Neue Projekte: Standardmäßig configVersion = 1. In Workspaces verwendet v1 standardmäßig den isolierten Linker; andernfalls verwendet es gehoisstes Linken.

Bestehende Bun-Projekte (vor v1.3.2 erstellt): Wenn Ihre bestehende Lockfile noch keine Version hat, setzt Bun configVersion = 0, wenn Sie bun install ausführen, und behält den vorherigen Standard für gehoisstes Linken bei.

Migrationen von anderen Paketmanagern:

• Von pnpm: configVersion = 1 (verwendet isolierte Installationen in Workspaces)
• Von npm oder yarn: configVersion = 0 (verwendet gehoisste Installationen)

Sie können das Standardverhalten überschreiben, indem Sie explizit das --linker-Flag angeben oder es in Ihrer Konfigurationsdatei festlegen.

Wie isolierte Installationen funktionieren

Verzeichnisstruktur

Anstatt Abhängigkeiten zu hoissen, erstellen isolierte Installationen eine zweistufige Struktur:

node_modules/
├── .bun/                          # Zentraler Paketspeicher
│   ├── package@1.0.0/             # Versionierte Paketinstallationen
│   │   └── node_modules/
│   │       └── package/           # Tatsächliche Paketdateien
│   ├── @scope+package@2.1.0/      # Gescopete Pakete (+ ersetzt /)
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # Symlinks

Auflösungsalgorithmus

1. Zentraler Speicher — Alle Pakete werden in node_modules/.bun/package@version/-Verzeichnissen installiert
2. Symlinks — node_modules auf oberster Ebene enthält Symlinks, die auf den zentralen Speicher zeigen
3. Peer-Auflösung — Komplexe Peer-Abhängigkeiten erstellen spezialisierte Verzeichnisnamen
4. Deduplizierung — Pakete mit identischen Paket-IDs und Peer-Abhängigkeitssätzen werden geteilt

Workspace-Behandlung

In Monorepos werden Workspace-Abhängigkeiten speziell behandelt:

• Workspace-Pakete — Direkt auf ihre Quellverzeichnisse symlinked, nicht auf den Speicher
• Workspace-Abhängigkeiten — Können auf andere Workspace-Pakete im Monorepo zugreifen
• Externe Abhängigkeiten — Im isolierten Speicher mit entsprechender Isolation installiert

Vergleich mit gehoissten Installationen

Aspekt	Gehoisst (npm/Yarn)	Isoliert (pnpm-ähnlich)
Abhängigkeitszugriff	Pakete können auf jede gehoisste Abhängigkeit zugreifen	Pakete sehen nur deklarierte Abhängigkeiten
Phantom-Abhängigkeiten	❌ Möglich	✅ Verhindert
Festplattennutzung	✅ Niedriger (geteilte Installationen)	✅ Ähnlich (verwendet Symlinks)
Determinismus	❌ Weniger deterministisch	✅ Mehr deterministisch
Node.js-Kompatibilität	✅ Standardverhalten	✅ Kompatibel über Symlinks
Am besten für	Einzelprojekte, Legacy-Code	Monorepos, striktes Abhängigkeitsmanagement

Erweiterte Funktionen

Peer-Abhängigkeitsbehandlung

Isolierte Installationen behandeln Peer-Abhängigkeiten durch ausgeklügelte Auflösung:

# Paket mit Peer-Abhängigkeiten erstellt spezialisierte Pfade
node_modules/.bun/package@1.0.0_react@18.2.0/

Der Verzeichnisname kodiert sowohl die Paketversion als auch die Peer-Abhängigkeitsversionen und stellt sicher, dass jede eindeutige Kombination ihre eigene Installation erhält.

Backend-Strategien

Bun verwendet verschiedene Dateioperationsstrategien für die Leistung:

• Clonefile (macOS) — Copy-on-Write-Dateisystemklone für maximale Effizienz
• Hardlink (Linux/Windows) — Hardlinks zum Speichern von Festplattenspeicher
• Copyfile (Fallback) — Vollständige Dateikopien, wenn andere Methoden nicht verfügbar sind

Debuggen isolierter Installationen

Aktivieren Sie die ausführliche Protokollierung, um den Installationsprozess zu verstehen:

bun install --linker isolated --verbose

Dies zeigt:

• Erstellung von Speichereinträgen
• Symlink-Operationen
• Peer-Abhängigkeitsauflösung
• Deduplizierungsentscheidungen

Fehlerbehebung

Kompatibilitätsprobleme

Einige Pakete funktionieren möglicherweise nicht korrekt mit isolierten Installationen aufgrund von:

• Hardcodierten Pfaden — Pakete, die eine flache node_modules-Struktur voraussetzen
• Dynamischen Importen — Laufzeitimporte, die der Node.js-Auflösung nicht folgen
• Build-Tools — Tools, die node_modules direkt durchsuchen

Wenn Sie auf Probleme stoßen, können Sie:

1. Für bestimmte Projekte in den gehoissten Modus wechseln:

   bun install --linker hoisted

2. Kompatibilitätsprobleme melden, um die Unterstützung isolierter Installationen zu verbessern

Leistungsüberlegungen

• Installationszeit — Kann aufgrund von Symlink-Operationen etwas langsamer sein
• Festplattennutzung — Ähnlich wie gehoisst (verwendet Symlinks, keine Dateikopien)
• Speichernutzung — Höher während der Installation aufgrund komplexer Peer-Auflösung

Migrationsanleitung

Von npm/Yarn

# Bestehende node_modules und Lockfiles entfernen
rm -rf node_modules package-lock.json yarn.lock

# Mit isoliertem Linker installieren
bun install --linker isolated

Von pnpm

Isolierte Installationen sind konzeptionell ähnlich wie pnpm, daher sollte die Migration unkompliziert sein:

# pnpm-Dateien entfernen
rm -rf node_modules pnpm-lock.yaml

# Mit Buns isoliertem Linker installieren
bun install --linker isolated

Der Hauptunterschied besteht darin, dass Bun Symlinks in node_modules verwendet, während pnpm einen globalen Speicher mit Symlinks verwendet.

Wann isolierte Installationen verwenden

Verwenden Sie isolierte Installationen, wenn:

• Sie in Monorepos mit mehreren Paketen arbeiten
• Striktes Abhängigkeitsmanagement erforderlich ist
• Die Verhinderung von Phantom-Abhängigkeiten wichtig ist
• Bibliotheken erstellt werden, die deterministische Abhängigkeiten benötigen

Verwenden Sie gehoisste Installationen, wenn:

• Mit Legacy-Code gearbeitet wird, der flache node_modules voraussetzt
• Kompatibilität mit bestehenden Build-Tools erforderlich ist
• In Umgebungen gearbeitet wird, in denen Symlinks nicht gut unterstützt werden
• Sie das einfachere traditionelle npm-Verhalten bevorzugen

Verwandte Dokumentation

• Paketmanager > Workspaces — Monorepo-Workspace-Verwaltung
• Paketmanager > Lockfile — Verständnis des Bun-Lockfile-Formats
• CLI > install — Vollständige bun install-Befehlsreferenz