Node.js не запускается: что означает ошибка «node: command not found» и как её исправить

Вчера проект спокойно запускался через npm run dev, а сегодня терминал отвечает:

//text

node: command not found

Первая мысль обычно простая: Node.js удалился или установка каким-то образом слетела.

Но есть нюанс. Эта ошибка не говорит, что Node.js обязательно отсутствует на компьютере. Она говорит только о том, что текущая оболочка не нашла команду node.

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

Сначала проверяем, что именно сломалось

Я бы не начинал с переустановки. Сначала стоит дать терминалу несколько простых команд.

//bash

node -v

Если получаем:

//text

zsh: command not found: node

или:

//text

bash: node: command not found

проверяем, существует ли команда в текущем окружении:

//bash

command -v node

На Linux и macOS отсутствие вывода обычно означает, что node не найден через текущий PATH.

Можно посмотреть и сам PATH:

//bash

echo $PATH

PATH - это список каталогов, в которых оболочка ищет исполняемые программы. Когда мы пишем:

//bash

node

терминал не перебирает весь диск в поисках файла с таким названием. Он смотрит в определённые каталоги из PATH.

Поэтому вполне возможна ситуация:

//text

Node.js установлен
        ↓
node находится на диске
        ↓
каталог с node не попал в PATH
        ↓
терминал отвечает "command not found"

Именно здесь находится одна из самых частых причин проблемы.

Node.js установлен, но терминал его не видит

Особенно часто такое происходит после установки Node.js через менеджер версий.

Например, разработчик использует nvm:

//bash

nvm install 24

После установки:

//bash

nvm use 24

И всё работает:

//bash

node -v

//text

v24.x.x

А затем закрывается Terminal, открывается новое окно - и снова:

//text

node: command not found

Причина в том, что nvm работает на уровне текущей shell-сессии. Он должен быть загружен при запуске оболочки, а нужная версия Node.js должна быть активна. В документации nvm отдельно описана именно такая ситуация: после установки менеджера версий иногда требуется загрузить настройки shell или открыть новый терминал.

Проверяем:

//bash

command -v nvm

Если команда ничего не возвращает, проблема уже не в Node.js. Терминал не знает даже о nvm.

Для zsh можно проверить загрузку конфигурации:

//bash

source ~/.zshrc

Для bash:

//bash

source ~/.bashrc

После этого:

//bash

command -v nvm

Если появился путь или команда начала определяться, пробуем:

//bash

nvm current

и:

//bash

node -v

Почему после установки Node.js иногда достаточно перезапустить терминал

Когда устанавливается nvm, его настройки обычно добавляются в файл конфигурации shell. Например, используется примерно такая конструкция:

//bash

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

После этого новый процесс shell получает возможность загрузить nvm.

Но уже открытый терминал сам по себе не обязан перечитывать изменённый .zshrc или .bashrc.

Поэтому после установки может быть достаточно открыть новое окно терминала.

Либо загрузить конфигурацию вручную:

//bash

source ~/.zshrc

После чего:

//bash

nvm use --lts
node -v
npm -v

Это как раз тот случай, когда переустановка Node.js ничего не даст. Node уже был установлен - проблема была в том, что текущая shell-сессия не знала, где его искать.

А если nvm работает, а node всё равно не найден?

Тогда смотрим, какие версии Node.js вообще установлены:

//bash

nvm ls

Например, можно увидеть:

//text

       v20.20.0
->     v24.14.0
default -> 24

Если версия есть, активируем её:

//bash

nvm use 24

Затем:

//bash

node -v

Если Node появился - причина найдена.

Можно сделать конкретную версию используемой по умолчанию:

//bash

nvm alias default 24

После этого новая shell-сессия должна выбирать указанную версию.

Но здесь есть ещё одна ловушка.

nvm может быть установлен в одном shell, а команда запускается в другом

Это особенно неприятный случай.

Допустим, в одном окне терминала:

//bash

nvm use 24

работает.

А затем команда запускается из IDE, скрипта или другого shell-процесса:

