fnm 完全指南 - wangshengliang

fnm（Fast Node Manager）基于 Rust 开发，启动速度比 nvm 快 40 倍以上。跨平台支持 macOS、Linux、Windows，是目前最推荐的 Node.js 版本管理工具。

🎯 环境说明：本文基于 fnm v1.37.x 编写。

为什么选择 fnm#

特性	fnm	nvm
语言	Rust	Bash
启动速度	~1ms	~40ms+
Windows	✅ 原生支持	❌ 需要 WSL
自动切换	✅ 内置	❌ 需要额外配置
安装方式	单一二进制	Shell 脚本
兼容性	.nvmrc 兼容	-

✅ fnm 的核心优势在于速度。每次打开终端时，nvm 需要加载大量 Shell 脚本，而 fnm 作为编译后的二进制文件，几乎零延迟。

安装 fnm#

macOS（Homebrew）#

$ brew install fnm

Linux / macOS（安装脚本）#

$ curl -fsSL https://fnm.vercel.app/install | bash

Windows（Scoop）#

> scoop install fnm

Windows（Chocolatey）#

> choco install fnm

Windows（winget）#

> winget install Schniz.fnm

验证安装：

$ fnm --version
fnm 1.37.1

配置 Shell#

fnm 需要在 Shell 配置中添加环境变量才能正常工作。

Zsh#

$ echo 'eval "$(fnm env --use-on-cd --shell zsh)"' >> ~/.zshrc
$ source ~/.zshrc

Bash#

$ echo 'eval "$(fnm env --use-on-cd --shell bash)"' >> ~/.bashrc
$ source ~/.bashrc

Fish#

$ echo 'fnm env --use-on-cd --shell fish | source' >> ~/.config/fish/config.fish

PowerShell#

# 添加到 $PROFILE
fnm env --use-on-cd --shell power-shell | Out-String | Invoke-Expression

--use-on-cd 参数启用目录切换时自动检测 .node-version 或 .nvmrc 文件并切换版本。

安装 Node.js#

# 安装最新 LTS 版本
$ fnm install --lts

# 安装最新版本
$ fnm install latest

# 安装指定主版本的最新版
$ fnm install 20

# 安装精确版本
$ fnm install 20.10.0

查看已安装版本：

$ fnm list

* v20.10.0 default, lts-iron
* v18.19.0 lts-hydrogen
* system

卸载版本：

$ fnm uninstall 18.19.0

切换版本#

# 切换到指定版本
$ fnm use 20

# 切换到 LTS
$ fnm use --lts

# 切换到系统安装的 Node
$ fnm use system

查看当前版本：

$ fnm current
v20.10.0

$ node -v
v20.10.0

设置默认版本#

# 设置默认版本
$ fnm default 20

# 或使用 alias
$ fnm alias 20.10.0 default

设置后，新终端窗口会自动使用该版本。

版本别名#

# 创建别名
$ fnm alias 20.10.0 my-project

# 使用别名切换
$ fnm use my-project

# 查看所有别名
$ fnm list

# 删除别名
$ fnm unalias my-project

内置特殊别名：

别名	含义
`default`	新终端默认版本
`system`	系统安装的 Node（如通过 .pkg）
`lts-*`	LTS 版本代号（iron、hydrogen 等）

项目级版本锁定#

在项目根目录创建 .node-version 或 .nvmrc 文件：

# 写入版本号
$ echo "20" > .node-version

# 或使用 node 命令写入当前版本
$ node -v > .node-version

配置了 --use-on-cd 后，进入项目目录时 fnm 会自动切换到指定版本：

$ cd my-project
Using Node v20.10.0

若本地未安装该版本，fnm 会提示安装。可配置自动安装：

# 在 Shell 配置中添加
eval "$(fnm env --use-on-cd --version-file-strategy=recursive --log-level=quiet)"

递归查找版本文件#

默认情况下，fnm 只在当前目录查找版本文件。使用 --version-file-strategy=recursive 可递归向上查找：

# 在 Monorepo 子目录中也能找到根目录的版本文件
repo/packages/my-package$ fnm use
# 会向上查找到 repo/.node-version

使用 engines.node#

fnm 支持读取 package.json 中的 engines.node 字段（默认启用）：

{
  "engines": {
    "node": ">=20 <21"
  }
}

fnm 会自动解析 semver 范围并使用满足条件的最新版本。

禁用此功能：

eval "$(fnm env --resolve-engines=false)"

团队协作建议#

🤔 通常只需指定主版本号（如 20），避免因次版本或补丁版本差异导致团队成员频繁重装。将 .node-version 提交到版本控制：

环境变量#

fnm 支持通过环境变量自定义行为：

变量	说明	默认值
`FNM_DIR`	fnm 数据目录	`~/.fnm`
`FNM_NODE_DIST_MIRROR`	Node.js 下载镜像	`https://nodejs.org/dist`
`FNM_MULTISHELL_PATH`	多 Shell 支持路径	自动生成
`FNM_VERSION_FILE_STRATEGY`	版本文件查找策略	`local`
`FNM_LOGLEVEL`	日志级别	`info`
`FNM_ARCH`	CPU 架构	自动检测
`FNM_COREPACK_ENABLED`	启用 Corepack	`false`

使用国内镜像加速下载：

export FNM_NODE_DIST_MIRROR="https://npmmirror.com/mirrors/node"

Corepack 集成#

fnm 支持与 Corepack 集成，自动管理 yarn/pnpm：

# 启用 Corepack
$ fnm env --corepack-enabled

# 或设置环境变量
export FNM_COREPACK_ENABLED=true

启用后安装 Node 时会自动启用 Corepack。

常用命令速查#

命令	用途
`fnm install <version>`	安装指定版本
`fnm install --lts`	安装最新 LTS
`fnm uninstall <version>`	卸载版本
`fnm use <version>`	切换版本
`fnm default <version>`	设置默认版本
`fnm current`	显示当前版本
`fnm list`	列出已安装版本
`fnm list-remote`	列出可安装的远程版本
`fnm alias`	管理别名
`fnm env`	输出环境变量
`fnm completions`	生成 Shell 补全脚本

从 nvm 迁移#

迁移前，记录当前 nvm 管理的 Node 版本和全局包：

# 查看已安装版本
$ nvm list

# 查看全局包
$ nvm use 20
$ npm list -g --depth=0

在 fnm 中安装对应版本：

$ fnm install 20
$ fnm install 18

重新安装需要的全局包：

$ npm install -g pnpm typescript

卸载 nvm#

删除 nvm 目录：

$ rm -rf "$NVM_DIR"
# 通常是 ~/.nvm

从 Shell 配置文件（~/.zshrc 或 ~/.bashrc）中移除 nvm 相关配置：

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

卸载 fnm#

若通过 Homebrew 安装：

$ brew uninstall fnm

若通过安装脚本安装，删除二进制文件：

$ rm -rf ~/.fnm

从 Shell 配置中移除 fnm 相关行：

eval "$(fnm env --use-on-cd)"

常见问题#

切换版本后 node 命令找不到#

确保 Shell 配置正确加载。重新打开终端或执行：

$ source ~/.zshrc

自动切换版本不生效#

检查是否使用了 --use-on-cd 参数：

$ grep fnm ~/.zshrc
eval "$(fnm env --use-on-cd --shell zsh)"

下载速度慢#

配置国内镜像：

$ export FNM_NODE_DIST_MIRROR="https://npmmirror.com/mirrors/node"
$ fnm install 20