Как исправить "ReferenceError: primordials не определен" в Node.js

Ошибка “ReferenceError: primordials is not defined” в Node.js обычно возникает при использовании Gulp.js версии 3 с Node.js 12 или новее из‑за несовместимости старого Gulp 3.x и новых версий Node.js. Эта ошибка появляется, потому что Gulp 3 зависит от graceful‑fs@3.0.0, который не поддерживает API primordials, введённый в Node.js 12+. Вы можете исправить её, либо обновив до Gulp 4, либо понизив Node.js до версии 10‑11, либо обновив зависимости проекта.

Содержание

• Понимание ошибки
• Анализ причины
• Решение 1: обновление до Gulp 4 (рекомендуется)
• Решение 2: понижение версии Node.js (быстрый фикс)
• Решение 3: альтернативные обходные пути
• Профилактика и лучшие практики

Понимание ошибки

Ошибка ReferenceError: primordials is not defined конкретно возникает в fs.js:27, где код пытается распаковать объект primordials:

const { Math, Object, Reflect } = primordials;

Это сообщение означает, что объект primordials, внутренний API Node.js, введённый в версии 12, недоступен в контексте, где выполняется код. Ошибка обычно проявляется при запуске команд Gulp, особенно gulp sass-watch, как в вашем случае.

Анализ причины

Основная причина — Gulp.js версии 3.x несовместим с Node.js 12 и новее. Согласно исследованию из Stack Overflow, Gulp 3.9.1 работает только с Node 8 (последняя 8.17.0) и ничего более.

Техническое разложение:

• Gulp 3 зависит от graceful-fs@3.0.0
• Эта версия graceful‑fs не поддерживает изменения в Node.js 12+
• Node.js 12 ввёл primordials как внутренний API
• Старые модули, как graceful‑fs@3.0.0, не имеют доступа к этому новому API
• При попытке загрузки этих модулей Node.js падает, потому что primordials не определён

Как подтверждает документация Microsoft SPFX, «Gulp v3 не поддерживается с Node.js v12+. Это не изменение в SPFx. Это упомянуто здесь, чтобы привлечь внимание, поскольку это релиз SPFx добавляет поддержку Node.js v12».

Решение 1: обновление до Gulp 4 (рекомендуется)

Почему это лучшее решение

Обновление до Gulp 4 — это долгосрочный фикс и рекомендуемый подход, потому что он обеспечивает:

• Полную совместимость с текущими версиями Node.js
• Улучшенную производительность и новые возможности
• Активное сопровождение и обновления безопасности
• Будущую совместимость разработки

Пошаговый процесс обновления

1. Удалите старый Gulp глобально и локально:

   bash

   npm uninstall gulp gulp-cli -g
   npm uninstall gulp gulp-cli
   

2. Установите Gulp 4 глобально:

   bash

   npm install -g gulp-cli
   

3. Установите Gulp 4 локально:

   bash

   npm install gulp@4 --save-dev
   

4. Обновите ваш gulpfile.js под синтаксис Gulp 4:

   javascript

   const gulp = require('gulp');
   const sass = require('gulp-sass');
   
   // Определяем задачу
   function sassWatch() {
     return gulp.src('src/scss/**/*.scss')
       .pipe(sass().on('error', sass.logError))
       .pipe(gulp.dest('dist/css'));
   }
   
   // Экспортируем задачу
   exports.sassWatch = sassWatch;
   
   // Задача по умолчанию
   exports.default = sassWatch;
   

5. Проверьте установку:

   bash

   gulp --version
   

   Вы должны увидеть версии Gulp CLI 4.x и локального Gulp 4.x.

Решение 2: понижение версии Node.js (быстрый фикс)

Когда использовать этот подход

Понижение Node.js — это быстрый фикс, рекомендованный для:

• Устаревших проектов, которые сложно мигрировать до Gulp 4
• Команд с ограниченным временем на крупные рефакторинги
• Проектов со сложными рабочими потоками Gulp 3

Пошаговый процесс понижения

1. Проверьте текущую версию Node.js:

   bash

   node --version
   

2. Установите Node Version Manager (nvm), если его нет:

   bash

   # Для macOS/Linux
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   
   # Для Windows (используя nvm-windows)
   # Скачайте с: https://github.com/coreybutler/nvm-windows/releases
   

3. Установите и используйте Node.js 11.x или 10.x:

   bash

   # Установить Node.js 11.x
   nvm install 11
   
   # Или установить Node.js 10.x
   nvm install 10
   
   # Переключиться на установленную версию
   nvm use 11
   

4. Проверьте понижение:

   bash

   node --version
   

5. Переустановите зависимости проекта:

   bash

   rm -rf node_modules package-lock.json
   npm install
   

Примечание: Согласно исследованию из r/node на Reddit, «использование nvm для получения node 10 устранило ошибку primordials, но теперь появляются ошибки о недостающих именах в некоторых файлах node_modules, например «Cannot find name ‘bigint’» и «Cannot find name ‘AsyncIterableIterator’».

Решение 3: альтернативные обходные пути

Метод А: Очистка lock‑файла

Иногда повреждённый package-lock.json может вызывать проблемы совместимости:

rm package-lock.json
rm -rf node_modules
npm install

Метод B: Создание npm-shrinkwrap.json

Как предложил TimOnWeb, вы можете создать файл npm-shrinkwrap.json, чтобы закрепить версии зависимостей:

npm shrinkwrap

Метод C: Обновление npm и обеспечение совместимости

Согласно CodeForGeek, обновление npm и проверка совместимости могут помочь:

npm install -g npm@latest
npm audit fix

Метод D: Альтернативные инструменты сборки

Рассмотрите замену Gulp на современные альтернативы:

• Vite – быстрый инструмент сборки
• Webpack – модульный бандлер
• Parcel – бандлер без конфигурации

Профилактика и лучшие практики

Регулярное обновление зависимостей

1. Используйте npm outdated для проверки обновлений:

   bash

   npm outdated
   

2. Тестируйте совместимость перед крупными обновлениями:

   bash

   npm install node@latest --dry-run
   

Структура проекта

1. Используйте .npmrc для принудительного указания версии Node.js:

   ini

   engine-strict=true
   engines={
     "node": ">=14.0.0 <15.0.0",
     "npm": ">=6.0.0"
   }
   

2. Добавьте скрипты для проверки совместимости:

   json

   {
     "scripts": {
       "preinstall": "node -e \"if (parseInt(process.version.split('.')[0]) < 14) console.log('Warning: Node.js version < 14 may cause compatibility issues')\"",
       "test": "npm run test:build && npm run test:lint"
     }
   }
   

Стратегия миграции

Для существующих проектов с Gulp 3:

1. Этап 1: Тестируйте совместимость Gulp 4 в отдельной ветке
2. Этап 2: Пошагово мигрируйте задачи под синтаксис Gulp 4
3. Этап 3: Удалите зависимости Gulp 3
4. Этап 4: Обновите документацию и знания команды

Заключение

Ошибка “ReferenceError: primordials is not defined” в основном является проблемой совместимости между Gulp 3 и современными версиями Node.js. Ключевые выводы:

1. Для новых проектов: всегда используйте последние стабильные версии Node.js и инструменты сборки, такие как Gulp 4.
2. Для устаревших проектов: выбирайте между обновлением до Gulp 4 (рекомендуется) или понижением Node.js (быстрый фикс).
3. Профилактика: регулярные обновления зависимостей и проверки совместимости помогут избежать подобных ошибок.
4. Долгосрочное решение: переход на современные инструменты сборки обеспечивает лучшую производительность, безопасность и поддержку.

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