//bash

node app.js

и появляется:

//text

node: command not found

Выглядит так, будто Node периодически ломается. На самом деле два процесса могут использовать разные окружения.

Для диагностики полезно посмотреть:

//bash

echo $SHELL

и:

//bash

command -v node

А затем сравнить результат в обычном Terminal и в том месте, откуда запускается проект.

Например, если Terminal показывает:

//text

/Users/user/.nvm/versions/node/v24.14.0/bin/node

а IDE запускает процесс без этого каталога в PATH, поведение будет отличаться.

Это одна из причин, почему проблема иногда проявляется не при обычном запуске:

//bash

node server.js

а только внутри IDE, Docker, CI или другого инструмента.

Если Node установлен без nvm

Не все используют менеджеры версий. Node.js можно установить системным пакетом, Homebrew и другими способами.

В таком случае полезно сначала понять, где находится исполняемый файл.

На macOS или Linux:

//bash

find /usr/local /opt /usr -name node -type f 2>/dev/null

Команда может вернуть несколько путей, например:

//text

/usr/local/bin/node
/opt/homebrew/bin/node

Если файл существует, но:

//bash

command -v node

ничего не показывает, проблема действительно похожа на PATH.

Можно временно добавить нужный каталог:

//bash

export PATH="/usr/local/bin:$PATH"

И проверить:

//bash

node -v

Если Node заработал, остаётся сделать изменение постоянным, добавив соответствующую строку в конфигурацию shell.

Например, для zsh:

//bash

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Но я бы не советовал механически копировать этот путь. Сначала нужно установить реальный каталог, в котором находится node.

На Apple Silicon, например, Homebrew обычно использует другой путь, поэтому вариант /usr/local/bin может быть вообще не тем, что требуется.

Отдельно стоит проверить npm

Иногда разработчик смотрит только на node, хотя проекту нужны сразу две команды:

//bash

node -v
npm -v

Если обе не находятся:

//text

node: command not found
npm: command not found

это ещё один аргумент в пользу того, что проблема связана с окружением или установкой Node.js целиком.

Если node работает:

//text

v24.x.x

а npm нет:

//text

npm: command not found

ситуация уже другая. Не стоит чинить её теми же командами, что и отсутствие node.

При установке Node.js через nvm npm устанавливается вместе с используемой версией Node.js. Поэтому после переключения версии стоит проверять обе команды:

//bash

nvm use 24

node -v
npm -v

Самая полезная команда в этой ситуации

Есть команда, которую я бы вообще поставил в начало диагностики:

//bash

command -v node

Она лучше многих попыток «починить Node.js» тем, что ничего не меняет.

Мы просто задаём вопрос shell:

Какой node ты собираешься запускать?

Если получаем:

//text

/Users/user/.nvm/versions/node/v24.14.0/bin/node

значит команда найдена.

Если:

//text

node not found

или нет вывода - текущий PATH не содержит доступного node.

Дальше уже можно разбираться с конкретным способом установки.

Если недавно переключали версию Node.js

С nvm ошибка может появиться и после переключения версий.

Например:

//bash

nvm use 20

а затем:

//bash

node -v

работает.

Но после открытия нового терминала:

//bash

node -v

снова выдаёт ошибку.

Проверяем:

//bash

nvm current

Если увидели:

//text

system

а системного Node.js нет, shell фактически не выбрал установленную через nvm версию.

Можно явно активировать нужную:

//bash

nvm use 20

А затем установить её как версию по умолчанию:

//bash

nvm alias default 20

После открытия нового терминала:

//bash

node -v

должен вернуть выбранную версию.

При этом важно помнить: nvm - это shell-решение, а не обычная программа node. В частности, проверять его через which nvm не совсем корректно: nvm реализован как shell-функция, поэтому в официальной документации рекомендуется command -v nvm.

А если проблема появилась внезапно

Вот здесь я бы уже смотрел не на Node.js, а на то, что изменилось между рабочим и нерабочим состоянием.

Например:

