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

Почему унаследованные проекты продолжают ломаться на разных машинах

Унаследованные кодовые базы часто ломаются самым раздражающим образом: непоследовательно. Один разработчик запускает приложение без проблем, другой получает загадочную ошибку. CI проходил утром, а днём падает. Небольшое, казалось бы безобидное изменение уходит в продакшен, и поведение меняется.

Этот «works on my machine» дрейф означает, что не только код решает — удастся ли собрать проект. Скрытые различия между ноутбуками, раннерами CI и серверами продакшена меняют, что устанавливается, как запускается и что в итоге деплоится.

Худшее — это случайность. Вы перестаёте доверять тестам, потому что они ненадёжны. Тратите время на поиск багов, которые не удаётся воспроизвести. И начинаете делать рискованные временные фиксы (например, вручную фиксировать зависимость), которые потом приводят к новым сюрпризам.

Большинство причин просты и исправимы:

• Разные версии Node.js (даже минорные отличия могут сломать нативные модули или инструменты)
• Отсутствие или игнорирование lockfile, из‑за чего установки подтягивают немного разные деревья зависимостей
• Глобальные утилиты (npm, yarn, pnpm, TypeScript, ESLint), которые отличаются на каждой машине
• Скрипты postinstall, которые ведут себя по‑разному в разных ОС или шеллах
• Кеширование в CI, которое скрывает проблемы, которые проявились бы при чистой установке

Цель простая: одинаковые входные данные должны давать одинаковый результат везде. Та же версия Node, тот же пакетный менеджер, то же дерево зависимостей, те же шаги сборки, одинаковые артефакты.

Когда вы устраняете дрейф, ошибки перестают казаться случайными. Если что-то ломается, оно ломается у всех в одном и том же месте с одинаковой ошибкой. Именно тогда унаследованный проект снова становится поддерживаемым.

Что значит воспроизводимая сборка в Node-проектах

Воспроизводимая сборка означает, что вы можете взять одну и ту же кодовую базу, выполнить одни и те же команды и получить один и тот же результат каждый раз. В Node‑проектах этот «результат» — не просто «запускается на моём ноутбуке». Он должен вести себя одинаково у всех в команде, в CI и в продакшене.

Если на одной машине стоит Node 18, на другой — Node 20, или на одной установке подтягиваются более новые пакеты, чем на другой, это уже не один и тот же проект.

В здоровом Node‑репозитории должно быть стабильно:

• Установка: чистый клон устанавливается без ручных починок
• Выход сборки: одни и те же исходники дают функционально идентичные артефакты
• Тесты: одинаковый прогон тестов проходит или падает по тем же причинам
• Скрипты: npm run build (или аналог) работает одинаково везде
• Ошибки: когда что-то ломается, оно ломается одинаково, а не случайно

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

Обычно вы понимаете, что воспроизводимости нет, когда чистая установка падает или когда CI падает, а на ноутбуках всё ок. Ещё признак — поведение меняется после удаления node_modules, или когда два разработчика получают разные версии одной и той же зависимости после установки.

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

Выберите единый источник правды для версий и скриптов

Унаследованные проекты ломаются, потому что правила живут в головах людей. Один разработчик использует Node 18, CI — Node 20, продакшен всё ещё на 16, и никто не замечает до тех пор, пока зависимость не изменит поведение. Выберите одно место в репозитории, где правда записана и принудительно применяется.

Начните с решения, где объявлять версии. Кладите их в файлы, которые ездят вместе с кодом, а не в README, который устаревает. Обычно это файл версии Node под управлением репозитория, настройка версии пакетного менеджера и (если вы используете контейнеры) тег базового образа, который не «плавает».

Далее договоритесь о точках входа сборки. Все должны запускать одни и те же команды для установки, сборки и тестов. Если существует несколько способов собрать (кастомные скрипты, ad‑hoc флаги, разные папки), дрейф будет возвращаться.

Правило, которое хорошо работает: если CI не может запустить сборку из чистого чекаута используя скрипты проекта — это не часть сборки.

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

Зафиксируйте версии Node и пакетного менеджера

Большинство «works on my machine» багов начинается ещё до запуска вашего кода. Если кто‑то на Node 18, CI на Node 20, а продакшен на 16 — вы фактически тестируете три разных приложения.

Зафиксируйте Node в месте, которое разработчики действительно будут видеть. Простые .nvmrc или .node-version в репозитории показывают ожидаемую версию сразу при открытии проекта. Дублируйте это в package.json, чтобы инструменты могли предупреждать (или падать), когда версия неправильная.

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

{
  "engines": {
    "node": ">=20 <21"
  },
  "packageManager": "[email protected]"
}

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

• Проверяйте, что node -v совпадает с зафиксированной мажорной версией
• Проверяйте, что версия пакетного менеджера совпадает с packageManager
• Немедленно падайте в CI, если что‑то не так

Навяжите использование lockfile и детерминированные установки

Lockfile — это разница между «мы все установили зависимости» и «мы все установили одинаковые зависимости». Именно эта одинаковость останавливает случайные поломки, когда транзитивный пакет выпускает новый патч.

