На главную

DF-ВЕБ-041 · Контент и сайты

Сборка ломается из-за внешних репозиториев: проверка зависимостей

Редакция Deskforge · 18 ноября 2026 · 6 мин чтения
Сборка ломается из-за внешних репозиториев: проверка зависимостей
Из статьи вы узнаете
  • Что именно фиксирует lockfile и почему без него сборка не воспроизводится
  • Какие поля package-lock.json проверить: resolved, integrity и hasInstallScript
  • Где в двухдокументном pnpm-lock.yaml лежит граф проекта
  • Почему сканер может ложно показать отсутствие зависимостей и пропустить CI-проверку

Сборка проходила вчера, а сегодня падает на установке зависимостей — при том, что вы не меняли ни одной строки в манифесте. Знакомая картина: где-то в глубине дерева обновился транзитивный пакет, обновился git-адрес или изменился источник, откуда тянется архив. Код тот же, а окружение уже другое.

Воспроизводимость сборки держится не на аккуратности разработчика, а на файле блокировки — lockfile. Он записывает, какие именно версии и откуда были установлены, чтобы следующая установка повторила то же дерево. Ниже — что проверить в этом файле до того, как сборка сломается, и где проверка может дать ложное «всё чисто».

Это редакционный чек-лист Deskforge, а не отчёт об испытании продукта и не клиентский кейс: шаги нужно адаптировать к вашему стеку и вашему пакетному менеджеру. Смежная тема — проверка npm-зависимости перед установкой, а работы по сайтам и кабинетам собраны на странице контента и сайтов.

Почему сборка перестаёт воспроизводиться: что фиксирует lockfile

Документация npm прямо описывает назначение package-lock.json: файл хранит точное дерево, которое было сгенерировано при операциях npm, чтобы последующие установки могли собирать идентичные деревья независимо от промежуточных обновлений зависимостей. То есть смысл файла — отвязать вашу установку от того, что успело выйти в реестре между двумя запусками.

Второй момент — файл предназначен для коммита в репозиторий исходного кода. Если lockfile лежит только на машине разработчика или в .gitignore, воспроизводимости нет: у коллеги и в CI соберётся своё дерево, и расхождение проявится не сразу, а в самый неудобный момент.

Третья цель из той же документации — обеспечить, чтобы коллеги, развёртывания и непрерывная интеграция устанавливали ровно одни и те же зависимости. Это и есть ответ на вопрос, почему сборка «вдруг» перестала воспроизводиться: где-то в цепочке lockfile не участвовал или расходился с манифестом.

Практический вывод простой: перед разбором любой поломки сборки сначала убедитесь, что lockfile закоммичен, актуален и одинаков во всех окружениях. Дальше смотрите внутрь него.

Что смотреть в package-lock.json: resolved, integrity и скрипты установки

В дескрипторе пакета внутри package-lock.json есть поля, по которым видно, откуда и как придёт зависимость. Поле resolved для git-зависимостей содержит полный git-адрес с commit sha — то есть фиксирует конкретный коммит, а не ветку, которая может уехать вперёд.

Поле integrity хранит строку Standard Subresource Integrity (sha512 или sha1) для распакованного артефакта. Если integrity пустой, проверить целостность скачанного пакета по этому полю не получится — а именно это поле ловит подмену содержимого.

Отдельно стоит флаг hasInstallScript: он указывает, что у пакета есть скрипт preinstall, install или postinstall. Сам флаг не говорит, безопасен ли скрипт, но он показывает, что при установке выполнится чужой код, — а значит, такой пакет стоит просмотреть глазами.

Разберём на синтетическом примере — это учебные данные, не клиентский кейс.

Возьмём четыре записи: обычный пакет из реестра с integrity, git-зависимость с commit sha, пакет из реестра с пустым integrity и install-скриптом и локальную ссылку без integrity. Проверка по полям resolved и integrity даёт такой результат:

Строка Источник integrity install-скрипт Итог проверки
1 архив из реестра есть нет проходит
2 git с commit sha commit sha нет проходит
3 архив из реестра пусто есть не проходит
4 локальная ссылка пусто нет не проходит

Логика проверки воспроизведена локальным обработчиком на учебных данных. Это подтверждает саму логику отбора, но не говорит ничего о вашем проекте и не заменяет проверку реального дерева зависимостей.