• обновилась система;

• изменился .zshrc;

• появился новый .bash_profile;

• поменялся PATH;

• была удалена версия Node.js;

• переключился nvm;

• терминал начал запускать другой shell;

• проект стал запускаться из IDE;

• поменялось окружение Docker или CI.

Полезная привычка - не пытаться исправить всё сразу.

Сначала:

//bash

command -v node

потом:

//bash

node -v

затем, если используется nvm:

//bash

command -v nvm
nvm current
nvm ls

и только после этого:

//bash

echo $PATH

Так становится понятно, на каком именно этапе пропадает Node.js.

Что делать, если Node действительно не установлен

Вот только теперь имеет смысл переустановка.

Если используется nvm, можно установить LTS-версию:

//bash

nvm install --lts

Затем:

//bash

nvm use --lts

Проверяем:

//bash

node -v
npm -v

Если всё работает, можно назначить установленную LTS-версию используемой по умолчанию:

//bash

nvm alias default 'lts/*'

Сам nvm рекомендует именно такой подход для установки и переключения нескольких версий Node.js.

Почему не стоит сразу делать sudo apt install nodejs

На Linux особенно легко получить странную смесь из нескольких установок.

Например, одна версия Node.js установлена через системный пакет, другая через nvm, третья осталась от старой конфигурации.

В результате:

//bash

which node

может показывать одно место, а:

//bash

nvm current

- совершенно другую версию.

Это уже не проблема одной команды. У компьютера просто несколько источников Node.js.

Поэтому если проект работает через nvm, лучше сначала привести в порядок именно nvm, а не добавлять ещё одну системную установку.

Быстрый алгоритм диагностики

Если сейчас перед глазами стоит:

//text

node: command not found

я бы прошёл следующие шаги.

Сначала:

//bash

command -v node

Если Node найден:

//bash

node -v

Если не найден, но используется nvm:

//bash

command -v nvm

Если nvm тоже не найден, для zsh:

//bash

source ~/.zshrc

для bash:

//bash

source ~/.bashrc

Затем:

//bash

nvm ls

Если нужная версия установлена:

//bash

nvm use 24
node -v

Если Node после этого появился, можно сделать выбор постоянным:

//bash

nvm alias default 24

Если nvm вообще не используется, ищем сам бинарник:

//bash

find /usr/local /opt /usr -name node -type f 2>/dev/null

И проверяем PATH:

//bash

echo $PATH

Если каталог с node отсутствует в PATH, исправляем именно его.

Когда переустановка действительно нужна

Иногда всё действительно проще: Node.js удалён, повреждён или установлен некорректно.

Тогда результат диагностики обычно будет достаточно очевидным.

node не найден:

//bash

command -v node

nvm не используется:

//bash

command -v nvm

И самого бинарника Node.js на ожидаемых путях нет.

В таком случае установка заново имеет смысл.

Но последовательность всё равно лучше сохранить:

//text

node -v
    ↓
command -v node
    ↓
проверка nvm
    ↓
проверка PATH
    ↓
проверка установки
    ↓
переустановка

Пять минут диагностики здесь часто экономят полчаса на удалении, скачивании и повторной настройке.

Что на самом деле означает command not found

Мне кажется, это главный момент всей истории.

Сообщение:

//text

node: command not found

не означает:

«На компьютере нет Node.js».

Оно означает:

«Этот shell не смог найти исполняемую команду с именем node».

И это принципиально разные вещи.

Node.js может быть установлен. Может даже нормально работать в другом терминале. Может быть доступен после:

//bash

nvm use 24

и исчезать после открытия новой shell-сессии.

Поэтому первое действие при такой ошибке - не удалять Node.js.

Сначала стоит спросить у самого терминала:

//bash

command -v node

А если используется nvm:

//bash

command -v nvm
nvm current

После этого причина обычно становится гораздо менее загадочной.

И это, пожалуй, хороший пример одной из самых полезных привычек в разработке: сначала определить, что именно не работает, и только потом что-нибудь переустанавливать.