Сначала выберите один пакетный менеджер и придерживайтесь его. Смешанная работа с инструментами создаёт скрытый дрейф: один запускает npm, другой — Yarn, CI — pnpm, и вы получаете разные деревья зависимостей, даже если package.json не менялся.

Приведите репозиторий в порядок: оставьте только один lockfile, соответствующий выбранному инструменту (package-lock.json, yarn.lock или pnpm-lock.yaml). Если вы видите более одного — считайте это ошибкой, а не предпочтением.

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

Детерминированные установки быстро падают, когда lockfile и package.json расходятся. Это то, чего вы хотите.

# npm
npm ci

# Yarn (Berry)
yarn install --immutable

# pnpm
pnpm install --frozen-lockfile

Если установка падает — исправляйте lockfile правильно, вместо того чтобы ослаблять правила. Цель — остановить скрытые изменения.

Сделайте lockfile обязательным

Относитесь к изменениям lockfile как к изменениям кода: ревью и блокируйте слияния, которые их забывают.

• CI падает, если package.json изменился, а lockfile нет
• CI падает, если репозиторий содержит несколько lockfile
• Ревьюеры отклоняют «я запустил установку и она обновила кучу пакетов» без понятного объяснения
• Обновления зависимостей группируйте и объясняйте, не смешивайте с фич‑PR

Сделайте CI похожим на чистую локальную машину

Много дрейфа выживает потому, что ноутбуки несут в себе скрытое состояние. CI должен быть обратным: чистая машина каждый раз, использующая те же шаги установки и сборки, что и локально.

Относитесь к каждому прогону CI как к новому чек-ауту. Не полагайтесь на оставшиеся node_modules, сгенерированные файлы или глобальные инструменты. Если сборка проходит только тогда, когда что‑то уже существует — это не настоящая сборка.

Храните один скрипт как источник правды. Если разработчики запускают npm run build, CI должен запускать именно этот скрипт, а не кастомную цепочку команд.

Практический подход к CI:

• Каждый прогон чек‑аутится в чистое рабочее пространство
• Устанавливайте только из lockfile (никаких «попыток сделать лучше»)
• Запускайте те же скрипты, что локально: lint, test, build
• Падайте, когда что‑то важное не так (конфликты peer‑зависимостей, отсутствующие env‑переменные, ошибки типов)
• Сохраняйте артефакты только после успешной сборки

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

• Кешируйте кеш загрузок пакетного менеджера (а не node_modules)
• Привязывайте ключ кеша к хэшу lockfile
• Сбрасывайте кеш, когда меняется Node.js или версия пакетного менеджера

Согласуйте продакшен с тем, что реально собирал CI

Много «works on my machine» багов проявляются после деплоя, потому что продакшен не запускает то же самое, что тестировал CI. Считайте CI местом, где определяется реальность, и заставьте продакшен соответствовать ему.

Сначала выберите, где происходят сборки, и держитесь этого:

• Собирайте в CI и деплойте готовый артефакт (или образ контейнера), или
• Собирайте в продакшене, но тогда продакшен должен использовать точно ту же версию Node, тот же пакетный менеджер и те же команды установки, что и CI

Смешивание подходов — источник неожиданных изменений.

Если вы используете Docker, фиксируйте тег базового образа вместо плавающего тега. Небольшое изменение базового образа может поменять Node, OpenSSL или системные библиотеки и привести к «тот же код, другое поведение». Обновляйте базовый образ осознанно и давайте CI его протестировать.

Держите переменные окружения отдельно от выходных артефактов сборки. Секреты и значения, зависящие от окружения, должны внедряться во время запуска, а не запекаться в бандл или коммититься в конфиг — это и вопрос безопасности, и вопрос воспроизводимости.

Наконец, проверьте, что runtime в продакшене действительно соответствует тому, что вы зафиксировали. Если CI использует Node 20, продакшен не должен молча запускать Node 18.

Пошагово: убираем дрейф, не ломая команду

Дрейф обычно начинается с малого: кто‑то обновляет Node, другой удаляет lockfile, CI использует другую команду установки, и продакшен подтягивает немного другое дерево зависимостей. Исправляйте по этапам, чтобы не блокировать повседневную работу.

Начните с базовой линии, затем постепенно ужесточайте правила:

• Зафиксируйте текущее состояние: версия Node, пакетный менеджер, команда установки и используется ли lockfile и действительно ли он применяется
• Выберите и зафиксируйте ожидаемые версии: добавьте файл версии Node и зафиксируйте версию пакетного менеджера, чтобы все использовали одни и те же инструменты
• Сделайте установки детерминированными везде: обновите CI, чтобы он использовал чистые установки и собирал из чистого рабочего пространства
• Докажите, что это работает с нуля: сделайте тест "fresh clone" на новой машине или в чистой папке и соберите с настройками, приближенными к продакшену
• После валидации введите принудительные проверки: падение при несовпадении Node, отсутствие изменений в lockfile, и защитите lockfile от случайных правок