Два документа pnpm-lock.yaml: где граф проекта, а где boot-часть

В pnpm картина другая. pnpm-lock.yaml — это YAML-файл, но не всегда один YAML-документ: в зависимости от того, что использует проект, pnpm пишет один документ или два. Это важно, потому что от числа документов зависит, как читать файл инструментами.

Когда документов два, первый — boot-документ. В нём лежат configDependencies и packageManagerDependencies с нужными им записями packages и snapshots. Это служебная часть: конфигурационные зависимости и версия самого pnpm, закреплённая за проектом.

Последний документ присутствует всегда и содержит граф зависимостей самого проекта: importers с их зависимостями и соответствующие packages и snapshots. Если инструменту нужен ответ на вопрос «от чего зависит этот проект», брать нужно именно последний документ, загружая файл через API для нескольких документов.

Отсюда типичная ошибка самодельных скриптов и сторонних читателей lockfile: они открывают файл как один документ и получают только boot-часть. Дальше — сюрприз в следующем разделе.

Почему сканер может показать «нет зависимостей» и пропустить CI-проверку

Документация pnpm описывает это прямо: инструмент, который читает только первый документ двухдокументного lockfile, не падает с явной ошибкой. Boot-документ структурно валиден как lockfile — он просто описывает importer без зависимостей.

Дальше цепочка разворачивается сама. Такой инструмент сообщает, что у проекта нет зависимостей, а значит, и нет уязвимостей, — и CI-проверка, построенная на нём, проходит. Зелёная галочка при этом не значит, что зависимости проверены: их просто не увидели.

Поэтому при сканировании pnpm-проектов читать нужно все документы lockfile. Инструмент, читающий только проектный документ, пропускает config-зависимости; инструмент, читающий только boot-документ, пропускает всё остальное. Оба случая дают неполную картину, но выглядят как успешная проверка.

Если вы не хотите разбираться с форматом самостоятельно, есть штатный путь: pnpm audit корректно читает lockfile в обеих формах и не требует настройки. Это утверждение относится именно к pnpm audit и не переносится автоматически на сторонние сканеры — их поведение нужно проверять отдельно.

Закреплённая версия pnpm и --frozen-lockfile: когда установка падает

Отдельная причина падения сборки — расхождение между закреплённой версией pnpm и lockfile. Если закреплённая версия pnpm отсутствует в lockfile или больше не совпадает с ним, команда pnpm install --frozen-lockfile завершается ошибкой ERR_PNPM_FROZEN_LOCKFILE_WITH_OUTDATED_LOCKFILE.

Практический смысл: манифест, в котором подняли закреплённую версию pnpm, но не перегенерировали lockfile, не пройдёт CI. Это не случайная поломка, а сработавшая защита — установка с флагом --frozen-lockfile как раз и нужна, чтобы такое расхождение не проскочило молча.

Поэтому при обновлении версии пакетного менеджера меняйте манифест и lockfile вместе, одним изменением. Тогда падение на установке будет означать реальную проблему, а не забытый шаг.

Чек-лист проверки перед сборкой и границы применимости

Соберём порядок проверки, который можно пройти до того, как сборка сломается. Он опирается на документацию npm и pnpm, а также на раздел документации GitHub по безопасности цепочки поставок — там темы безопасности зависимостей, управления безопасностью зависимостей и установления происхождения и целостности проектов собраны вместе.

  • Убедитесь, что lockfile закоммичен и одинаков во всех окружениях: локально, у коллег, в CI.
  • Просмотрите записи с пустым integrity и с флагом hasInstallScript — это кандидаты на ручной разбор.
  • Для git-зависимостей проверьте, что в resolved стоит полный адрес с commit sha, а не ветка.
  • Если проект на pnpm, выясните, сколько документов в lockfile, и убедитесь, что ваши инструменты читают все.
  • Держите версию пакетного менеджера и lockfile согласованными, чтобы --frozen-lockfile не падал на забытом шаге.

Границы применимости честные: утверждения выше относятся к npm и pnpm и их форматам lockfile, они не описывают автоматически другие пакетные менеджеры. Синтетический пример проверяет учебную логику отбора записей, но не подтверждает работу вашего CI, поведение конкретного сканера или отсутствие проблем в реальном дереве зависимостей. Проверку стоит повторить на своём проекте и своих инструментах.

Источники

Назад