Коротко о главном
Node.js удобен для API, инструментов командной строки и фронтенд-сборки. Пакетный менеджер npm входит в стандартную поставку и описывает проект в package.json. В статье разберём установку, создание приложения, зависимости и воспроизводимую установку в CI. Примеры используют обычный Linux-терминал и не требуют глобальных фреймворков.
Единая среда JavaScript упрощает разработку клиента и сервера. npm даёт доступ к огромной экосистеме библиотек и готовых скриптов. package-lock.json фиксирует дерево зависимостей для повторяемых сборок. Node.js также часто используется для локальных инструментов и автоматизации.
Большинство проблем с nodejs сводится к нескольким повторяющимся ошибкам. Ниже — что проверить в первую очередь и как не усугубить ситуацию.
Почему это происходит
Ошибки почти всегда связаны с контекстом: другая версия пакета, не тот пользователь, устаревший конфиг или команда из руководства для другой системы. nodejs не исключение. Поэтому сначала фиксируем исходное состояние, затем меняем одну вещь за раз.
Типичные ошибки
Ниже — сбои, которые встречаются чаще всего. Перед исправлением сохраните текущие конфиги и запишите, какие изменения вносите: так проще откатиться.
1. npm install -g завершается ошибкой EACCES.
Не используйте sudo для npm. Настройте пользовательский prefix или применяйте npx для разовых инструментов.
2. При запуске появляется Cannot find module.
Установите зависимости командой npm install и проверьте имя модуля. Убедитесь, что команда выполняется в каталоге проекта.
3. Пакет требует другую версию Node.js.
Проверьте поле engines и переключитесь на поддерживаемую LTS-версию. Обновите зависимости или Node.js в зависимости от требований проекта.
4. Сервер завершается с ошибкой EADDRINUSE.
Порт уже занят другим процессом. Найдите его через ss -ltnp и остановите процесс либо задайте другой порт через переменную окружения.
Как настроить правильно
Правильная последовательность проста: проверить версию и зависимости, сделать резервную копию конфигурации, внести минимальное изменение, проверить логи и только потом двигаться дальше.
Установка
В Debian, Ubuntu и Linux Mint используется пакетный менеджер APT:
sudo apt install nodejs npm
В Fedora и RHEL-совместимых системах пакет ставится через DNF:
sudo dnf install nodejs npm
В Arch Linux и производных пакет доступен в официальных репозиториях:
sudo pacman -S nodejs npm
1. Проверьте Node.js и npm
Убедитесь, что установлены обе команды и их версии совместимы. Для новых проектов выбирайте LTS-ветку Node.js. Версия npm влияет на поддержку команд npm pkg и npm ci.
node --version
npm --version
2. Создайте проект
npm init -y создаёт package.json с настройками по умолчанию. Команда npm pkg set позволяет изменить поле без ручного редактирования. Значение type=module включает современный синтаксис import.
mkdir demo-app && cd demo-app
npm init -y
npm pkg set type=module
3. Установите зависимости
Обычная зависимость нужна приложению во время работы. Флаг —save-dev добавляет пакет только для разработки и проверок. npm создаёт package-lock.json с точными версиями.
npm install express
npm install --save-dev eslint
4. Запустите скрипт проекта
Скрипты из package.json запускаются через npm run. Короткая форма npm start работает для стандартного скрипта start. Создайте простой index.js, чтобы проверить настройку.
printf 'console.log("ok")\n' > index.js
npm start
Рабочий конфиг
Начните с минимального рабочего варианта. Не копируйте большой конфиг целиком: добавляйте параметры по одному и проверяйте результат после каждого изменения.
{
"name": "demo-app",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"start": "node index.js",
"test": "node --test"
}
}
Практические советы
Эти рекомендации проверены на повседневных задачах. Начните с тех, которые закрывают вашу текущую боль, а не со всего списка сразу.
Совет 1. Выбирайте LTS-версию Node.js для рабочих проектов и проверяйте срок по
Выбирайте LTS-версию Node.js для рабочих проектов и проверяйте срок поддержки.
Совет 2. Коммитьте package-lock.json: без него npm ci не сможет воспроизвести у
Коммитьте package-lock.json: без него npm ci не сможет воспроизвести установку.
Совет 3. Используйте npm ci в CI, а npm install — при активной разработке завис
Используйте npm ci в CI, а npm install — при активной разработке зависимостей.
Совет 4. Добавляйте node_modules и .env в .gitignore, чтобы не хранить зависимо
Добавляйте node_modules и .env в .gitignore, чтобы не хранить зависимости и секреты в репозитории.
Профилактика
Большинство повторяющихся сбоев с nodejs связано не с ошибкой в самой программе, а с окружением: обновились зависимости, изменился путь, закончилось место или другой администратор поправил конфиг. Поэтому профилактика начинается с фиксации исходного состояния.
Сохраните рабочий конфиг в систему контроля версий, добавьте короткий комментарий о том, зачем нужен каждый нестандартный параметр, и запишите команду проверки. Через месяц вы скажете себе спасибо: восстановить логику по чужому файлу без пояснений почти невозможно.
Чек-лист
- Версия пакета и конфигурация зафиксированы и доступны для сравнения.
- Есть автоматическая проверка синтаксиса перед перезапуском службы.
- Журналы ротуются, а диск не заполняется ими за неделю.
- Изменения проходят через тестовый стенд, а не сразу на рабочий сервер.
Итог
Большинство ошибок с nodejs лечится не переустановкой, а проверкой конфигурации, логов и прав доступа. Действуйте по одному изменению за раз — и причина быстро найдётся.