Типичная история с унаследованными, AI‑сгенерированными прототипами — фиксирование Node и принудительные замороженные установки превращают случайную ошибку в предсказуемую и читабельную (отсутствующая зависимость, несоответствующее требование engines или скрипт, который работал только на одном ноутбуке). Как только поведение стабильно, оно исправляется.

Частые ошибки, которые возвращают «works on my machine»

Большинство команд начинают с хороших намерений, но затем маленькие упрощения возвращают дрейф. Цель проста: один и тот же код должен собираться одинаково на ноутбуке, в CI и в продакшене.

Одна из ловушек — «best effort» установка в CI. npm install может обновить lockfile, подтянуть слегка другие деревья зависимостей или вести себя по‑разному в разных версиях npm. Так вы получаете зелёный билд локально и красный в CI на следующий день.

Ещё ошибка — считать node_modules частью проекта: коммитить его, кешировать слишком агрессивно или полагаться на его наличие — всё это прячет реальные проблемы. Тогда чистая машина или чистый CI становятся первыми местами, где эти проблемы проявляются.

Также: выберите один пакетный менеджер. Когда в репозитории смешиваются артефакты npm, Yarn и pnpm, люди будут «чинить» проблему переключением команд. Это часто сработает один раз, а потом тихо изменит дерево зависимостей.

Повторяющиеся генераторы дрейфа:

• CI использует недетерминированную установку (например, обновляет lockfile во время сборки)
• Репозиторий полагается на существующий node_modules вместо чистой установки
• В репозитории используются несколько пакетных менеджеров и несколько lockfile
• Сборки зависят от глобальных CLI (есть на машине одного разработчика, отсутствуют в CI)
• Docker или runtime‑образы не зафиксированы (например, используется latest)

Быстрый чеклист перед тем, как доверять сборке

Прежде чем тратить ещё день на «починку CI», убедитесь, что проект собирается с нуля на чистой машине. Если там он падает — рано или поздно упадёт в продакшене.

5 проверок, которые ловят большую часть дрейфа

Начните с теста чистого клона. На новом ноутбуке или в чистой временной папке (без старого node_modules) выполните установку, сборку и тесты точно так, как написано в репозитории. Если нужны дополнительные шаги, которые не задокументированы — у вас ещё нет надёжной сборки.

Подтвердите версии. Версия Node.js и версия пакетного менеджера должны совпадать с тем, что ожидает репозиторий, а не с тем, что установлено глобально.

Проверьте lockfile. Должен быть ровно один lockfile, он должен быть в коммите и меняться только при намеренном обновлении зависимостей.

Убедитесь, что CI ставит детерминированно. CI должен использовать команду чистой установки для вашего инструмента (например, npm ci вместо npm install), чтобы не переписывать молча lockfile и не подтягивать новые транзитивные пакеты.

Проверьте, что продакшен совпадает с тем, что собрал CI. Рантайм‑версия Node в продакшене должна совпадать с зафиксированной, а деплой должен доставлять тот же выход сборки, который создал CI (а не пересобирать с другой средой).

Пример: стабилизация унаследованного AI‑прототипа

Основатель получил Node‑приложение, сгенерированное AI. Оно работает на ноутбуке оригинального разработчика, но CI падает с расплывчатыми ошибками вроде "Cannot find module", "Unsupported engine" или тесты проходят локально и падают в CI.

После быстрой проверки картина знакомая:

• Локально — Node 20, CI — Node 18, продакшен — Node 16
• Нет lockfile (или он игнорируется), так что каждая установка подтягивает чуть разные версии зависимостей
• CI восстанавливает кешированные зависимости, поэтому он никогда не ведёт себя как чистая машина

Исправление простое: сделать сборку детерминированной и заставить все окружения следовать ей.

Зафиксируйте Node.js (и пакетный менеджер), добавьте или восстановите lockfile, переключите установки в CI в строгий режим и выполните как минимум одну холодную установку локально (удалите node_modules, заново установите), чтобы убедиться, что ваш ноутбук не маскирует проблемы.

Цель скучная, но правильная: один и тот же коммит даёт одинаковое дерево зависимостей и одинаковый результат сборки везде.

Следующие шаги, если унаследованная сборка всё ещё нестабильна

Если после базовых шагов вы всё ещё видите "works on my machine" баги, не меняйте сразу пять вещей. Стандартизируйте в строгом порядке: сначала версии, затем lockfile, потом правила CI. Каждый шаг должен убирать переменные.

Запишите, что вы признаёте как истину для этого репозитория: версия Node.js, пакетный менеджер и его версия, и одна команда установки, которую обязаны использовать все. Держите набор правил маленьким и видимым.

Если кодовая база сама по себе грязная (особенно AI‑сгенерированные прототипы), воспроизводимые сборки — это первая задача по ремонту, а не опция. Пока сборки непредсказуемы, любые другие исправления сложнее проверить.

Если нужно быстрое решение, FixMyMess (fixmymess.ai) фокусируется на приведении сломанных AI‑сгенерированных приложений в продакшен‑состояние. Бесплатный аудит кода может показать, откуда идёт дрейф (версии, lockfile, скрытые скрипты), после чего команда может исправить сборку и основные проблемы за один проход.