从 nvm 迁移到 fnm

场景:个人 PC 双系统(Windows 11 原生 + Debian),原先都用 nvm 管理 Node.js,现在统一换成 fnm。

一、为什么更换?

2026 年个人机器上 fnm 是更推荐的默认选择,但它不是”必须换”——nvm 依然能用。判断标准是你在意什么:

  • 你在意终端启动速度和切换速度 → 换 fnm(nvm 是 shell 脚本,每个新终端都要 source 一遍;fnm 是 Rust 编译的单文件二进制,启动开销接近 0)。
  • 你在意Windows 原生支持 → 必须换 fnm。nvm 官方不支持 Windows,你现在 Windows 上用的其实是另一个项目 nvm-windows(作者 Corey Butler),它连 .nvmrc 都不读,nvm use 必须手打版本号。这本身就是两套东西、两套行为,长期维护很别扭。
  • fnm 一个工具同时跑 Windows / Linux / macOS,配置语法一致,这是你双系统最实际的收益。
  • 你已经有大量 .nvmrc → 无损迁移,fnm 原生读 .nvmrc 和 .node-version。
  • 如果你需要”跟着 package.json 把 node 和包管理器版本一起钉死给团队” → 那不是 fnm 的活,看 Volta 或 mise。fnm 只管 node 版本。

nvm vs fnm 对照

维度 nvm(POSIX)/ nvm-windows fnm
实现 Shell 脚本 / Go Rust 单文件二进制
终端启动开销 数十~上百 ms < 5 ms
Windows 原生 否(要装另一个项目) 是,同一套命令
读 .nvmrc 是 / Windows 版否 是
读 .node-version 否 是
cd 进目录自动切换 需手写 hook --use-on-cd 内置
支持的 shell bash/zsh/sh bash/zsh/fish/PowerShell
管 npm/pnpm 版本 否 否(交给 corepack)

一句话取舍:nvm 是”最多教程、最广认知”的老牌方案;fnm 是它的事实标准替代品(同命令、同 .nvmrc、更快、跨平台)。只有”团队级可复现构建”才需要考虑 Volta/mise。


二、迁移前必做:先记账(两个系统都要做)

fnm 不会接管 nvm 已装的 node,版本要重建,全局包要重装。先记下来,否则删完就查不到了。

1
2
3
4
5
6
7
8
# 1. 当前装了哪些 node 版本
nvm ls # nvm-windows 用 nvm list

# 2. 每个版本下装了哪些全局包(关键,容易漏)
npm ls -g --depth=0

# 3. 当前在用的版本,先记下来当默认版本
node -v

Windows 上如果多个 node 版本各有一套全局包,逐版本切换后各跑一次 npm ls -g --depth=0。


三、Windows 11:卸载 nvm-windows

nvm-windows 是用符号链接(C:\Program Files\nodejs)指到当前版本目录的方式工作的,卸载不干净就会残留一个假的 node 命令,装完 fnm 后到处报错。按顺序做:

1. 执行官方卸载程序

  • 打开「设置 → 应用 → 已安装的应用」,搜 NVM for Windows,点卸载;
  • 或直接运行 %APPDATA%\nvm\unins000.exe。

2. 删残留目录

路径 说明
%APPDATA%\nvm(即 C:\Users\<你>\AppData\Roaming\nvm) nvm 本体 + 所有 node 版本
C:\Program Files\nodejs nvm 建的符号链接目录,必须删
C:\Users\<你>\AppData\Roaming\npm 旧全局包的 bin 目录(可选清)

PowerShell 里可以先确认再删:

1
2
Test-Path "$env:APPDATA\nvm"
Test-Path "C:\Program Files\nodejs"

删除时注意:C:\Program Files\nodejs 如果是符号链接,删的是链接本身;如果提示占用,说明还有 node 进程在跑,先关掉终端/编辑器。

3. 清环境变量

「Win + R → sysdm.cpl → 高级 → 环境变量」,在用户变量里:

  • 删除 NVM_HOME、NVM_SYMLINK 两条;
  • 编辑 Path,删掉 %NVM_HOME%、%NVM_SYMLINK% 及任何 ...\nvm、...\nodejs 条目;
  • 系统变量里如果有同名条目一并删。

4. 验证卸载干净

