Bun предоставляет альтернативную стратегию установки пакетов, называемую изолированными установками, которая создает строгую изоляцию зависимостей, аналогичную подходу pnpm. Этот режим предотвращает фантомные зависимости и обеспечивает воспроизводимые, детерминированные сборки.

Это стратегия установки по умолчанию для новых проектов рабочих областей/монорепозиториев (с configVersion = 1 в файле блокировки). Существующие проекты продолжают использовать установки с поднятием, если явно не настроено иное.

Что такое изолированные установки?

Изолированные установки создают структуру зависимостей без поднятия, где пакеты могут получать доступ только к своим явно объявленным зависимостям. Это отличается от традиционной стратегии установки с «поднятием», используемой npm и Yarn, где зависимости выравниваются в общий каталог node_modules.

Ключевые преимущества

• Предотвращает фантомные зависимости — Пакеты не могут случайно импортировать зависимости, которые они не объявили
• Детерминированное разрешение — Одно и то же дерево зависимостей независимо от того, что еще установлено
• Лучше для монорепозиториев — Изоляция рабочих областей предотвращает перекрестное загрязнение между пакетами
• Воспроизводимые сборки — Более предсказуемое поведение разрешения в различных средах

Использование изолированных установок

Командная строка

Используйте флаг --linker для указания стратегии установки:

# Использовать изолированные установки
bun install --linker isolated

# Использовать традиционные установки с поднятием
bun install --linker hoisted

Файл конфигурации

Установите стратегию компоновщика по умолчанию в вашем bunfig.toml или глобально в $HOME/.bunfig.toml:

[install]
linker = "isolated"

Поведение по умолчанию

Стратегия компоновщика по умолчанию зависит от configVersion файла блокировки вашего проекта:

configVersion	Использование рабочих областей?	Компоновщик по умолчанию
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

Новые проекты: По умолчанию configVersion = 1. В рабочих областях v1 использует изолированный компоновщик по умолчанию; в противном случае используется поднятие.

Существующие проекты Bun (созданные до v1.3.2): Если в вашем существующем файле блокировки еще нет версии, Bun устанавливает configVersion = 0 при запуске bun install, сохраняя предыдущий компоновщик с поднятием по умолчанию.

Миграция с других менеджеров пакетов:

• Из pnpm: configVersion = 1 (используя изолированные установки в рабочих областях)
• Из npm или yarn: configVersion = 0 (используя установки с поднятием)

Вы можете переопределить поведение по умолчанию, явно указав флаг --linker или установив его в файле конфигурации.

Как работают изолированные установки

Структура каталогов

Вместо поднятия зависимостей изолированные установки создают двухуровневую структуру:

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. Разрешение peer-зависимостей — Сложные peer-зависимости создают специализированные имена каталогов
4. Дедупликация — Пакеты с одинаковыми идентификаторами пакетов и наборами peer-зависимостей являются общими

Обработка рабочих областей

В монорепозиториях зависимости рабочих областей обрабатываются особым образом:

• Пакеты рабочей области — Символически связаны непосредственно с их исходными каталогами, а не с хранилищем
• Зависимости рабочей области — Могут получать доступ к другим пакетам рабочей области в монорепозитории
• Внешние зависимости — Устанавливаются в изолированное хранилище с надлежащей изоляцией

Сравнение с установками с поднятием

Аспект	С поднятием (npm/Yarn)	Изолированные (pnpm-like)
Доступ к зависимостям	Пакеты могут получать доступ к любой поднятой зависимости	Пакеты видят только объявленные зависимости
Фантомные зависимости	❌ Возможны	✅ Предотвращены
Использование диска	✅ Ниже (общие установки)	✅ Аналогично (использует симлинки)
Детерминизм	❌ Менее детерминировано	✅ Более детерминировано
Совместимость с Node.js	✅ Стандартное поведение	✅ Совместимо через симлинки
Лучше для	Отдельные проекты, устаревший код	Монорепозитории, строгое управление зависимостями

Расширенные функции

Обработка peer-зависимостей

Изолированные установки обрабатывают peer-зависимости через сложное разрешение:

# Пакет с peer-зависимостями создает специализированные пути
node_modules/.bun/package@1.0.0_react@18.2.0/

Имя каталога кодирует как версию пакета, так и версии его peer-зависимостей, обеспечивая собственную установку для каждой уникальной комбинации.

Стратегии бэкенда

Bun использует различные стратегии файловых операций для производительности:

• Clonefile (macOS) — Копирование файловой системы copy-on-write для максимальной эффективности
• Hardlink (Linux/Windows) — Жесткие ссылки для экономии дискового пространства
• Copyfile (резервный вариант) — Полное копирование файлов, когда другие методы недоступны

Отладка изолированных установок

Включите подробное логирование, чтобы понять процесс установки:

bun install --linker isolated --verbose

Это показывает:

• Создание записей хранилища
• Операции с символическими ссылками
• Разрешение peer-зависимостей
• Решения о дедупликации

Устранение неполадок

Проблемы совместимости

Некоторые пакеты могут не работать корректно с изолированными установками из-за:

• Жестко закодированные пути — Пакеты, которые предполагают плоскую структуру node_modules
• Динамические импорты — Импорты времени выполнения, которые не следуют разрешению Node.js
• Инструменты сборки — Инструменты, которые сканируют node_modules напрямую

Если вы столкнулись с проблемами, вы можете:

1. Переключиться в режим с поднятием для конкретных проектов:

   bun install --linker hoisted

2. Сообщить о проблемах совместимости, чтобы помочь улучшить поддержку изолированных установок

Соображения производительности

• Время установки — Может быть немного медленнее из-за операций с символическими ссылками
• Использование диска — Аналогично поднятию (использует символические ссылки, а не копии файлов)
• Использование памяти — Выше во время установки из-за сложного разрешения peer-зависимостей

Руководство по миграции

Из npm/Yarn

# Удалить существующие node_modules и файлы блокировки
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 использует глобальное хранилище с символическими ссылками.

Когда использовать изолированные установки

Используйте изолированные установки, когда:

• Работа в монорепозиториях с несколькими пакетами
• Требуется строгое управление зависимостями
• Важно предотвращение фантомных зависимостей
• Создание библиотек, нуждающихся в детерминированных зависимостях

Используйте установки с поднятием, когда:

• Работа с устаревшим кодом, который предполагает плоский node_modules
• Требуется совместимость с существующими инструментами сборки
• Работа в средах, где символические ссылки плохо поддерживаются
• Вы предпочитаете более простое традиционное поведение npm

Связанная документация

• Менеджер пакетов > Рабочие области — Управление рабочими областями монорепозитория
• Менеджер пакетов > Файл блокировки — Понимание формата файла блокировки Bun
• CLI > install — Полная справка по команде bun install