【备忘清单】 请求: volta

### 说明项目

# volta 使用指南

## 简介

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

## 特性

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

## 为何选择 Volta？

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

## 安装 Volta

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

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

对于 bash、zsh 和 fish shells，此安装程序会自动更新你的控制台启动脚本。如果你希望阻止对控制台启动脚本的修改，请参阅 “[跳过 Volta 设置](https://docs.volta.sh/advanced/installers#skipping-volta-setup)”。要手动配置 shell 以使用 Volta，请编辑你的控制台启动脚本，执行以下操作：

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

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

```bash
winget install Volta.Volta
```

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

### 选择默认（全局）的 Node 版本
这是全系统默认的 Node 版本，特定项目设置了指定版本的除外。

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

```bash
volta install node@22.5.1
```

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

```bash
volta install node
```

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

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

```bash
volta pin node@22.5.1
```

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

```bash
volta pin node
```

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

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

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

用法：
```bash
volta [FLAGS] [SUBCOMMAND]
```

标志（FLAGS）：
```bash
--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` 目录

```bash
rm -rf ~/.volta
```

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

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

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

### Windows 系统卸载

在 Windows 上，卸载 Volta 可以通过在[开始 > 设置 > 应用](ms-settings:appsfeatures)的列表中选中它，然后选择 “卸载”。

## 钩子（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` 文件的示例：

```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