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 命令不更新

自動切換不工作

版本文件優先級

相關鏈接