Node.js працює локально, але падає в CI: як синхронізувати версії

Пів години до релізу, а версії різні

Виправлення вже готове, локальні тести проходять, але CI падає під час встановлення нативного модуля. Розробник перевіряє свою версію Node.js і бачить, що runner використовує іншу. Яка версія працює в бойовому середовищі, ніхто одразу не знає.

Пів години до релізу швидко перетворюються на пошук Dockerfile, налаштувань CI та старих домовленостей у чаті. Проблема тут не в одному зламаному тесті. Команда втратила спільну відповідь на просте запитання: яке середовище виконання має використовувати застосунок?

Графік релізів Node.js допомагає повернути цю відповідь. Але він не наказує негайно переходити на найновішу гілку. Це зовнішній календар, на основі якого команда може планувати перевірки, оновлення та завершення підтримки старих версій.

Спочатку зберіть факти

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

Перевірте щонайменше:

• ноутбуки розробників: .nvmrc, .node-version, менеджер версій і результат node --version;
• репозиторій: поле engines у package.json та документацію запуску;
• CI: версію в конфігурації job, образ runner і фактичний вивід node --version;
• контейнери: базовий образ у Dockerfile, його тег і дайджест;
• serverless або керовану платформу: версію в налаштуваннях функції чи сервісу;
• бойове середовище: process.version у внутрішньому стартовому журналі застосунку.

Налаштування і реальність можуть відрізнятися. Наприклад, Dockerfile уже змінений, але сервер досі запускає старий образ. Тому записуйте не лише очікувану, а й фактично побачену версію.

Читайте статус гілки, а не лише номер

Офіційний анонс Node.js описує розвиток графіка релізів. Офіційна стрічка блогу станом на 20 липня показує паралельну активність гілок 22, 24 і 26, зокрема реліз Node.js 26.5.0 від 8 липня. Сам факт появи новішої версії не означає, що вона автоматично є правильною ціллю для кожного сервісу.

Для поточної та цільової гілок знайдіть в офіційному графіку їхній статус і контрольні дати. Не вгадуйте підтримку за парністю або величиною номера. Позначка LTS також не скасовує тестування вашого коду, залежностей і платформи.

Потім команда має додати власні правила. Наприклад: планові оновлення оцінюються щомісяця, перехід на погоджену гілку завершується за визначений строк, а термінові виправлення безпеки мають окремий коротший SLA. Це редакційний приклад командної політики, а не правило проєкту Node.js.

Перевірте стару й нову версії поруч

Додайте до CI тимчасову матрицю з поточною та цільовою версіями. Точний синтаксис залежить від вашої системи, але логіка проста:

strategy:
  matrix:
    node: [current, target]

У кожній гілці матриці виконайте чисте встановлення залежностей, збірку, модульні та інтеграційні тести. Окремо перевірте фонові задачі, обробники черг і сценарії командного рядка, якщо вони не покриті звичайним тестовим запуском.

Нативний модуль може використати артефакт, зібраний для іншої версії Node.js. Очистьте відповідний кеш і переконайтеся, що ключ кешування враховує основну версію Node.js, операційну систему та архітектуру. Не лікуйте помилку копіюванням каталогу node_modules із ноутбука, де все працює.

Не поєднуйте оновлення середовища виконання з великим рефакторингом і десятками непов’язаних оновлень залежностей. Якщо тест упаде, менша зміна допоможе швидше знайти причину.

Перебудуйте образ і підготуйте відкат

Після успішного CI створіть новий контейнерний образ із цільовою версією Node.js. Не покладайтеся лише на рухомий тег на кшталт latest. Запишіть тег і дайджест образу застосунку, а базовий образ закріпіть способом, який підтримує ваш процес оновлень.

Підготуйте попередній стабільний образ до повторного розгортання. Відкат має бути конкретною дією, а не фразою «повернемо стару версію». Зафіксуйте потрібний дайджест, команду розгортання та людину, яка ухвалює рішення. Не додавайте до тієї самої зміни незворотну міграцію бази даних, якщо вона унеможливить швидке повернення.

Дайте новій версії невелику частину навантаження

Канаркове розгортання — це командна рекомендація, а не вимога графіка Node.js. Запустіть новий образ на одному екземплярі або невеликій частці трафіку. Перевірте старт процесу, основні HTTP-маршрути, роботу з базою даних, черги, пам’ять, частоту помилок і тривалість відповідей.

До початку визначте умови відкату: повторювані помилки, невдала базова перевірка, різке зростання затримки або споживання пам’яті. Без таких умов канарка лише відкладає суперечку про те, чи достатньо серйозна проблема.

Завершуйте міграцію доказами

Оновлення завершене не тоді, коли змінили один файл, а коли команда може показати:

• версію Node.js у стартовому журналі кожного сервісу;
• дайджест образу, реально розгорнутого в бойовому середовищі;
• успішні базові перевірки після розгортання;
• стабільні ключові метрики протягом погодженого часу;
• оновлену таблицю без невідомих або забутих середовищ.

Найгірші скорочення шляху — оновити лише CI, використовувати плаваючий тег, визначити підтримку за номером версії або залишити знання про бойове середовище в пам’яті однієї людини. Календар Node.js стає корисною політикою лише тоді, коли пов’язаний із власником, строком, перевіркою та доказом фактичного розгортання.

Джерела

• https://nodejs.org/en/blog/announcements/evolving-the-nodejs-release-schedule
• https://nodejs.org/en/feed/blog.xml