Vite+

Окружение ​

vp env управляет версиями Node.js глобально и на уровне отдельных проектов.

Обзор ​

Управляемый режим включён по умолчанию, поэтому node, npm и связанные shim-команды разрешаются через Vite+ и выбирают подходящую версию Node.js для текущего проекта.

Версия Node.js для проекта определяется из следующих источников в порядке приоритета:

  1. Файл .node-version (в текущем или родительских каталогах)
  2. devEngines.runtime в package.json (согласно стандарту devEngines)
  3. engines.node в package.json
  4. Глобальная версия по умолчанию (vp env default), затем последняя LTS-версия

devEngines.runtime имеет более высокий приоритет, чем engines.node, поскольку определяет требования к среде разработки, тогда как engines.node описывает диапазон версий, поддерживаемых для пользователей пакета. Если указанные источники противоречат друг другу, vp env doctor выведет предупреждение.

Если проект содержит поле packageManager (или devEngines.packageManager) в package.json, соответствующие shim-команды менеджера пакетов также будут использовать указанную версию. Например, запись packageManager: "npm@10.9.4" заставит команды npm и npx использовать npm 10.9.4. Аналогично работают пары алиасов npm/npx, pnpm/pnpx, yarn/yarnpkg и bun/bunx, если для них установлены соответствующие shim-команды. Vite+ не подменяет команды автоматически, поэтому в проекте, привязанном к pnpm, команда npm всё равно будет использовать npm, поставляемый вместе с разрешённой версией среды выполнения Node.js.

По умолчанию Vite+ хранит управляемую среду выполнения и связанные файлы в ~/.vite-plus. При необходимости это расположение можно переопределить с помощью VP_HOME.

Если вы хотите сохранить такое поведение, выполните:

bash
vp env on

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

Если вы не хотите, чтобы Vite+ в первую очередь управлял Node.js, выполните:

bash
vp env off

Это переключает Vite+ в режим system-first, в котором shim-команды предпочитают использовать системную версию Node.js и обращаются к среде выполнения, управляемой Vite+, только при необходимости.

Команды ​

Настройка ​

  • vp env setup создаёт или обновляет shim-команды в VP_HOME/bin (а также записывает сценарии настройки для каждой оболочки в VP_HOME)
  • vp env on включает управляемый режим, при котором shim-команды всегда используют Node.js, управляемый Vite+
  • vp env off включает режим system-first, при котором shim-команды в первую очередь используют системную версию Node.js
  • vp env print выводит фрагмент команд оболочки для текущей сессии

В PowerShell необходимо выполнить dot-source для сгенерированного сценария настройки в текущей оболочке, прежде чем vp env use сможет влиять только на текущую сессию оболочки:

powershell
. "$env:USERPROFILE\.vite-plus\env.ps1"

Добавьте эту строку в конец вашего PowerShell-профиля $PROFILE, чтобы она автоматически применялась в новых сессиях оболочки. Для этого не требуются повышенные привилегии.

Создайте файл профиля, если он ещё не существует:

powershell
if (-not (Test-Path $PROFILE)) { New-Item $PROFILE -Force }

Откройте файл профиля для редактирования:

powershell
Invoke-Item $PROFILE

Командная строка Windows (cmd.exe) не может определить функцию-обёртку, необходимую для того, чтобы vp env use мог обновить текущий сеанс оболочки. Вместо этого используйте сгенерированную команду vp-use.cmd:

batch
vp-use 20
node --version
vp-use --unset

Эта альтернативная команда требуется только для vp env use. Остальные команды vp env работают в командной строке Windows без каких-либо изменений. Команда vp env setup создаёт vp-use.cmd в каталоге VP_HOME/bin в Windows.

В CI vp env use всё равно может выполняться без инициализации оболочки. Команда записывает временный файл сессии в VP_HOME, чтобы последующие вызовы shim-команд в рамках той же задачи могли определить выбранную версию Node.js.

Управление ​

  • vp env default устанавливает или показывает глобальную версию Node.js по умолчанию
  • vp env pin закрепляет версию Node.js для текущего каталога: если файл .node-version уже существует, обновляется он; в противном случае версия записывается в package.json#devEngines.runtime; файл .node-version создаётся только в том случае, если в каталоге отсутствует package.json. Используйте --target node-version или --target dev-engines, чтобы явно выбрать место записи. Существующее поле engines.node никогда не изменяется.
  • vp env unpin удаляет закреплённую версию из того же источника, в который команда vp env pin записала бы её
  • vp env use устанавливает версию Node.js для текущей сессии оболочки
  • vp env install устанавливает версию Node.js
  • vp env uninstall удаляет установленную версию Node.js
  • vp env clean удаляет неиспользуемые управляемые среды выполнения Node.js, все загруженные менеджеры пакетов и кэш Corepack.
  • vp env exec выполняет команду с указанной версией Node.js
  • vp node запускает сценарий Node.js — сокращение для vp env exec node

Проверка ​

  • vp env current показывает текущее разрешённое окружение
  • vp env doctor выполняет диагностику окружения
  • vp env which показывает, какой путь к инструменту будет использован
  • vp env list показывает локально установленные версии Node.js
  • vp env list-remote показывает доступные версии Node.js из реестра

