Сборка ломается из-за внешних репозиториев: проверка зависимостей
- Что именно фиксирует 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, поведение конкретного сканера или отсутствие проблем в реальном дереве зависимостей. Проверку стоит повторить на своём проекте и своих инструментах.