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

Офіційний приклад не гарантує однаковий результат

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

Це не обов’язково помилка в коді чи ознака неуважності. У браузері може бути відкрита документація для однієї версії Node.js, на ноутбуці встановлена інша, а контейнер або робочий сервер може запускати третю.

Починати варто не з переписування прикладу, а з найпростішої перевірки:

node --version
node -p 'process.execPath'

Перша команда показує версію середовища виконання. Друга допомагає визначити, який саме виконуваний файл Node.js запустила поточна оболонка.

Три факти, які легко переплутати

24 липня 2026 року проєкт Node.js оголосив бета-версію нової API-документації. Це був анонс попереднього перегляду документації, а не реліз середовища виконання Node.js, тому він сам по собі нічого не оновлює у вашому застосунку.

API, або програмний інтерфейс, — це набір функцій, класів та інших можливостей, до яких може звертатися програма. Під час перевірки розділяйте три факти:

1. Який інтерфейс документації відкритий у браузері.
2. Для якої версії Node.js сторінка описує API та який статус указано для потрібної можливості.
3. Яка версія Node.js фактично запускає код.

Позначка beta на інтерфейсі документації сама по собі не визначає статус конкретного API. Так само новий вигляд документації не робить новий API доступним у старішому середовищі виконання.

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

Складіть карту версій

У наскрізному сценарії приклад працює на ноутбуці, але падає в CI. Запишіть фактичні значення, а не очікувані. PATH — це перелік каталогів, у яких оболонка шукає виконувані файли, зокрема node.

Середовище	Фактична версія	Звідки вона береться	Результат тесту
Ноутбук	[результат]	інструмент вибору версії або PATH	[результат]
CI	[результат]	конфігурація завдання	[результат]
Контейнерний образ	[результат]	зібраний образ	[результат]
Робоче середовище	[результат]	розгорнутий артефакт	[результат]

Для CI тимчасово виведіть node --version перед тестами. Якщо контейнерний образ дає змогу передати іншу команду, перевірте той самий образ, який плануєте розгортати:

docker run --rm <image> node --version

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

Далі перегляньте .nvmrc, .node-version, поле engines у package.json, крок налаштування Node.js у CI та рядок FROM у Dockerfile. У багатостадійному Dockerfile важливий етап, який формує фінальний образ, а не обов’язково перший FROM.

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

Якщо прямий доступ до сервера обмежений, отримайте process.version із дозволеної діагностики застосунку або журналу запуску. Звичайна команда в інтерактивній оболонці може знайти інший виконуваний файл, ніж той, який використовує службовий процес.

Звірте документацію з реальною версією

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

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

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

Підтвердьте API мінімальним тестом

Наведений нижче шаблон перевіряє лише наявність експорту в модулі. Він не є універсальною перевіркою глобального API, методу об’єкта чи конкретної поведінки. Замініть заповнювачі:

const moduleName = 'node:MODULE_NAME';
const exportName = 'EXPORT_NAME';

const mod = await import(moduleName);

if (!(exportName in mod)) {
  throw new Error(`Missing ${exportName} in ${moduleName} on ${process.version}`);
}

console.log(`Available on ${process.version}`);

Запустіть файл тим Node.js, який перевіряєте:

node check-api.mjs
docker run --rm -v "$PWD:/work" -w /work <image> node check-api.mjs

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

Для глобального API перевірте відповідну властивість глобального об’єкта globalThis. Для методу перевіряйте об’єкт, якому цей метод має належати. Відсутність названого експорту в наведеному шаблоні не доводить відсутності API, якщо документація описує інший спосіб доступу до нього.

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

Не експериментуйте безпосередньо на робочому сервері. Спочатку виконайте перевірку в CI або тестовому середовищі з тим самим контейнерним образом, який плануєте розгортати. Якщо API критичний, залиште відповідний мінімальний тест у CI. Тоді зміна версії Node.js, образу чи налаштувань CI зможе дати цілеспрямовану помилку до розгортання.

Антипатерни, які приховують проблему

• Посилатися лише на головну сторінку документації без версійного контексту.
• Вважати latest надійним способом відтворити однакове середовище.
• Перевіряти API тільки на ноутбуці автора зміни.
• Сприймати engines у package.json як доказ встановленої версії.
• Плутати бета-версію інтерфейсу документації зі статусом конкретного API.
• Оновлювати робоче середовище лише тому, що приклад не запустився, не перевіривши наслідки переходу.
• Запускати неперевірений експеримент із сумісністю безпосередньо в робочому середовищі.

Перегляньте командні посилання

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

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

Головний принцип простий: сторінка в браузері є джерелом інформації, але фактичний результат визначає середовище виконання. Зафіксована карта версій, версійна документація та короткий цільовий тест перетворюють випадкову поломку на звичайну перевірку.

Джерела

• https://nodejs.org/en/blog/announcements/new-api-docs-beta
• https://nodejs.org/en/feed/blog.xml