Переезд на новый LTS Node.js: что проверить до обновления
- Как выбрать целевую версию Node.js в статусе Active LTS или Maintenance LTS
- Как проверить lock-файл и воспроизвести установку зависимостей через npm ci
- Как выявить устаревшие API в собственном коде по типам deprecation
- Чек-лист решений, которые нужно принять до выкладки на новый LTS
Обновление Node.js до нового LTS обычно выглядит как одна строка в конфиге сборки. Пока приложение крутится на старой версии, всё предсказуемо, и кажется, что достаточно поменять номер версии и перезапустить. Проблемы всплывают позже: установка зависимостей падает на чистой машине, сборка выдаёт предупреждения, а часть кода обращается к API, который в новой версии помечен как устаревший.
Ниже — порядок проверок до выкладки: зафиксировать целевую версию, воспроизвести установку зависимостей и собрать предупреждения об устаревших API. Это редакционный чек-лист Deskforge, а не отчёт об испытании продукта и не клиентский кейс: шаги нужно адаптировать к вашему стеку и вашим зависимостям. Смежная тема — проверка npm-зависимости перед установкой, а варианты работ с сайтами и кабинетами собраны на странице контента и сайтов.
Зачем фиксировать целевую версию LTS до обновления
Первое решение — не «обновиться на последнюю», а выбрать конкретную версию и записать её. Документация Node.js прямо говорит: для production-приложений следует использовать только релизы в статусе Active LTS или Maintenance LTS. Версия в статусе Current для рабочего контура не предназначена.
Статус LTS обычно означает, что критические ошибки будут исправляться в течение суммарно 30 месяцев. Формулировка «обычно» важна: это не жёсткая гарантия для каждого релиза, а общее правило, и точные даты нужно смотреть в расписании релизов на странице версий.
Понимание цикла помогает планировать. Каждая мажорная версия проводит шесть месяцев в статусе Current — это время даётся авторам библиотек, чтобы добавить поддержку новой версии. Значит, к моменту перехода в LTS часть зависимостей может ещё не быть готовой, и это стоит проверить заранее.
Есть и заявленное изменение на будущее: начиная с Node.js 27 цикл релизов станет ежегодным, и каждая мажорная версия будет переходить в LTS после шести месяцев Current и шести дополнительных месяцев Alpha. Это описание будущего порядка, а не текущего состояния уже выпущенных версий, поэтому для сегодняшнего переезда ориентируйтесь на действующее расписание.
Как проверить lock-файл и установку зависимостей через npm ci
Вторая проверка — воспроизводимая установка. Именно здесь чаще всего и обнаруживается, что локально всё работало, а на чистой машине сборка не стартует. Инструмент для этого — npm ci, и у него есть условия, которые нужно знать до запуска.
npm ci требует наличия существующего package-lock.json или npm-shrinkwrap.json. Если lock-файла нет, команда не заменит его генерацией — сначала нужно получить его обычной установкой и закоммитить.
Дальше — рассинхронизация. Если зависимости в package-lock не совпадают с package.json, npm ci завершится с ошибкой вместо того, чтобы обновить lock-файл. Это и есть проверка: успешный прогон подтверждает, что оба файла согласованы, а ошибка показывает, где расхождение.
Поведение команды стоит держать в голове.
Если папка node_modules уже есть, npm ci удалит её перед началом установки. И команда никогда не записывает изменения в package.json или lock-файлы: установка по сути заморожена. Поэтому прогон в изолированной среде честно повторяет то, что получит CI или сервер.
Отдельный случай — флаги. Если package-lock.json создавался с флагами, влияющими на форму дерева зависимостей, например --legacy-peer-deps или --install-links, те же флаги нужно передать и в npm ci, иначе вероятны ошибки. Сверьте флаги, с которыми создавался lock-файл, с теми, что передаёте в проверочный прогон.
Как выявить устаревшие API по типам deprecation
Третья проверка — собственный код. В Node.js существует четыре вида deprecation: documentation-only, application (только код вне node_modules), runtime (весь код) и End-of-Life. Различать их важно, потому что ведут они себя по-разному.
Application deprecation по умолчанию выводит предупреждение в stderr при первом использовании устаревшего API в коде, загруженном не из node_modules. То есть предупреждения из ваших файлов вы увидите и без дополнительных флагов — их стоит собрать из вывода сборки и тестов.
С зависимостями иначе. При использовании флага --pending-deprecation предупреждения также выводятся для кода, загруженного из node_modules. Без этого флага предупреждения из библиотек по умолчанию не показываются, и картина будет неполной.
Есть и более строгий режим.
При использовании флага --throw-deprecation runtime deprecation приводит к выбрасыванию ошибки. Это превращает предупреждение в падение, поэтому такой прогон лучше делать отдельно от обычной сборки и осознанно.
Не все виды deprecation одинаково управляемы. Documentation-only deprecation, поддерживающие флаг --pending-deprecation, явно помечены как таковые в списке устаревших API — по этой пометке и понятно, чего ждать от флага.
Чек-лист решений перед выкладкой на новый LTS
Соберём проверки в один проход, который выполняется до выкладки, а не после. Сначала зафиксируйте целевую версию: она должна быть в статусе Active LTS или Maintenance LTS, а не Current. Запишите номер версии в конфигурацию сборки и в план переезда, чтобы проверки шли на той же версии, что пойдёт в работу.
Затем воспроизведите установку. Убедитесь, что package-lock.json существует и закоммичен, запустите npm ci в изолированной среде и добейтесь, чтобы команда не падала на рассинхронизации с package.json. Сверьте флаги, с которыми создавался lock-файл, с флагами проверочного прогона.
После этого соберите предупреждения. Прогоните сборку и тесты, соберите предупреждения об устаревших API из кода вне node_modules, затем повторите прогон с --pending-deprecation, чтобы увидеть предупреждения из зависимостей. Решите заранее, нужен ли отдельный прогон с --throw-deprecation, и зафиксируйте это решение в плане.
Смысл порядка простой: каждая проверка отвечает на свой вопрос. Версия — на вопрос «куда переезжаем и поддерживается ли она». npm ci — на вопрос «соберётся ли установка с нуля». Deprecation — на вопрос «что в коде и зависимостях уже помечено как устаревшее». Если все три ответа получены до выкладки, переезд перестаёт быть лотереей.