Как удалить пакет из npm: unpublish версии и всего пакета

Политика npm: почему unpublish иногда запрещён

npm считает опубликованные данные реестра фактически неизменяемыми для целей стабильности экосистемы. Для недавно опубликованного пакета действует окно: если прошло меньше 72 часов и другие пакеты публичного npm Registry от него не зависят, пакет можно снять с публикации. Для пакета старше 72 часов npm требует одновременно выполнить дополнительные условия: отсутствие зависимых публичных пакетов, менее 300 загрузок за последнюю неделю и единственный owner/maintainer. Эти критерии нужны, чтобы случайное удаление популярной зависимости не ломало чужие сборки. Поэтому отказ unpublish у старого пакета может быть ожидаемым ограничением политики, а не проблемой токена или версии CLI. Перед действиями полезно открыть официальную policy ещё раз: правила registry важнее старых блогов и ответов на форумах.

Важно: Перед удалением сохраните имя пакета и точную версию в журнале релиза. Операция необратима, а прежнюю пару package@version повторно использовать нельзя.

Безопасный порядок удаления версии или пакета

1. Проверьте registry: Выполните `npm config get registry` и `npm whoami`, особенно если одновременно используете npmjs.com и корпоративный registry.
2. Проверьте пакет и версию: Посмотрите `npm view <package> versions`, чтобы не удалить соседний релиз из-за опечатки.
3. Для одной версии укажите точный spec: Выполните `npm unpublish <package>@<version>`. Это предпочтительнее полного удаления, если проблема только в одном релизе.
4. Для полного удаления применяйте --force осознанно: Если политика npm допускает удаление всех версий, команда имеет вид `npm unpublish <package> --force`.
5. Проверьте registry после операции: Снова запросите метаданные пакета и убедитесь, что исчезла именно ожидаемая версия или весь пакет.
6. Исправление публикуйте новой версией: Удалённую version переиспользовать нельзя, поэтому исправленный релиз получает новый semver.

Предупреждение: Не вставляйте `--force` по привычке в скрипты релиза. Эта опция предназначена для осознанного полного удаления пакета, если policy разрешает действие.

Unpublish или deprecate: что выбрать

[object Object]

Что нельзя сделать после unpublish

У unpublish есть два критичных последствия. Во-первых, npm говорит, что уже использованную комбинацию package@version нельзя опубликовать снова, даже если эту версию сняли. Если вы удалили 1.2.3, исправленный релиз должен получить другую версию — например 1.2.4 или подходящую по вашей semver-стратегии. Во-вторых, если удалить все версии пакета целиком, npm вводит 24-часовую паузу перед публикацией новых версий пакета с тем же именем. Поэтому полное удаление — плохой способ «быстро очистить историю и тут же начать заново». Для обычной ошибки релиза почти всегда безопаснее точечно снять свежую версию или, если policy не позволяет, пометить её deprecated и выпустить исправление. Не стройте автоматизацию, которая предполагает повторное использование номера версии после неудачной публикации. Если пакет scoped, перепроверьте scope и активный registry перед удалением: одинаковое короткое имя в другом namespace — другой объект. Для автоматизации также фиксируйте точный package spec в логе операции, чтобы последующий аудит не зависел от памяти автора релиза.

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

Если npm не разрешает удалить пакет

Не пытайтесь обходить политику сменой владельцев или удалением collaborators: документация прямо отмечает, что это само по себе не снимает пакет с публикации. Сначала прочитайте причину отказа и сравните пакет с критериями. Если пакет не подходит под unpublish, используйте `npm deprecate <package> "<message>"` для всего пакета или `npm deprecate <package>@<version> "<message>"` для конкретной версии. Сообщение должно помогать пользователю: укажите исправленную версию, альтернативный пакет или причину, а не просто «do not use». Для чувствительных случаев — например, случайно опубликованных секретов — считайте секрет уже раскрытым, отзовите его у провайдера и только затем отдельно решайте вопрос с реестром. Само удаление tarball не делает ранее попавший в чужой кеш токен безопасным.

Перед unpublish оцените не только техническую возможность, но и последствия для уже опубликованной документации, lock-файлов и CI пользователей. Даже малое число загрузок не означает, что пакет нигде не закреплён в частном проекте. Если релиз содержит обычную функциональную ошибку, новый исправленный semver-релиз плюс deprecate часто создаёт меньше неожиданностей, чем исчезновение артефакта. Если же опубликован секрет, удаление версии не является процедурой отзыва секрета: токен или ключ нужно немедленно аннулировать у его провайдера, потому что tarball мог быть скачан или закеширован. После операции проверьте не только веб-страницу npm, но и установку ожидаемой версии из чистого временного каталога, чтобы исключить ошибку в имени, scope или registry.

Перед нажатием Enter

• Registry и активный npm-пользователь проверены.
• Точно известны package name и version, которые требуется снять.
• Проверено, разрешает ли npm policy unpublish для этого пакета.
• Понятно, что удалённую version нельзя опубликовать снова.
• Если полное удаление не нужно, выбран unpublish одной версии или deprecate.
• В CI или локальном журнале зафиксирована причина операции и следующая версия исправления.

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

npm считает опубликованные данные реестра фактически неизменяемыми для целей стабильности экосистемы. Для недавно опубликованного пакета действует окно: если прошло меньше 72 часов и другие пакеты публичного npm Registry от него не зависят, пакет можно снять с публикации. Для пакета старше 72 часов npm требует одновременно выполнить дополнительные условия: отсутствие зависимых публичных пакетов, менее 300 загрузок за последнюю неделю и единственный owner/maintainer. Эти критерии нужны, чтобы…

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

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

• npm Unpublish Policy
• Unpublishing packages from the registry