说明项目

volta 使用指南

简介

Volta 是一种轻松管理 JavaScript 命令行工具的方式。

特性

• 速度快 ⚡
• 无缝的、按项目切换版本
• 跨平台支持，包括 Windows 和所有 Unix 外壳
• 支持多种包管理器
• 稳定的工具安装 —— 无需在每次 Node 升级时重新安装！
• 可扩展钩子，用于特定站点的自定义

为何选择 Volta？

使用 Volta，你可以在不同项目间使用不同的 Node 版本，而不必手动切换。

安装 Volta

Unix 系统安装

在包括 macOS 在内的大多数 Unix 系统上，你可以通过一条命令安装 Volta：

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

对于 bash、zsh 和 fish shells，此安装程序会自动更新你的控制台启动脚本。如果你希望阻止对控制台启动脚本的修改，请参阅 “跳过 Volta 设置”。要手动配置 shell 以使用 Volta，请编辑你的控制台启动脚本，执行以下操作：

1. 将 VOLTA_HOME 变量设置为 $HOME/.volta
2. 将 $VOLTA_HOME/bin 添加到 PATH 变量的开头

Windows 系统安装

在 Windows 系统上，推荐使用 winget 安装 Volta：

winget install Volta.Volta

如果你愿意，也可以直接下载安装程序并手动运行来安装 Volta。
Windows subsystem for Linux（适用于 Linux 的 Windows 子系统）
如果你要在适用于 Linux 的 Windows 子系统中使用 Volta，请遵循上面的 Unix 安装指南。

选择默认（全局）的 Node 版本

这是全系统默认的 Node 版本，特定项目设置了指定版本的除外。

要选择特定版本的 Node，请运行：

volta install node@22.5.1

或者，要使用最新的 LTS 版本，请运行：

volta install node

设置特定项目的 Node 版本

在指定的项目中使用的 Node 版本，只在这个项目上使用特定的 Node 版本
| 一定要有 package.json 文件。

要设置特定版本的 Node，请运行：

volta pin node@22.5.1

或者，要使用最新的 LTS 版本，请运行：

volta pin node

Volta 命令

以下是 volta 命令行工具的命令参考，其语法如下：

要在工具链中安装工具，请使用 volta install xxx。

要固定项目的运行时或包管理器，请使用 volta pin xxx。

用法：

volta [FLAGS] [SUBCOMMAND]

标志（FLAGS）：

--verbose
启用详细诊断信息

--quiet
阻止不必要的输出

-v, --version
打印当前 Volta 的版本

-h, --help
打印帮助信息

子命令（SUBCOMMANDS）：

fetch 将工具下载到本地机器
install 在你的工具链中安装工具
uninstall 从你的工具链中卸载工具
pin 固定项目的运行时或包管理器
list 显示当前的工具链
completions 生成 Volta 的自动补全脚本
which 定位 Volta 将调用的实际二进制文件
setup 为当前用户 / Shell 启用 Volta
help 打印此消息或指定子命令的帮助信息

卸载 Volta

如果 Volta 不能满足你的需求，你想要卸载它，你可以通过以下方式卸载它。

Unix 系统卸载

在 Unix 系统上完全卸载 Volta 需要两个步骤：

• 删除整个 ~/.volta 目录

rm -rf ~/.volta

• 编辑你的 shell 配置文件脚本，移除提及 Volta 的两行内容。Volta 默认查找的配置文件脚本包括：

  1. .bashrc
  2. .bash_profile
  3. .zshrc
  4. .zshenv
  5. config.fish
  6. .profile

注意 修改后你可能需要打开一个新的终端，因为许多 shell 会缓存最近命令的位置。

Windows 系统卸载

在 Windows 上，卸载 Volta 可以通过在开始 > 设置 > 应用的列表中选中它，然后选择 “卸载”。

钩子（Hooks）

默认情况下，Volta 会从公共源和注册表（https://nodejs.org、https://yarnpkg.com、https://www.npmjs.com）获取 Node、npm 和 Yarn。

但根据你的环境，可能需要让 Volta 从其他源下载（例如，用于内部工具的 npm Enterprise）。为满足这一需求，Volta 在下载过程中提供了钩子机制。

在哪里指定钩子

钩子始终在名为 hooks.json 的文件中设置。

该文件可位于两个位置之一，具体取决于你希望这些钩子生效的范围：

