fnm 常用命令

2026-07-20 15:04:25

fnm 是什么

fnm（Fast Node Manager）是一个使用 Rust 编写的 Node.js 版本管理器，支持 macOS、Linux 和 Windows。它可以在同一台电脑上安装多个 Node.js 版本，并根据不同项目的要求快速切换版本。

fnm 支持 .node-version、.nvmrc，也可以读取 package.json 中的 engines.node。如果之前使用 nvm，通常可以直接沿用项目中的 .nvmrc 文件。

安装 fnm

macOS 或 Linux：使用 Homebrew

1
brew install fnm

升级 fnm：

1
brew upgrade fnm

macOS 或 Linux：使用官方安装脚本

执行前需要先安装 curl 和 unzip：

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

再次运行脚本升级时，可以添加 --skip-shell，避免重复修改 Shell 配置：

1
curl -fsSL https://fnm.vercel.app/install | bash -s -- --skip-shell

fnm 官方目前建议 macOS 用户优先通过 Homebrew 安装；安装脚本在 macOS 上默认也会使用 Homebrew。

Windows

可以选择系统中已有的包管理器：

1
2
3
4
5
6
7
8
# Windows Package Manager
winget install Schniz.fnm

# Scoop
scoop install fnm

# Chocolatey
choco install fnm

更多安装方式和参数请查看官方的 Installation 说明。

配置 Shell

仅安装 fnm 还不够，需要让 Shell 执行 fnm env 输出的环境配置。官方建议明确写出 Shell 类型，这样启动稍快，也不需要在运行时推断 Shell。

Zsh

将下面的内容加入 ~/.zshrc：

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

然后执行：

1
source ~/.zshrc

Bash

将下面的内容加入 ~/.bashrc：

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

Fish

将下面的内容加入 ~/.config/fish/conf.d/fnm.fish：

1
fnm env --use-on-cd --shell fish | source

PowerShell

将下面的内容加入 PowerShell Profile：

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

可以通过 $PROFILE 查看 Profile 路径，通过以下命令创建文件：

1
if (-not (Test-Path $PROFILE)) { New-Item $PROFILE -Force }

配置中的 --use-on-cd 会在进入项目目录时，根据版本文件自动切换 Node.js。fnm 官方将其列为推荐配置，详细说明见 Configuration。

验证安装和环境配置：

1
2
fnm --version
fnm --help

查看可安装的 Node.js 版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 列出全部远端 Node.js 版本
fnm list-remote

# 只列出 LTS 版本
fnm list-remote --lts

# 从新到旧排列 LTS 版本
fnm list-remote --lts --sort desc

# 只显示最新的 LTS 版本
fnm list-remote --lts --latest

# 查看符合指定范围的最新版本
fnm list-remote --filter "22" --latest

fnm ls-remote 是 fnm list-remote 的别名。

安装 Node.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# 安装最新的 LTS 版本
fnm install --lts

# 安装最新版，不限定是否为 LTS
fnm install --latest

# 安装指定的大版本，fnm 会解析为该系列的合适版本
fnm install 22

# 安装精确版本
fnm install 22.17.0

# 安装后立即切换到该版本
fnm install --lts --use
fnm install 22 --use

版本参数可以是完整版本、部分版本，也可以是 LTS 代号。日常开发通常优先选择 LTS 版本。

切换 Node.js 版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 切换到已经安装的 Node.js 22
fnm use 22

# 如果本地没有该版本，则先安装再切换
fnm use --install-if-missing 22

# 根据当前目录中的版本文件切换
fnm use

# 查看当前使用的版本
fnm current

# 同时验证 node 命令实际使用的版本
node --version

fnm use 只影响当前 Shell 会话；如果希望新终端默认使用某个版本，还需要设置默认版本。

设置默认版本

1
2
3
4
5
# 将 Node.js 22 设为默认版本
fnm default 22

# 查看当前默认版本
fnm default

fnm default 22 等价于为该版本设置名为 default 的别名。设置后，在没有项目版本要求时，新 Shell 会话会使用这个版本。

查看已安装版本

1
2
3
4
5
6
7
8
# 列出本地已经安装的 Node.js 版本和别名
fnm list

# 简写形式
fnm ls

# 查看当前正在使用的版本
fnm current

为项目固定 Node.js 版本

推荐在项目根目录提交 .node-version 或 .nvmrc，让团队成员和 CI 使用一致的 Node.js 版本。

使用 `.node-version`

1
2
# 把当前 Node.js 的完整版本写入文件
node --version > .node-version

文件内容示例：

1
v22.17.0

使用 `.nvmrc`

1
22

