Volta使用指南

Volta 是一个现代化的 JavaScript 工具链管理器，用于管理 Node.js、npm、yarn、pnpm 以及各类全局 CLI 工具。以下是完整的命令速查手册。

一、全局选项（Flags）

在使用任何子命令之前，可以附加以下全局选项：

命令	功能
`volta --version` 或 `volta -v`	打印当前 Volta 版本
`volta --help` 或 `volta -h`	打印帮助信息
`volta --verbose`	启用详细诊断输出
`volta --quiet`	抑制不必要的输出

二、安装与管理命令

这是最常用的命令类别，负责工具的安装、卸载和全局默认版本设置。

命令	功能
`volta install <tool>`	下载并安装工具，同时设为全局默认版本
`volta install node@18`	安装 Node.js 18 的最新版本并设为默认
`volta install node@lts`	安装最新 LTS 版本的 Node.js
`volta install node@latest`	安装最新版 Node.js
`volta install yarn@3`	安装 Yarn 3 并设为默认
`volta install cowsay`	安装 npm 全局包（cowsay）
`volta uninstall <tool>`	从工具链中卸载工具
`volta uninstall node@18.17.0`	卸载指定版本的 Node.js

特别说明：Volta 会把全局包安装在沙箱中，即使切换 Node 版本，这些全局工具依然可用——这是 NVM 做不到的。

三、项目锁定命令（Pin）

Volta 的核心优势之一——将项目所需的工具版本锁定，并写入 package.json，团队成员 clone 项目后无需手动切换版本。

命令	功能
`volta pin node@<version>`	将当前项目的 Node.js 版本固定到指定版本
`volta pin node@20.10.0`	示例：固定 Node 版本为 20.10.0
`volta pin yarn@<version>`	固定项目的 yarn 版本
`volta pin npm@<version>`	固定项目的 npm 版本
`volta pin pnpm@<version>`	固定项目的 pnpm 版本

执行后，Volta 会自动在 package.json 中添加以下配置：

"volta": {
  "node": "20.10.0"
}

四、信息查询命令

命令	功能
`volta list`	查看当前生效的工具版本（受当前目录上下文影响）
`volta list node`	列出所有已安装的 Node.js 版本
`volta list all`	查看本地缓存的所有已下载版本（包括所有工具）
`volta which <binary>`	定位 Volta 实际调用的二进制文件路径
`volta which node`	示例：查看 Volta 实际使用的 node 路径

五、高级工具命令

命令	功能
`volta fetch <tool>`	将工具预下载到本地缓存（用于离线使用，不设为默认）
`volta fetch node@latest`	示例：预下载最新版 Node.js
`volta run <command>`	使用临时指定的工具版本运行命令
`volta run --node 20 node app.js`	示例：临时使用 Node 20 运行 app.js
`volta setup`	为当前用户/Shell 启用 Volta（通常安装后会自动执行）
`volta completions <shell>`	生成 shell 自动补全脚本（支持 bash、zsh、fish、powershell）
`volta help [subcommand]`	查看指定子命令的帮助信息

六、已废弃命令

命令	状态
`volta use`	已废弃，原功能已被 `install` 和 `pin` 替代

快速参考卡片

# 🌟 最常用（90%场景）
volta install node@lts        # 安装 Node LTS
volta pin node@20              # 锁定项目 Node 版本
volta list                     # 查看当前环境

# 📦 包管理器
volta install yarn@3           # 安装 Yarn 3
volta pin pnpm@8               # 锁定项目 pnpm

# 🔍 调试
volta which node               # 查看 node 实际路径
volta list node                # 查看所有已安装 Node 版本
volta --version                # 查看 Volta 版本

💡 提示

几乎所有命令都支持追加 --help 或 -h 来查看详细用法，例如 volta install --help。
Volta 的核心设计理念是自动化：进入项目目录后自动切换工具版本，无需手动执行任何命令。
如果遇到任何命令执行问题，可以加 --verbose 查看详细诊断信息。