• 在 Volta 目录中指定的钩子（Linux/MacOS 上为 ~/.volta/hooks.json，Windows 上为 %LOCALAPPDATA%\Volta\hooks.json）将在整个系统中生效。
• 在项目的 .volta 子目录中指定的钩子（<项目根目录>/.volta/hooks.json）仅在该项目内生效。此处的 <项目根目录> 定义为该项目的 package.json 所在位置。

钩子文件格式

hooks.json 的内容必须是一个对象，包含针对每种工具（当前为 node、npm 和 yarn）的可选键。每种工具都有 3 个操作，每个操作都可以应用一个钩子：

• index：表示用于确定该工具可下载版本列表的 URL。访问该 URL 时的响应必须与所选工具的公共索引格式匹配。
• latest：表示用于确定该工具最新版本的 URL。对于 node，响应格式应与 index 相同，确保最新版本是列表中的第一个元素；对于 yarn，响应应仅为原始版本号字符串。
• distro：表示用于下载工具二进制文件的 URL。

最后，每个操作有 3 种可能的钩子（如下所述）可供使用（任何时候每个操作只能指定一个钩子）。以下是 hooks.json 文件的示例：

{
    "node": {
        "index": {
            "bin": "/usr/local/node-lookup"
        },
        "latest": {
            "prefix": "http://example.com/node/"
        },
        "distro": {
            "template": "http://example.com/{{os}}/{{arch}}/node-{{version}}.tar.gz"
        }
    },
    "npm": {
        "index": {
            "prefix": "http://example.com/npm/"
        },
        "latest": {
            "bin": "~/npm-latest"
        },
        "distro": {
            "template": "http://example.com/npm/npm-{{version}}.tgz"
        }
    },
    "yarn": {
        "index": {
            "template": "http://example.com/yarn/{{os}}/{{arch}}/yarn-{{version}}.tgz"
        },
        "latest": {
            "prefix": "http://example.com/yarnpkg/"
        },
        "distro": {
            "bin": "~/yarn-distro"
        }
    }
}

钩子类型

prefix 钩子

prefix 钩子是一种简单的 URL 替换。URL 将使用指定的前缀加上该操作的公共文件名构建。例如，在上述 hooks.json 中，我们为确定 yarn 的最新版本指定了 prefix 钩子。

默认情况下，Volta 会通过请求 https://yarnpkg.com/latest-version 获取最新版本；使用该钩子后，Volta 会尝试访问 http://example.com/yarnpkg/latest-version，即将 latest-version 附加到指定的前缀 http://example.com/yarnpkg/ 之后。

template 钩子

template 钩子允许你指定 URL 模板，其中的通配符将被替换。可用的通配符包括：

• {{os}}：将根据操作系统替换为 darwin（ Darwin 系统，如 macOS）、linux（Linux 系统）或 win（Windows 系统）。
• {{arch}}：将根据系统架构替换为 x86（32 位）或 x64（64 位）。
• {{version}}（仅适用于 distro 操作）：将替换为 Volta 尝试下载的工具的特定版本。
• {{filename}}：将替换为 Volta 要从公共注册表下载的文件的文件名。
• {{ext}}（仅适用于 distro 操作）：将替换为 Volta 期望下载的文件的扩展名。

注意：filename 和 ext 替换仅在 Volta 0.8.4 及更高版本中可用。

以上述示例中的 node.distro 钩子为例，当在 64 位 Linux 系统上获取 node@10.15.3 时，Volta 将尝试从以下 URL 下载 tarball：http://example.com/linux/x64/node-10.15.3.tar.gz。

bin 钩子

bin 钩子是一种通用钩子，它会调用外部脚本来确定 URL。其值是要调用的可执行脚本的路径，URL 将从该脚本的标准输出（stdout）中读取。脚本的标准错误（stderr）会显示给用户，因此可用于显示进度条或等待 spinner（加载动画）。

如果脚本路径是相对路径，则会相对于指定它的 hooks.json 文件进行解析。

在此上下文中，相对路径在 Linux/MacOS 上以 ./ 或 ../ 开头，在 Windows 上以 .\ 或 ..\ 开头。最后，对于 distro 操作钩子，工具的请求版本将作为第一个参数传递给该脚本。

以上述示例中的 yarn.distro 钩子为例，当获取 yarn@1.13.0 时，Volta 将调用 ~/yarn-distro "1.13.0"，并尝试从该钩子返回的 URL 下载 tarball。

提供官网

https://docs.volta.sh/

参考资料 URL

https://docs.volta.sh/guide/getting-started