配置了 fnm env --use-on-cd 后，进入项目目录就会自动切换版本。没有配置自动切换时，可以手动执行：

1
2
3
4
5
# 根据版本文件安装 Node.js
fnm install

# 根据版本文件切换 Node.js
fnm use

如果是 monorepo，希望在子目录中也能向上查找根目录的版本文件，可以在 Shell 初始化配置中加入 --version-file-strategy=recursive：

1
eval "$(fnm env --use-on-cd --version-file-strategy=recursive --shell zsh)"

在没有 .node-version 或 .nvmrc 时，当前 fnm 也会尝试解析 package.json 中的 engines.node，并选择满足 semver 范围的版本：

1
2
3
4
5
{
  "engines": {
    "node": ">=22 <23"
  }
}

管理版本别名

别名适合为常用版本取一个容易记忆的名字：

1
2
3
4
5
6
7
8
# 将 Node.js 22 设置为 work 别名
fnm alias 22 work

# 使用该别名
fnm use work

# 删除别名
fnm unalias work

默认版本实际上也是一个特殊别名：

1
fnm alias 22 default

一般直接使用更直观的 fnm default 22 即可。

临时使用指定版本运行命令

fnm exec 可以在不改变当前 Shell 版本的情况下，临时使用指定版本执行命令：

1
2
3
4
5
6
7
8
# 使用 Node.js 22 查看版本
fnm exec --using=22 node --version

# 使用 Node.js 22 运行 npm 测试
fnm exec --using=22 npm test

# 使用版本文件指定的版本执行命令
fnm exec --using=.node-version node app.js

这个命令适合在脚本或 CI 中对多个 Node.js 版本进行测试。

卸载 Node.js 版本

1
2
3
4
5
# 先确认本地版本
fnm list

# 卸载指定版本
fnm uninstall 20.19.4

fnm uni 是 fnm uninstall 的别名。卸载时如果传入别名，fnm 会删除该别名指向的 Node.js 版本，并同时删除所有指向同一版本的别名，因此执行前应先运行 fnm list 确认目标。

生成命令补全

fnm 可以为 Bash、Zsh、Fish 和 PowerShell 输出补全脚本：

1
2
3
4
fnm completions --shell zsh
fnm completions --shell bash
fnm completions --shell fish
fnm completions --shell powershell

补全脚本的加载位置和方式取决于所使用的 Shell 或补全框架。

常用工作流

第一次安装 fnm

1
2
3
4
brew install fnm
fnm install --lts --use
fnm default $(fnm current)
node --version

其中 fnm default $(fnm current) 会把当前正在使用的 Node.js 版本设为默认版本。

进入已有项目

1
2
3
4
cd <项目目录>
fnm install
fnm use
node --version

如果已配置 --use-on-cd，进入目录时会自动切换；本地缺少项目要求的版本时，再执行一次 fnm install 即可。

创建新项目

1
2
fnm install --lts --use
node --version > .node-version

记得将 .node-version 提交到 Git 仓库。

常见问题

安装后提示 `fnm: command not found`

先重新打开终端，或者重新加载 Shell 配置：

1
2
3
4
5
# Zsh
source ~/.zshrc

# Bash
source ~/.bashrc

如果仍然找不到命令，检查 fnm 是否已加入 PATH，并确认安装脚本是否修改了正确的 Shell 配置文件。

`fnm` 能运行，但 `node` 找不到或版本没有切换

通常是因为 Shell 没有执行 fnm env 的输出。确认 ~/.zshrc、~/.bashrc 或 PowerShell Profile 中存在对应的初始化命令，然后重新打开终端。

npm 全局包为什么不见了

不同 Node.js 版本拥有各自的全局 npm 安装目录。切换版本后，之前通过 npm install -g 安装的命令不一定存在，需要在新版本下重新安装。项目依赖应保存在 package.json 中，通过 npm install、npm ci、pnpm install 或 yarn install 恢复。

常用命令速查

命令	用途
`fnm list-remote --lts --sort desc`	查看可安装的 LTS 版本
`fnm install --lts --use`	安装并立即使用最新 LTS
`fnm install 22`	安装 Node.js 22 系列
`fnm use 22`	在当前 Shell 切换到 Node.js 22
`fnm use --install-if-missing 22`	缺少版本时自动安装并切换
`fnm default 22`	设置新 Shell 默认使用的版本
`fnm list`	查看本地已安装版本和别名
`fnm current`	查看当前使用的 Node.js 版本
`fnm install`	根据项目版本文件安装
`fnm use`	根据项目版本文件切换
`fnm exec --using=22 <命令>`	临时使用指定版本运行命令
`fnm uninstall <版本>`	卸载指定 Node.js 版本