Окружение

Команда vp env управляет всей средой JavaScript: одной средой выполнения Node.js и одним выбранным менеджером пакетов. npm, pnpm, Yarn и Bun являются семействами взаимозаменяемых менеджеров пакетов. Она относится к глобальному CLI и не входит в локальный пакет vite-plus проекта.

Обзор

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

Node.js — рантайм, используемый для выполнения JavaScript-инструментов и скриптов. Каждый проект может указать необходимую ему версию Node.js.
Менеджер пакетов устанавливает зависимости проекта и управляет ими. Каждый проект может выбрать npm, pnpm, Yarn или Bun и указать его версию.

Например, проект может использовать Node.js 24 и pnpm 10. Изменение версии Node.js не меняет выбранный менеджер пакетов, а переключение с pnpm на Yarn не меняет версию Node.js. Vite+ определяет оба компонента при запуске команды, поэтому можно переключаться между проектами без необходимости вручную менять используемые инструменты.

Vite+ связывает эти настройки с вашей оболочкой через шимы — небольшие запускающие программы с именами node, npm, pnpm, yarn и bun, а также их алиасы. В управляемом режиме шим определяет и запускает соответствующий инструмент для текущего проекта. Такие команды, как vp install, используют выбранный проектом менеджер пакетов; прямой вызов pnpm всегда запускает pnpm, даже в проекте, который выбрал другой менеджер.

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

Используйте vp env off, чтобы отключить управляемый режим для Node.js и менеджеров пакетов. Подробнее о режимах окружения и о том, как переключиться на системные инструменты, см. ниже в разделе Режимы окружения.

Если селектор не указан, большинство команд работают с обоими компонентами. Добавьте node, pm, npm, pnpm, yarn или bun, чтобы ограничить область действия команды. pm означает все четыре семейства при выполнении команд просмотра списка и очистки, но при операциях над проектом обозначает единственный выбранный менеджер пакетов.

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

bash

vp env pin 22.0.0               # Только Node.js
vp env pin pnpm@10.18.0         # Только pnpm
vp env pin node@24 pnpm@12      # Оба компонента
vp env pin 22.0.0 pnpm@10.18.0  # Также оба компонента

Используйте vp env pin, чтобы сохранить версии проекта, vp env default — чтобы задать резервные версии, а vp env use — чтобы переопределить версии для текущей оболочки. Выполните vp env current, чтобы увидеть определённое окружение.

Выбор версии Node.js

Чтобы определить версию Node.js для проекта, Vite+ сначала проверяет текущий каталог, а затем поднимается по дереву его родительских каталогов. Используется ближайший каталог с поддерживаемым объявлением. Внутри каждого каталога источники проверяются в следующем порядке:

Файл .node-version
devEngines.runtime в package.json (согласно стандарту devEngines)
engines.node в package.json
Файл .nvmrc

Если ни в одном каталоге не указана версия, Vite+ использует глобальную версию по умолчанию (vp env default), а затем — последнюю LTS-версию.

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

Использование pnpm с управлением средой выполнения в Vite+

pnpm также может управлять средой выполнения, объявленной в devEngines.runtime. Если Node.js одновременно управляется pnpm и Vite+, они могут отдельно загрузить одну и ту же версию или выбрать разные версии, что приведёт к непредсказуемому поведению разных команд.

Если вы хотите, чтобы Vite+ управлял Node.js, начиная с pnpm 11 можно глобально отключить автоматическое управление средой выполнения pnpm с помощью runtimeOnFail:

bash

pnpm config set --global runtimeOnFail ignore

Этот параметр также отключает автоматическое управление другими объявленными средами выполнения, включая Bun и Deno. Прежде чем устанавливать его глобально, убедитесь, что ни один из ваших проектов не зависит от такого поведения.

Выбор менеджера пакетов

При выборе менеджера пакетов используется следующий приоритет:

Явно заданное переопределение в команде
VP_PACKAGE_MANAGER
packageManager верхнего уровня
devEngines.packageManager
Lock-файл или конфигурация конкретного менеджера
Глобальная версия по умолчанию для указанного менеджера пакетов
Последняя доступная версия указанной shim-команды

VP_PACKAGE_MANAGER выбирает менеджер пакетов и его версию для таких команд, как vp install. Шимы менеджеров пакетов, вызываемые напрямую, игнорируют эту переменную и используют независимые переопределения версий:

Переменная	Шимы
`VP_NPM_VERSION`	`npm`, `npx`
`VP_PNPM_VERSION`	`pnpm`, `pnpx`
`VP_YARN_VERSION`	`yarn`, `yarnpkg`
`VP_BUN_VERSION`	`bun`, `bunx`