必须新开一个终端(环境变量改动不会继承到已开的终端):

1
2
3
where.exe nvm      # 期望:找不到(报 INFO: Could not find files)
where.exe node # 期望:找不到
where.exe npm

三条都找不到,才算干净。这一步不做,后面 fnm 装的 node 会和残留打架。


四、Windows 11:安装 fnm

1. 安装

1
winget install Schniz.fnm

备选:scoop install fnm / choco install fnm / cargo install fnm。

2. 接进 PowerShell

fnm 需要往当前 shell 注入环境变量,这行必须写进 profile,否则每个新终端都得手动 eval。

先确认 profile 文件存在(PowerShell 7 和 Windows PowerShell 的 profile 路径不同,别写错文件):

1
2
if (-not (Test-Path $profile)) { New-Item $profile -Force }
Invoke-Item $profile

在打开的 profile 里加一行:

1
fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression

说明:

  • --use-on-cd:cd 进入带 .nvmrc / .node-version 的目录时自动切版本(这是 fnm 相对 nvm 最舒服的地方);
  • 仓库是 monorepo 时加 --version-file-strategy=recursive,让 fnm 往上找最近的版本文件,否则进到子包目录就不切了。

3. 重启终端并验证

1
2
3
fnm --version
fnm list # 应该是空的
node -v # 报错才是正常,说明还没有 node

注意:如果用 VS Code / Windows Terminal,父进程是旧终端时新开的标签页可能继承旧环境变量,完全退出应用再开。


五、Debian:卸载 nvm(nvm-sh)

Debian 上装的是官方 nvm-sh(bash 脚本版)。卸载本质就是”删目录 + 删 shell 里的 source 行”。

1. 记录 + 停用

1
2
3
nvm ls
npm ls -g --depth=0
nvm deactivate # 从当前 shell 摘掉 node 路径

2. 清 shell 配置里的 nvm 行

编辑 ~/.bashrc、~/.zshrc(如果你用 zsh 就两个都看)、~/.profile,删掉类似这几行(不同版本略有差异):

1
2
3
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

zsh 用户还可能有 nvm_load_nvmrc 之类的自定义 hook,一并删。

3. 删目录

1
rm -rf "$HOME/.nvm"

这个目录里装着 nvm 自己以及所有 node 版本,rm -rf 不可恢复。执行前确认上面第二步的记录还在。

4. 检查是否还有系统级 node 残留

1
2
which node npm       # 期望:无输出
dpkg -l | grep -i nodejs

如果之前用 apt 装过(sudo apt install nodejs),那是独立于 nvm 的一套,需要另外处理:

1
2
sudo apt purge nodejs npm
sudo apt autoremove

5. 验证

1
2
exec bash            # 或退出重开终端
command -v nvm # 无输出即成功

六、Debian:安装 fnm

1. 安装(官方脚本,推荐)

先确保有 curl 和 unzip:

1
2
sudo apt update && sudo apt install -y curl unzip
curl -fsSL https://fnm.vercel.app/install | bash

其他方式:

1
2
3
brew install fnm                     # 有 Homebrew 的话
cargo install fnm # 有 Rust
# 或从 GitHub Releases 下 fnm-linux.zip 手动放进 PATH

2. 接进 shell

Debian 默认 bash,写进 ~/.bashrc:

1
eval "$(fnm env --use-on-cd --shell bash)"

zsh 用户写进 ~/.zshrc,并把 --shell bash 换成 --shell zsh。
用 fish 的,安装脚本会自动写 ~/.config/fish/conf.d/fnm.fish,一般不用管。

然后:

1
2
source ~/.bashrc
fnm --version

小坑:官方脚本默认会把 eval 行追加到 ~/.bashrc;如果你已经手动加过,会出现两行重复 —— 保留一行即可。另外,Debian 上 ~/.bashrc 只对交互式 shell 生效,脚本里用 node 记得显式 fnm use 或用 #!/usr/bin/env -S bash -i。


七、用 fnm 装 Node(两个系统命令完全一致)

装哪个版本

1
2
fnm list-remote              # 看远端可装版本
fnm list-remote --lts # 只看 LTS

安装 / 切换 / 设默认

