Question 1

如何修复在 zsh 中加载 nvm.sh 时出现的 nvm 错误 "cdhist: error: unrecognized arguments: -q"？

Accepted Answer

出现这种情况是因为 `cdhist` 提供的用户自定义 `cd` shell 函数遮蔽了 zsh 内置的 `cd`。nvm 在 zsh 中执行 `cd -q`，但 `cdhist` 不支持 `-q` 选项，导致 `NVM_DIR` 变为 `/`。

将 nvm 升级到包含 `nvm_cd` 修复的版本，该修复会绕过用户自定义的 `cd` 函数，直接调用 shell 内建命令。

即时补丁：打开 `~/.nvm/nvm.sh`，找到 `nvm_cd()`，将其修改为：

```sh
nvm_cd() {
  if nvm_is_zsh; then
    builtin cd "$@"
  else
    command cd "$@"
  fi
}
```

然后重新加载：

```sh
source ~/.nvm/nvm.sh
```

仅对当前 shell 生效的临时解决方案：

```sh
unset -f cd
source ~/.nvm/nvm.sh
```

这会禁用 `cdhist` 的 `cd` 函数，直到 shell 重新启动。

Question 2

如何修复 nvm 的安装脚本将 bash_completion 追加到 ~/.bashrc 最后一行的问题？

Accepted Answer

当 `~/.bashrc` 末尾没有换行符,且其中已包含匹配 `nvm.sh` 的行时,nvm v0.40.8 的安装程序就会出现此问题;补全行会被直接追加到现有行之后,而不会另起一行。要修复此问题,请打开 `~/.bashrc`,将 nvm 补全代码片段移到单独的一行:

```bash
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion
```

在重新运行安装程序之前,请确保文件以换行符结尾:

```bash
[ -n "$(tail -c1 ~/.bashrc)" ] && printf '
' >> ~/.bashrc
```

然后重新运行最新的 nvm 安装程序,该版本已包含修复:在向末尾没有换行符的配置文件追加内容之前,会先写入一个换行符。

Question 3

在没有单独安装 Node.js 的情况下，如何修复 macOS 上 nvm 出现的 "not compatible with the npm config prefix option" 错误？

Accepted Answer

当 macOS 报告的主目录路径大小写与实际文件夹不一致时，就会出现这种情况，通常发生在 Time Machine 恢复或账户迁移之后——例如，`$HOME` 为 `/Users/mitch`，而实际文件夹为 `/Users/Mitch`。使用以下命令对比路径：

```sh
echo "$HOME"
whoami
ls -ld /Users/*
```

如果大小写不一致，请更正主目录路径：

1. 备份你的 Mac，并退出登录受影响的账户。
2. 前往 **系统偏好设置 → 用户与群组**（System Preferences → Users & Groups）。
3. 右键点击你的用户，选择 **高级选项**（Advanced Options）。
4. 将 **主目录**（Home directory）设置为实际的大写路径，例如 `/Users/Mitch`。
5. 保存并重启 Mac，然后重新打开 Terminal。
6. 如果 nvm 仍报告某个已安装版本的 prefix 问题，请运行：

```sh
nvm use --delete-prefix v14.5.0
```

将 `v14.5.0` 替换为 nvm 所安装的 Node 版本。更新 nvm 也可能会针对这种情况显示更完善的警告；该检测问题已在 nvm PR #2263 中得到解决。

Question 4

为什么 nvm 会导致 zsh 启动变慢，以及如何减少这种延迟？

Accepted Answer

延迟主要是由 nvm 在加载 `nvm.sh` 时自动运行 `nvm use default` 造成的。通过在加载 nvm 时加上 `--no-use`，可以推迟该版本选择。

在 `~/.zshrc` 中，将：

```sh
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
```

替换为：

```sh
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" --no-use
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
```

重启 shell：

```sh
exec zsh
```

在该 issue 的基准测试中，正常加载耗时约 303 毫秒，而使用 `--no-use` 可将 shell 启动时间缩短至约 75 毫秒；加载 nvm 本身大约花费 44 毫秒，其余时间都花在了自动选择默认版本上。

使用 `--no-use` 后，当需要使用 Node 时，运行以下命令：

```sh
nvm use default
```

或者，仅在首次调用 `nvm`、`node`、`npm` 或 `npx` 时才懒加载 nvm：

```sh
export NVM_DIR="$HOME/.nvm"

_lazy_load_nvm() {
  unset -f nvm node npm npx
  [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
  [ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
}

nvm() { _lazy_load_nvm; nvm "$@"; }
node() { _lazy_load_nvm; node "$@"; }
npm() { _lazy_load_nvm; npm "$@"; }
npx() { _lazy_load_nvm; npx "$@"; }
```

使用以下命令测量启动时间：

```sh
hyperfine --warmup 3 'zsh -i -c exit'
```

Question 5

为什么在 Windows 主机上已安装 Node.js/npm 的情况下，在 WSL 上安装 nvm 会失败？

Accepted Answer

**原因：** nvm 的安装脚本会调用 `npm`（通过 `nvm_check_global_modules`）。在 WSL 上，Windows 路径默认会被追加到 `$PATH` 中，因此 `npm` 可能会解析为 `/mnt/c/Program Files/nodejs/npm` —— 这是随 Windows 版 Node.js 安装附带的一个 shell 脚本，它会执行 Windows 的 `node.exe`。这会导致安装失败。

**解决方法 1 —— 阻止 Windows PATH 泄漏到 WSL（推荐）：**
1. 在 WSL 中创建/编辑 `/etc/wsl.conf`：
   ```ini
   [interop]
   appendWindowsPath = false
   ```
2. 在 Windows 上的 PowerShell 中运行 `wsl --shutdown`，然后重新打开 WSL 终端。
3. 重新运行 nvm 安装脚本。

**解决方法 2 —— 仅在安装期间临时移除 Windows 路径：**
```sh
PATH=$(echo "$PATH" | tr ':' '
' | grep -v '^/mnt/c' | paste -sd: -)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
```

使用 `which npm` 进行验证 —— 它不应指向 `/mnt/c/...`。nvm 本身的一个修复方案（当 `npm` 旁边存在 Windows 的 `node.exe` 时跳过 npm 检查）已被提出，因此在该修复发布后升级 nvm 也可能解决此问题。

nvm

项目简介

README 预览

常见问题 (5)

同类型项目

hermes-agent

firecrawl

go

markitdown