Эти переменные принимают версию или диапазон версий, например 10.18.0, 10 или latest, и переопределяют версии проекта и версии по умолчанию соответствующего шима. Они не изменяют менеджер или версию, выбранные командой vp install.

vp env use pnpm@10.20.0 устанавливает VP_PNPM_VERSION для текущей оболочки, так же как vp env use node@22 устанавливает VP_NODE_VERSION. У каждого менеджера пакетов есть собственное переопределение, поэтому переключение на Yarn не сбрасывает переопределение для pnpm. vp env use не устанавливает и не очищает VP_PACKAGE_MANAGER.

Прямые шимы определяют свою версию из соответствующей переменной окружения, затем из соответствующего файла сессии, если оболочка-обёртка недоступна, затем из конфигурации проекта и значения по умолчанию для семейства. vp env current pnpm и vp env which pnpm позволяют проверить выбор версии этого шима; vp env current pm сообщает о менеджере, выбранном для команд vp.

bash

VP_PACKAGE_MANAGER=pnpm@10.18.0 vp install
VP_PNPM_VERSION=10.20.0 pnpm --version

Переопределения применяются в управляемом режиме. Менеджер пакетов также может самостоятельно переключить свою версию после того, как Vite+ запустит его; например, настройка managePackageManagerVersions в pnpm может переключить его обратно на версию, указанную в package.json.

Выбор проекта применяется только к соответствующим ему шимам. Например, pnpm управляет pnpm и pnpx; при вызове npm его версия по-прежнему определяется независимо. Если подходящего выбора проекта нет, именованный шим использует настроенную версию по умолчанию, а при её отсутствии — последнюю доступную версию без запроса подтверждения. Напрямую вызываемый шим npm сохраняет свой резервный вариант, поставляемый вместе с Node, тогда как явное указание области семейства vp env ... npm использует последнюю версию отдельно устанавливаемого npm.

Кэширование последней версии

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

Режимы окружения

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

Чтобы включить управляемый режим, выполните:

bash

vp env on

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

bash

vp env on node
vp env off pm
vp env off pnpm
vp env on bun

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

bash

vp env off

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

Использование pm задаёт выбранный режим для всех поддерживаемых в настоящее время менеджеров пакетов и заменяет их индивидуальные настройки. Непривязанные к конкретному компоненту команды on или off делают то же самое, одновременно изменяя режим Node.js. Для семейства, режим которого ещё не задан, выбор остаётся неопределённым до первого использования его shim-команды или выполнения команды on / off, которая задаёт этот режим.

Команды

Настройка

vp env setup создаёт или обновляет shim-файлы node, npm, npx, pnpm, pnpx, yarn, yarnpkg, bun, bunx, vpx и vpr в определённом каталоге bin. Он записывает скрипты настройки оболочки в каталог конфигурации.
vp env on / vp env off изменяет оба режима; добавьте node, pm, npm, pnpm, yarn или bun, чтобы ограничить область изменения
vp env print выводит настройки PATH для обоих компонентов; добавьте селектор, чтобы вывести настройки только для одного компонента

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

powershell

. "$env:APPDATA\vite-plus\env.ps1"

Если в старой установке Vite+ используется %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 в директории bin в Windows.

В CI vp env use может выполняться без инициализации оболочки. Команда записывает временный файл сессии для каждого рантайма или менеджера пакетов в определённый каталог состояния, например .session-node-version или .session-pnpm-version. Последующие вызовы шимов в рамках той же задачи используют эти файлы для определения той же среды.

Управление

vp env default показывает глобальную версию Node.js по умолчанию и версию каждого настроенного менеджера пакетов. Версии без указания компонента задают версию Node.js; спецификации с указанием менеджера, такие как pnpm@10.18.0, задают версию по умолчанию для shim-команды этого менеджера, не изменяя версии по умолчанию для Bun, Yarn или npm. --unset удаляет все значения по умолчанию, если не указан селектор.
vp env pin показывает или записывает закреплённые версии проекта. Существующие файлы .node-version и поля packageManager верхнего уровня продолжают обновляться для обеспечения совместимости. Существующий .nvmrc обновляется, если он является фактическим источником версии Node в текущем каталоге; его комментарии и другое содержимое, не относящееся к версии, сохраняются. В противном случае Vite+ записывает соответствующую запись devEngines. Используйте --target node-version, --target nvmrc, --target dev-engines или --target package-manager, чтобы явно выбрать целевой источник. Закрепление версии во вложенном каталоге не изменяет унаследованный .nvmrc.
vp env unpin по умолчанию удаляет обе действующие фиксации; добавьте селектор, чтобы удалить только одну из них. Объявления с более низким приоритетом не удаляются.
vp env use активирует всю среду проекта. Явно указанные спецификации переопределяют выбранные компоненты; --unset удаляет настройки обоих компонентов, если не указан селектор.
vp env install устанавливает всю определённую среду, выбранный компонент или явно указанные спецификации.
vp env uninstall удаляет явно указанные точные версии Node.js или версии менеджеров пакетов с указанием версии.
vp env clean удаляет неиспользуемые установки. Используйте clean node, clean pm или укажите конкретный менеджер. Текущие версии и настроенные версии по умолчанию сохраняются.
vp env exec запускает команду в определённой среде. Используйте --node и --package-manager; --npm является псевдонимом для --package-manager npm@….
vp node использует определённую среду выполнения Node.js и предоставляет дочерним процессам путь к выбранному менеджеру пакетов.