1
2
3
4
5
6
7
8
9
fnm install --lts            # 装最新 LTS
fnm install 22 # 装指定大版本(会装该大版本最新小版本)
fnm install 20.11.1 # 装精确版本

fnm use 22 # 当前 shell 临时切到 22
fnm default 22 # 设为全局默认(新终端默认用这个)
fnm current # 看当前用的是哪个
fnm list # 看已装列表
node -v && npm -v # 验证

一次重建你在 nvm 里用过的版本

1
2
fnm install 18 && fnm install 20 && fnm install 22
fnm default 22

项目级版本固定(迁移的核心价值)

任选一种写进仓库根目录:

1
2
echo "22" > .node-version      # fnm 优先读这个
echo "22" > .nvmrc # 老项目已有,fnm 直接兼容

之后 cd 进目录会自动切换(前提是 shell 里带 --use-on-cd)。手动也行:

1
2
fnm use                # 不带参数 = 读当前目录的 .node-version / .nvmrc
fnm use --silent-if-unchanged

别名与卸载

1
2
3
fnm alias 22 default         # 给版本起别名
fnm uninstall 18 # 删掉某个版本
fnm uninstall 18 --keep-version-file # 保留版本文件引用

顺手把 pnpm / yarn 管起来

fnm 不管包管理器版本,交给 corepack(Node 16.9+ 自带):

1
2
corepack enable
corepack prepare pnpm@latest --activate

或用 fnm 的开关(装 node 时一起开):

1
fnm install --lts --corepack-enabled

八、国内网络:换 node 下载镜像

fnm 通过环境变量 FNM_NODE_DIST_MIRROR 指定下载源,官方默认 https://nodejs.org/dist 在国内经常慢/断。

Debian(写进 ~/.bashrc,放在 fnm eval 行之前)

1
2
export FNM_NODE_DIST_MIRROR="https://npmmirror.com/mirrors/node/"
eval "$(fnm env --use-on-cd --shell bash)"

Windows 11(PowerShell profile 或用户环境变量)

1
2
$env:FNM_NODE_DIST_MIRROR = "https://npmmirror.com/mirrors/node/"
fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression

要永久生效就在「环境变量」里新建用户变量 FNM_NODE_DIST_MIRROR。
npm 本身的 registry 另配:npm config set registry https://registry.npmmirror.com。


九、踩坑清单

  1. Windows 上没删 C:\Program Files\nodejs → node 命令仍指向旧版本或直接损坏。装 fnm 前必须 where.exe node 无输出。
  2. 改了环境变量不重开终端 → 看起来”装成功但命令找不到”。winget 装完、改完 Path,全部重开终端,必要时重启。
  3. PowerShell profile 写错文件 → PowerShell 7 的 $profile 是 ...\Documents\PowerShell\Microsoft.PowerShell_profile.ps1,Windows PowerShell 5.1 是 ...\Documents\WindowsPowerShell\...。你在 pwsh 里配的,cmd/旧 PS 里不生效,属正常。
  4. 全局包全部消失 → 正常现象。全局包按 node 版本隔离存放,fnm use 到新版本后要重新 npm i -g。迁移前用 npm ls -g --depth=0 记好清单。
  5. .nvmrc 读到了但不切换 → 检查 eval 行有没有 --use-on-cd;monorepo 再加 --version-file-strategy=recursive。
  6. 两个系统共用一份 dotfiles 仓库 → 用 --shell bash / --shell powershell 区分,别把 PowerShell 那行塞进 .bashrc。
  7. 想同时管 Python/Go → fnm 只管 node,这类需求看 mise,别硬塞给 fnm。
  8. 别用 sudo npm install -g → 一旦用 root 装全局包,node 在用户目录的权限模型会被破坏,后续 fnm 切换版本会出现奇怪报错。

十、速查表

目的 nvm(旧) fnm(新)
装 LTS nvm install --lts fnm install --lts
装指定版本 nvm install 22 fnm install 22
切版本 nvm use 22 fnm use 22
读目录版本文件 nvm use fnm use
设默认 nvm alias default 22 fnm default 22
列已装 nvm ls fnm list
列可装 nvm ls-remote fnm list-remote
删版本 nvm uninstall 22 fnm uninstall 22
当前版本 nvm current fnm current
自动切换 手写 hook --use-on-cd 内置

参考资料