Node.js 版本管理

fnm 提供了强大的版本管理功能，让你轻松在多个 Node.js 版本之间切换。

基本操作

查看已安装版本

bash

fnm list

输出示例：

* v20.10.0 default
  v18.19.0
  v16.20.2

* 表示当前使用的版本
default 表示默认版本

查看当前版本

bash

fnm current

切换版本

bash

# 切换到指定版本
fnm use 20

# 切换到指定精确版本
fnm use 20.10.0

# 如果版本未安装，自动安装后切换
fnm use 18 --install-if-missing

默认版本

设置默认版本

bash

fnm default 20

默认版本是：

新终端会话启动时使用的版本
没有版本文件时使用的版本

查看默认版本

bash

fnm default

版本别名

别名让你可以为版本设置易于记忆的名称。

创建别名

bash

# 为版本设置别名
fnm alias 20 default
fnm alias 18 legacy
fnm alias 16 old

使用别名

bash

# 通过别名切换版本
fnm use default
fnm use legacy

删除别名

bash

fnm unalias legacy

自动版本切换

fnm 可以根据项目目录自动切换 Node.js 版本。

启用自动切换

在 Shell 配置中添加 --use-on-cd：

bash

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

创建版本文件

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

bash

# 使用 .node-version（推荐）
echo "20" > .node-version

# 或使用 .nvmrc（兼容 nvm）
echo "v18.17.0" > .nvmrc

版本文件格式

.node-version 支持以下格式：

20           # 主版本，使用最新的 20.x.x
20.10        # 次版本，使用最新的 20.10.x
20.10.0      # 精确版本
lts/iron     # LTS 版本名

版本文件解析策略

fnm 支持两种版本文件解析策略：

bash

# local（默认）- 只在当前目录查找
fnm env --version-file-strategy=local

# recursive - 递归向上查找父目录
fnm env --version-file-strategy=recursive

package.json engines 支持

fnm 可以读取 package.json 中的 engines.node 字段：

json

{
  "engines": {
    "node": ">=18.0.0"
  }
}

默认启用，可以通过环境变量禁用：

bash

export FNM_RESOLVE_ENGINES=false

版本管理最佳实践

1. 项目级版本锁定

在每个项目中创建 .node-version 文件：

bash

cd my-project
echo "20" > .node-version
fnm install
fnm use

2. 团队协作

将 .node-version 添加到 Git：

bash

git add .node-version
git commit -m "chore: add .node-version"

3. CI/CD 配置

在 CI/CD 环境中使用 fnm：

yaml

# GitHub Actions
- name: Install fnm
  run: curl -fsSL https://fnm.vercel.app/install | bash

- name: Install Node.js
  run: fnm install && fnm use

4. 多版本开发

bash

# 安装多个版本
fnm install 20
fnm install 18
fnm install 16

# 设置别名便于切换
fnm alias 20 current
fnm alias 18 legacy
fnm alias 16 old

# 在不同项目中使用不同版本
cd project-new && fnm use current
cd project-old && fnm use legacy

卸载版本

bash

# 卸载指定版本
fnm uninstall 16.20.2

# 通过别名卸载（会删除版本和所有相关别名）
fnm uninstall old

常见问题

版本切换后 node 命令不更新

确保 Shell 配置正确：

bash

# 检查 node 路径
which node

# 应该指向 fnm 目录
# ~/.fnm/node-versions/.../bin/node

自动切换不工作

确认 --use-on-cd 已添加到 Shell 配置
确认版本文件存在
重新加载 Shell 配置

版本文件优先级

fnm 按以下顺序查找版本：

命令行指定的版本
.node-version 文件
.nvmrc 文件
package.json 的 engines.node
默认版本

Node.js 版本管理 ​

基本操作 ​

查看已安装版本 ​

查看当前版本 ​

切换版本 ​

默认版本 ​

设置默认版本 ​

查看默认版本 ​

版本别名 ​

创建别名 ​

使用别名 ​

删除别名 ​

自动版本切换 ​

启用自动切换 ​

创建版本文件 ​

版本文件格式 ​

版本文件解析策略 ​

package.json engines 支持 ​

版本管理最佳实践 ​

1. 项目级版本锁定 ​

2. 团队协作 ​

3. CI/CD 配置 ​

4. 多版本开发 ​

卸载版本 ​

常见问题 ​

版本切换后 node 命令不更新 ​

自动切换不工作 ​

版本文件优先级 ​

相关链接 ​

Node.js 版本管理

基本操作

查看已安装版本

查看当前版本

切换版本

默认版本

设置默认版本

查看默认版本

版本别名

创建别名

使用别名

删除别名

自动版本切换

启用自动切换

创建版本文件

版本文件格式

版本文件解析策略

package.json engines 支持

版本管理最佳实践

1. 项目级版本锁定

2. 团队协作

3. CI/CD 配置

4. 多版本开发

卸载版本

常见问题

版本切换后 node 命令不更新

自动切换不工作

版本文件优先级

相关链接