Как Desktop использует вашу среду Node

HagiCode Desktop использует внешние node и npm, установленные в вашей системе. Установите Node.js перед первым запуском Desktop и убедитесь, что обе команды доступны через системную переменную PATH.

Этот FAQ объясняет, как Desktop находит внешнюю среду Node, куда устанавливаются Agent CLI и что делать, если Node или npm не найдены.

Требования к версии

Нужен Node.js 24 или выше (минимально допустимая версия — тоже 24). npm устанавливается вместе с Node.js. Способы установки описаны в разделе Установка Node.js.

Git тоже нужно установить самостоятельно, см. Руководство по установке.

Как Desktop находит node и npm

При запуске Desktop читает системную переменную PATH и ищет в ней node, npm и git. Это значит, что:

• Версия, которую вы видите в терминале по команде node --version, обычно и есть версия, которую использует Desktop.
• Desktop лишь использует вашу среду Node и не заменяет и не изменяет ее.
• Если вы установили или обновили Node.js, когда Desktop уже был открыт, полностью закройте Desktop и запустите его заново, чтобы он прочитал новый PATH.

Менеджеры версий и PATH

В macOS и Linux менеджеры версий, такие как nvm и fnm, обычно задают PATH только в файлах конфигурации оболочки. Desktop, запущенный из Dock, меню приложений или с ярлыка на рабочем столе, эти файлы не читает и может не найти node. Запускайте Desktop из терминала, в котором уже работает node, либо используйте установку на уровне системы.

Куда устанавливаются Agent CLI и другие управляемые пакеты

Страница управления зависимостями в Desktop обнаруживает node и npm в PATH, показывает определенный глобальный префикс npm и устанавливает пакеты CLI, перечисленные в каталоге, в этот внешний глобальный каталог.

Для каждого управляемого CLI Desktop ищет исполняемый файл в следующем порядке:

1. Уже существующий управляемый путь
2. Глобальный каталог bin npm (в Windows включая скрипты запуска .cmd и .ps1)
3. PATH

Настройки зеркала npm применяются при установке и синхронизации. Удаление тоже выполняется во внешнем глобальном каталоге и требует подтверждения в интерфейсе. Текущий глобальный каталог можно посмотреть такой командой:

npm prefix -g

Если глобальный каталог находится в месте, где нужны права администратора, при установке может возникнуть ошибка доступа; см. Настройка глобального каталога npm.

Что делать, если Desktop не находит Node или npm

1. Выполните в терминале node --version и убедитесь, что версия Node.js не ниже 24. Затем выполните npm --version, чтобы проверить доступность npm.
2. Если Node.js не установлен или его версия слишком низкая, сначала установите Node.js вне Desktop.
3. Полностью закройте Desktop и запустите его заново, затем вернитесь на страницу зависимостей и нажмите «Обновить».

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