Проверка

vp env current показывает текущее разрешённое окружение
vp env doctor выполняет диагностику окружения
vp env which показывает, какой путь к инструменту будет использован
vp env list показывает отдельные разделы для Node.js, npm, pnpm, Yarn и Bun; селекторы ограничивают вывод
vp env list-remote одновременно получает данные из реестров Node.js и всех четырёх менеджеров пакетов; селекторы ограничивают сетевые запросы. --lts неявно выбирает Node.js.

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

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

Примеры

bash

# Настройка
vp env setup                  # Создать shim-команды для Node.js и менеджеров пакетов
vp env on                     # Управление Node.js и менеджерами пакетов
vp env off pm                 # Использовать только системные менеджеры пакетов
vp env off pnpm               # Использовать только системный pnpm
vp env print                  # Вывести настройки PATH для обоих компонентов

# Управление
vp env pin lts pnpm@10        # Зафиксировать точные версии обоих компонентов проекта
vp env install                # Установить всю определённую среду
vp env default node@24        # Задать глобальную версию Node.js по умолчанию
vp env default pnpm@10        # Задать глобальную версию pnpm по умолчанию
vp env use 20 pnpm@10         # Переопределить оба компонента для текущей оболочки
vp env use --unset pnpm       # Удалить только сессионную версию pnpm
vp env use --unset pm         # Удалить все сессионные версии менеджеров пакетов
vp env clean                  # Удалить неиспользуемые управляемые версии Node.js и менеджеров пакетов

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

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

Вывод JSON

Вывод JSON для current, list и list-remote организован по компонентам. current --json возвращает соседние объекты node и package_manager:

json

{
  "node": {
    "version": "22.0.0",
    "source": "devEngines.runtime",
    "source_path": "/project/package.json",
    "project_root": "/project",
    "bin_path": "/home/.vite-plus/js_runtime/node/22.0.0/bin/node",
    "installed": true,
    "mode": "managed"
  },
  "package_manager": {
    "name": "pnpm",
    "version": "10.18.0",
    "source": "packageManager",
    "source_path": "/project/package.json",
    "project_root": "/project",
    "bin_paths": {
      "pnpm": "/home/.vite-plus/package_manager/pnpm/10.18.0/pnpm/bin/pnpm",
      "pnpx": "/home/.vite-plus/package_manager/pnpm/10.18.0/pnpm/bin/pnpx"
    },
    "installed": true,
    "mode": "managed"
  }
}

list --json и list-remote --json группируют массивы компонентов:

json

{
  "node": [],
  "package_managers": {
    "npm": [],
    "pnpm": [],
    "yarn": [],
    "bun": []
  }
}

Селекторы исключают невыбранные поля верхнего уровня или семейства менеджеров пакетов. Вывод данных из реестров работает по принципу «всё или ошибка»: если не удаётся выполнить запрос к любому выбранному реестру, Vite+ не выводит частичный результат ни в обычном, ни в JSON-формате.

Пользовательское зеркало 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

Переход на Vite+

vp check

Кэширование задач

Окружение

Обзор

Выбор версии Node.js

Выбор менеджера пакетов

Режимы окружения

Команды

Настройка

Управление

Проверка

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

Примеры

Вывод JSON

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

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

Окружение ​

Обзор ​

Выбор версии Node.js ​

Выбор менеджера пакетов ​

Режимы окружения ​

Команды ​

Настройка ​

Управление ​

Проверка ​

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

Примеры ​

Вывод JSON ​

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

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

Окружение

Обзор

Выбор версии Node.js

Выбор менеджера пакетов

Режимы окружения

Команды

Настройка

Управление

Проверка

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

Примеры

Вывод JSON

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

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