Настройка проекта ​

  • Закрепите версию проекта с помощью vp env pin
  • Используйте vp install, vp dev и vp build как обычно
  • Позвольте Vite+ автоматически выбрать подходящую среду выполнения для проекта

Примеры ​

bash
# Настройка
vp env setup                  # Создать shim-команды для node, npm, npx и corepack
vp env on                     # Использовать Node.js, управляемый Vite+
vp env print                  # Вывести фрагмент команд оболочки для текущей сессии

# Управление
vp env pin lts                # Закрепить проект за последним LTS-релизом
vp env install                # Установить версию из .node-version или package.json
vp env default lts            # Установить глобальную версию по умолчанию
vp env use 20                 # Использовать Node.js 20 для текущей сессии оболочки
vp env use --unset            # Удалить переопределение для текущей сессии
vp env clean                  # Удалить неиспользуемые управляемые кэши

# Проверка
vp env current                # Показать текущее разрешённое окружение
vp env current --json         # Вывести данные в формате JSON для автоматизации
vp env which node             # Показать, какой исполняемый файл node будет использован
vp env which npx              # Показать закреплённый алиас менеджера пакетов, если packageManager совпадает
vp env list-remote --lts      # Показать только LTS-версии

# Выполнение
vp env exec --node lts npm i  # Выполнить npm с последней LTS-версией
vp env exec node -v           # Использовать режим shim-команд с автоматическим выбором версии
vp node script.js             # Сокращение: запустить сценарий Node.js с разрешённой версией
vp node -e "console.log(1+1)" # Сокращение: передать любой флаг или аргумент node

Corepack ​

По умолчанию Vite+ создаёт shim-команду corepack, поэтому Corepack работает даже без установленного в системе Node.js:

  • В Node.js 24 и более ранних версиях shim использует Corepack, поставляемый вместе с разрешённой версией Node.js.
  • В Node.js 25 и новее, где Corepack больше не входит в поставку Node.js, Vite+ при первом использовании устанавливает Corepack как управляемый глобальный пакет. При этом создаётся ссылка только на исполняемый файл corepack; если вам также нужны команды запуска pnpm и yarn из этого пакета, установите его самостоятельно с помощью vp install -g corepack.
  • Если вы явно установили Corepack через vp install -g corepack, эта установка всегда имеет приоритет.

Обычно corepack enable создаёт команды запуска pnpm и yarn рядом с исполняемым файлом Corepack, но в Vite+ этот каталог не находится в PATH. Поэтому shim по умолчанию задаёт --install-directory равным VP_HOME/bin, благодаря чему после выполнения corepack enable эти команды становятся доступны отовсюду и продолжают использовать версии Node.js и менеджера пакетов, разрешённые для проекта:

bash
corepack enable               # pnpm и yarn теперь разрешаются через corepack
corepack disable              # снова удалить команды pnpm/yarn

Созданные команды запуска привязаны к той копии Corepack, которая их создала. Если эта копия впоследствии будет удалена (например, при удалении версии Node.js, с которой она поставлялась), повторно выполните corepack enable, чтобы создать их заново.

Shim-команды, принадлежащие Vite+ (npm, npx и бинарные файлы, установленные через vp install -g), защищены: если Corepack удалит или заменит их, Vite+ восстановит их и выведет предупреждение.

Пользовательское зеркало Node.js ​

По умолчанию Vite+ загружает Node.js с https://nodejs.org/dist. Если вы работаете за корпоративным прокси или вам необходимо использовать внутреннее зеркало (например, Artifactory), задайте переменную окружения VP_NODE_DIST_MIRROR:

bash
# Устанавливаем конкретную версию из пользовательского зеркала
VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist vp env install 22

# Устанавливаем глобальную версию по умолчанию, используя пользовательское зеркало
VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist vp env default lts

# Задаём постоянное значение в профиле оболочки (.bashrc, .zshrc и т. д.)
echo 'export VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist' >> ~/.zshrc

Проверка цифровой подписи Node.js ​

При установке Node.js из официального дистрибутива nodejs.org Vite+ загружает PGP-подписанный файл SHASUMS256.txt.asc и проверяет его подпись с помощью встроенного набора открытых ключей разработчиков Node.js, прежде чем доверять каким-либо контрольным суммам. Это защищает от подмены файла SHASUMS256.txt вместе с соответствующим вредоносным архивом. После этого всегда выполняется проверка SHA-256 контрольной суммы загруженного архива.

При использовании пользовательских зеркал (VP_NODE_DIST_MIRROR), публикующих только обычный файл SHASUMS256.txt, Vite+ использует только проверку контрольной суммы. Если зеркало публикует и файл .asc, его подпись также проверяется, а недействительная подпись считается критической ошибкой.

Если в будущем проблемы с набором ключей или сертификатами помешают загрузке, можно установить переменную VP_NODE_SKIP_SIGNATURE_VERIFY, чтобы временно отключить проверку PGP-подписи. Проверка SHA-256 контрольной суммы при этом всё равно выполняется, а Vite+ выводит предупреждение о том, что проверка подписи была пропущена:

bash
VP_NODE_SKIP_SIGNATURE_VERIFY=1 vp env install 22

© 2026 VoidZero Inc. и контрибьюторы Vite+.