pnpm store prune: как очистить store и не сломать проекты

Что именно хранит pnpm store

pnpm экономит место тем, что одинаковые файлы пакетов не копируются отдельно в каждый проект. Пакетные данные лежат в общем content-addressable store, а проекты получают доступ к нужному содержимому через ссылки. После обновления зависимости старая версия может остаться в store, даже если текущая ветка уже перешла на новую. Это сделано намеренно: другой проект или старая ветка ещё могут использовать прежнюю версию. Со временем хранилище накапливает объекты, на которые больше никто не ссылается. Именно их и удаляет `pnpm store prune`. После завершения pnpm показывает объём убранных файлов, поэтому можно сразу оценить, была ли очистка вообще полезной.

Как очистить pnpm store пошагово

1. 1: Запустите `pnpm store path`, чтобы увидеть фактический путь активного store.
2. 2: Закройте активные процессы установки пакетов, чтобы не смешивать очистку с текущим install.
3. 3: Выполните `pnpm store prune` под тем же пользователем, который обычно запускает pnpm.
4. 4: Посмотрите итоговый отчёт. Удалять `node_modules` в каждом проекте после этой команды не требуется.
5. 5: При необходимости откройте нужный проект и выполните обычный `pnpm install`; отсутствующие данные будут скачаны повторно.

Совет: Перед поездкой без интернета или работой со старыми release-ветками prune лучше отложить: локальный запас версий может пригодиться.

Почему существующие проекты не ломаются после prune

Официальная документация pnpm описывает `store prune` как операцию без побочных эффектов для проектов. Удаляются пакеты, которые больше не используются зарегистрированными проектами. Если такая версия позже понадобится — например, после checkout старого commit, — pnpm загрузит её повторно. Риск здесь не в повреждении рабочей копии, а в потере «тёплого» локального запаса. Поэтому очистка полезна, когда диск действительно нужно разгрузить, но бессмысленно запускать её после каждой установки. Слишком частый prune превращает экономию места в лишний сетевой трафик и более медленный возврат к старым зависимостям.

Что очищает pnpm store prune, а что нет

• Неиспользуемые пакеты в pnpm store. Удаляются. Главная цель команды.
• Пакеты, нужные активным проектам. Сохраняются. Они считаются используемыми.
• node_modules конкретного проекта. Не является целью команды. Для переустановки проекта используются другие действия.
• Возможность поставить старую версию позже. Сохраняется через повторное скачивание. После prune может потребоваться сеть.

Когда prune действительно имеет смысл

Хороший момент — после долгой разработки, множества обновлений монорепозитория или удаления нескольких старых проектов, когда свободное место заметно уменьшилось. Ещё один сценарий — рабочая станция или CI-агент с ограниченным SSD, где pnpm месяцами использовался для разных веток. Но перед очисткой оцените, насколько важны офлайн-установки. Если команда часто возвращается к старым релизам без постоянного доступа к registry, прежние версии в store — не мусор, а полезный локальный резерв. Документация pnpm советует запускать prune время от времени, но не слишком часто. Практичный подход — очищать при реальной необходимости, а не превращать команду в обязательный postinstall-хук.

Если диск всё ещё заполнен после prune

• Проверьте фактический путь через `pnpm store path`: возможно, вы смотрите не тот каталог.
• Проверьте старые `node_modules`, build-артефакты и кэши других инструментов: store prune их не удаляет.
• Если менялся `store-dir` или версия pnpm, на диске могут остаться другие хранилища.
• Не удаляйте неизвестные каталоги вручную до проверки, кто ими пользуется.
• На CI отличайте кэш runner от собственного pnpm store.

Предупреждение: Если после ручного удаления store установка стала полностью сетевой, это ожидаемо: вы стерли пакетные данные, а не только неиспользуемые версии.

Почему store — не просто временный кэш

В разговорной речи pnpm store часто называют кэшем, но для самого package manager это общее хранилище пакетных файлов, из которого проекты переиспользуют данные. Поэтому правильная задача — не «стереть всё временное», а убрать только объекты, на которые больше нет ссылок. `pnpm store prune` решает именно её. Если же установка одного проекта падает, prune не должен быть первой реакцией: сначала смотрят текст ошибки, lockfile, registry и integrity. Очистка store нужна для дискового пространства и накопившихся версий, а не как универсальное средство от любой ошибки `pnpm install`.

Как проверить эффект очистки и не перепутать его с размером проекта

До и после prune полезно посмотреть путь store и свободное место на том же диске. Не делайте вывод только по размеру `node_modules` конкретного проекта: pnpm переиспользует данные, и физическая экономия распределена между общим store и ссылками. Если команда освободила мало места, это может означать, что большинство пакетов всё ещё реально используются другими проектами. В таком случае дополнительный ручной purge не делает их «мусором». Сначала найдите старые рабочие копии, build-артефакты, Docker-образы и другие крупные каталоги. Store prune должен оставаться узкой операцией по сборке неиспользуемых пакетов, а не заменой нормальному анализу дискового пространства.

Что произойдёт после prune при переключении на старую ветку

Удаление неиспользуемых пакетов из store не переписывает `package.json` и lockfile проекта. Но если позже вы переключитесь на старую ветку, где нужны версии, уже удалённые командой prune, следующая установка должна будет скачать их снова. Именно поэтому pnpm рекомендует очищать store время от времени, а не после каждого рабочего дня. На машине с большим количеством активных веток и репозиториев слишком частый prune экономит диск ценой повторных сетевых загрузок. Для CI-агента или временного окружения этот компромисс может быть другим, чем на рабочем ноутбуке разработчика. Перед очисткой полезно посмотреть путь `pnpm store path`, оценить размер каталога и понять, действительно ли именно он занимает место. Если основной объём лежит в локальных `node_modules`, build-кэше или Docker-образах, `pnpm store prune` не решит проблему, потому что команда отвечает за общий store, а не за весь мусор проекта.

Как встроить очистку store в нормальное обслуживание рабочей машины

Практичный режим — запускать prune после заметных обновлений зависимостей, удаления старых проектов или когда общий store действительно вырос до неудобного размера. Команду лучше выполнять отдельно от активных установок и сборок, чтобы диагностика оставалась понятной. Сначала зафиксируйте свободное место, затем выполните `pnpm store prune` и посмотрите отчёт pnpm о размере удалённых файлов. После этого откройте один-два текущих проекта и при необходимости выполните обычный install. Если они работают, дополнительных действий не требуется. Не заменяйте `pnpm store prune` ручным удалением случайных внутренних каталогов store: структура хранилища является частью реализации package manager и может меняться между версиями. Штатная команда знает, какие данные считаются неиспользуемыми, а ручная «чистка по папкам» лишает вас этой проверки и усложняет восстановление.

Когда очистку лучше отложить

Если вы прямо сейчас переключаетесь между несколькими старыми ветками или работаете без стабильного доступа к registry, prune может быть невыгоден: удалённые версии придётся скачивать заново. Сначала завершите работу, затем очищайте store осознанно.

Что учитывать

Официальная документация pnpm описывает `store prune` как операцию без побочных эффектов для проектов. Удаляются пакеты, которые больше не используются зарегистрированными проектами. Если такая версия позже понадобится — например, после checkout старого commit, — pnpm загрузит её повторно. Риск здесь не в повреждении рабочей копии, а в потере «тёплого» локального запаса. Поэтому очистка полезна, когда диск действительно нужно разгрузить, но бессмысленно запускать её после каждой установки…

Источники и проверка

Фактическая часть сверена по первичным источникам (в т.ч. pnpm store). Пример и формулировки — редакция N1RO на 2026-09-20.

• pnpm store