Volta 安装与使用：Node.js 版本管理器

Volta - 更快更强的 Node.js 版本管理器

什么是 Volta

Volta 是一个基于 Rust 构建的 JavaScript 工具管理器，用于管理 Node.js 版本。它提供了一种无障碍的方式来管理 JavaScript 命令行工具，支持 Windows、macOS 和 Linux 系统。

为什么选择 Volta

主要原因是即使使用了 nvm，在多个不同的项目之间，也常常忘记切换 node 版本， 而 Volta 通过 pin 命令在 package.json 中添加了 node 以及 pnpm 的版本，实现了无感知切换

如果项目的 node 版本以及 pnpm 版本是非常固定的情况下，是不需要使用 Volta 的

核心优势

• 🚀 极速性能：基于 Rust 构建，比 nvm 快约 40 倍
• 🔄 无缝版本切换：项目间自动切换 Node 版本，无需手动操作
• 🌍 跨平台支持：支持 Windows、macOS 和 Linux
• 📦 智能包管理：全局包与对应 Node 版本关联，避免版本冲突
• 🔒 版本锁定：项目版本信息存储在 package.json 中，团队协作更便捷
• ⚡ 即时切换：版本切换无延迟，提升开发效率

与 nvm 的对比

官网

https://docs.volta.sh/reference/setup

安装

macOS / Linux 安装

curl https://get.volta.sh | bash

Windows 安装

1. 访问 Volta GitHub Releases 页面
2. 下载最新版本的 volta-*-windows-x86_64.msi 文件
3. 双击运行 .msi 安装程序
4. 按照安装向导完成安装

验证安装

安装完成后关闭终端，重新打开终端，运行查看版本看是否安装成功

基础使用

查看版本

volta --version

安装指定 node 版本

volta install node@16.18.1

如果您没有指定确切的版本，Volta 会选择与您的请求相匹配的适当版本。

volta install node@20

安装最新版本

volta install node@latest

给项目指定版本

volta pin node@22.12.0

这会在你的 package.json 中添加：

{
  "volta": {
    "node": "22.12.0"
  }
}

查看已安装的版本

volta list all

查看当前工具链

volta list

主要命令

volta install

安装工具到您的工具链中

# 安装 Node.js
volta install node@18.17.1

# 安装 npm
volta install npm@9.8.1

# 安装 yarn
volta install yarn@1.22.19

# 安装 pnpm（需要启用 pnpm 支持）
volta install pnpm@8.6.12

volta pin

锁定项目的运行时或包管理器

# 锁定 Node 版本
volta pin node@20.5.1

# 锁定 npm 版本
volta pin npm@9.8.1

# 锁定 yarn 版本
volta pin yarn@3.6.1

volta list

显示当前工具链

# 显示当前活跃的工具
volta list

# 显示所有已安装的工具
volta list all

# 显示特定工具的版本
volta list node
volta list npm

volta uninstall

从工具链中卸载工具

# 卸载 pnpm
volta uninstall pnpm

volta setup

为当前用户/shell 启用 Volta

volta setup

高级功能

包管理器支持

Volta 支持多种包管理器：

# 安装并锁定 yarn
volta install yarn@3.6.1
volta pin yarn@3.6.1

# 安装并锁定 pnpm（需要先启用 pnpm 支持）
volta install pnpm@8.6.12
volta pin pnpm@8.6.12

工作区支持

Volta 支持 monorepo 和工作区，会自动检测项目根目录的 package.json 中的 volta 配置。

子项目可以通过在 package.json 中添加如下代码进行继承

{
  "volta": {
    "extends": "../../package.json"
  }
}

常见问题与解决方案

卸载 volta 安装的 node 版本

• Volta 目前不支持直接通过命令卸载 Node.js 版本
• 可以通过手动删除 ~/.volta/tools/image/node/ 目录下的对应版本目录来卸载

进入目录

cd ~/.volta/tools/image/node/

执行删除

rm -rf 16.18.1 20.18.0 20.19.2 22.12.0 24.1.0

启用 pnpm

https://docs.volta.sh/advanced/pnpm

macOS / Linux 启用方法

在环境变量中添加 export VOLTA_FEATURE_PNPM=1

# 临时启用（当前会话）
export VOLTA_FEATURE_PNPM=1

# 永久启用（添加到 shell 配置文件）
echo 'export VOLTA_FEATURE_PNPM=1' >> ~/.bashrc
# 或者
echo 'export VOLTA_FEATURE_PNPM=1' >> ~/.zshrc

Windows 启用方法

方法一：使用命令行设置环境变量

临时设置（当前会话）：

# Command Prompt
set VOLTA_FEATURE_PNPM=1

# PowerShell
$env:VOLTA_FEATURE_PNPM=1

永久设置：

# PowerShell（管理员权限）
[System.Environment]::SetEnvironmentVariable('VOLTA_FEATURE_PNPM', '1', [System.EnvironmentVariableTarget]::User)

方法二：通过系统设置界面

1. 按 Win + R 打开运行对话框
2. 输入 sysdm.cpl 并按回车
3. 点击"高级"选项卡
4. 点击"环境变量"按钮
5. 在"用户变量"部分点击"新建"
6. 变量名：VOLTA_FEATURE_PNPM
7. 变量值：1
8. 点击"确定"保存

方法三：使用 setx 命令

setx VOLTA_FEATURE_PNPM 1

验证 pnpm 支持

设置环境变量后，重启终端并验证：

# 安装 pnpm
volta install pnpm@latest

# 验证安装
pnpm --version

# 在项目中锁定 pnpm 版本
volta pin pnpm@8.15.1

注意事项

• 设置环境变量后需要重启终端才能生效
• 建议使用 pnpm@8.6.0 或更高版本，以获得更好的兼容性
• 如果遇到安装 pnpm 问题，参考：GitHub Issue #1554