Что будешь делать когда код не поменялся при нарушении сборки?

Стратегия диагностики и устранения сбоя сборки при неизменном коде

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

1. Первичный анализ ошибки

Первым делом внимательно изучаю логи сборки (build logs). Ключевые моменты:

• Точное сообщение об ошибке (error message, stack trace).
• Шаг, на котором упала сборка (например, npm run build, webpack compilation, TypeScript type checking).
• Код ошибки (например, ERR_MODULE_NOT_FOUND, Cannot read property).

Пример типичного логирования:

> webpack --mode production

ERROR in ./src/index.js
Module not found: Error: Can't resolve 'lodash' in '/project/src'

2. Проверка очевидных причин

Запускаю чек-лист быстрых проверок:

• Состояние зависимостей:

    *   `node_modules` — не был ли случайно изменён или удалён?
    *   `package-lock.json` / `yarn.lock` — актуален ли? Не было ли частичного обновления?
    *   Проверяю целостность: `npm ci` (чистая установка) вместо `npm install`.

• Проблемы кэширования:

    *   Очищаю кэш сборщика: `npm run clean` или `rm -rf dist/build`.
    *   Очищаю кэш пакетного менеджера: `npm cache clean --force`.
    *   Очищаю кэш компилятора (например, для TypeScript: `tsc --build --clean`).

• Состояние окружения:

    *   Версии Node.js и npm/yarn: `node -v`, `npm -v`. Не обновились ли они?
    *   Глобальные зависимости (если используются): версии CLI-инструментов.
    *   Переменные окружения (env variables) — не изменились ли?

3. Глубокая диагностика

Если быстрые проверки не помогли, перехожу к детальному анализу.

• Сравнение с рабочей версией: Использую git status и git diff для проверки, что действительно не было изменений в коде, конфигах или lock-файлах. Иногда проблема в незакоммиченных изменениях.
• Анализ графа зависимостей: Команды вроде npm ls <package-name> помогают найти конфликты версий.
• Изоляция проблемы:

    *   Пробую собрать проект на другой машине или в чистом контейнере (Docker).
    *   Пробую откатить **только зависимости** к более раннему состоянию через `git checkout` lock-файла и переустановку.
    *   Запускаю сборку с флагами повышенной детализации (например, `webpack --stats verbose`).

• Проверка сторонних сервисов: Если сборка зависит от внешних ресурсов (CDN, API), проверяю их доступность.

4. Практические примеры и решения

Рассмотрим частые сценарии:

Сценарий 1: «Плавающая» ошибка из-за семантического версионирования. В package.json: "lodash": "^4.17.21". Автор минорной версии 4.18.0 мог внести breaking change.

• Решение: Фиксируем версию в package-lock.json. Выполняем npm ci для точного восстановления. В идеале — переходим на детерминированные сборки с использованием Docker-образов.

Сценарий 2: Сломанный кэш Babel/Webpack.

• Решение: Очистка кэша и удаление выходных директорий.

# Для Create React App
npm run clean или rm -rf ./build ./node_modules/.cache

# Для Webpack с кэшированием
rm -rf ./node_modules/.cache/webpack

Сценарий 3: Изменение в глобальном окружении CI/CD. На сервере сборки обновили Node.js с 16 на 18, и некоторые нативные модули сломались.

• Решение: Явно задать версию Node.js в конфигурации CI (например, в .github/workflows/ci.yml или .nvmrc-файле).

5. Профилактика проблем

Чтобы минимизировать такие инциденты, внедряю следующие практики:

• Детерминированность сборок: Использование package-lock.json / yarn.lock (коммитить их в репозиторий!). Идеально — контейнеризация (Docker).
• Непрерывная интеграция (CI): Настройка CI-пайплайна, который запускает сборку на каждом коммите. Это быстро выявляет проблемы окружения.
• Монорепозитории с инструментами вроде Nx или Turborepo: Они имеют продвинутые системы кэширования, основанные на хэшах файлов, что делает сборки более предсказуемыми.
• Документация: Чёткое описание необходимого окружения (версии Node.js, npm, глобальных пакетов) в README.md.

Итог: Падение сборки при неизменном коде — это почти всегда сигнал о недетерминированности процесса. Мои действия направлены на поиск источника нестабильности (кэш, зависимости, окружение) и его устранение, с последующим укреплением процесса сборки для предотвращения повторения. Ключевой принцип: сборка должна быть воспроизводимой на любой машине в любой момент времени.