#Как проявляется ошибка и когда применим способ
Пакет установлен локально через npm install, но его команда не находится при прямом вводе в терминале. Это нормальное различие между локальными исполняемыми файлами node_modules/.bin и системной переменной PATH; глобальная установка обычно не нужна.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Команда доступна только внутри npm runnpm добавляет node_modules/.bin в PATH при выполнении scripts. | npm run build работает, а ввод vite или eslint в оболочке — нет. | Использовать npm run или npm exec. |
| Пакет не предоставляет binУстановленный пакет — только библиотека или не та версия инструмента. | В node_modules/.bin нет ожидаемого имени. | Проверить поле bin пакета и документацию инструмента. |
#Пошаговая диагностика и решение
- 1. Проверьте, что пакет действительно установленОткройте терминал внутри каталога, где лежит package.json. Выполните npm ls с настоящим именем пакета. Если вывод (empty) или ошибка отсутствующей зависимости, сначала разберите установку пакета, а не настройку системного PATH.
- Подставьте имяLinux · Терминал (Bash)КомандаПодставьте имя. Чтение установленного дерева, без администратора.
npm ls ИМЯ_ПАКЕТА --depth=0
- 2. Найдите локальный исполняемый файлВ Linux/macOS откройте папку проекта → node_modules/.bin; в Windows откройте её через Проводник. Windows обычно содержит обёртки .cmd, а Unix-системы ссылки или скрипты. Если папки нет, установленный пакет может не предоставлять команду, либо были пропущены devDependencies.
- 3. Посмотрите scripts в package.jsonОткройте package.json в редакторе, найдите секцию scripts и конкретную команду. Если в ней прописано, например, "lint": "eslint .", запускайте npm run lint из корня проекта. При таком запуске npm сам расширяет PATH; не нужно менять глобальные переменные Windows или конфигурацию сервера.
- Показывает имеющиеся сценарииLinux · Терминал (Bash)КомандаПоказывает имеющиеся сценарии. Если пусто — нужного сценария нет.
npm pkg get scripts
- 4. Проверьте команду через npm execЕсли нужно выполнить отдельный инструмент без добавления постоянного сценария, используйте npm exec --no -- ИМЯ_КОМАНДЫ из папки проекта; опция --no не даёт npm автоматически получать пакет из сети при его отсутствии. Если команда не найдена, сначала выясните, какой пакет должен поставлять её.
- Дополнительная команда по темеLinux · Терминал (Bash)С осторожностьюПодставьте реальную команду, совместимую с --version; запускает локальный исполняемый файл доверенной зависимости.
npm exec --no -- ИМЯ_КОМАНДЫ --versionКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- 5. Разделите отсутствие команды и пакет без binОткройте node_modules/ИМЯ_ПАКЕТА/package.json и проверьте поле bin, если оно есть. Если bin отсутствует, библиотека не обязана предоставлять исполняемую команду. Если bin указан, но обёртка отсутствует, проверьте результат установки и не восстанавливайте ссылки вручную вслепую.
- 6. Закрепите правильный способ запускаДля команды, входящей в сборку, добавьте проверенный сценарий в scripts на отдельной ветке и запустите npm run его-имя. Сохраните package.json и проверьте работу в чистой копии с npm ci. Не добавляйте node_modules/.bin в глобальный PATH машины на постоянной основе.
#Проверка результата и действия при повторении
Нужная команда работает из npm run или npm exec в каталоге проекта без глобальных установок. Если это сторонняя утилита без bin, ожидаемый результат — понимание, что пакет не предоставляет консольную команду; используйте документированный способ его применения.
Если на указанном шаге результат отличается, остановитесь и запишите первое полное сообщение об ошибке, версию инструментов и проверенное состояние до исправления. Не переходите к опасным действиям на действующем проекте: повторите проверку на отдельной копии, верните сохранённые файлы и только затем выбирайте следующую причину.