Node.js 多版本管理工具 nvm 的安裝與使用教程（含鏡像加速與常見坑）

適用人群：前端/后端/全棧開發者，Mac/Linux/Windows（nvm-windows）用戶；需要在多項目間快速切換 Node 版本、或在國內網絡環境下穩定安裝 Node。

一、為什么要用 nvm？

一機多版本：不同項目依賴不同 Node 版本（如 16.x / 18.x / 20.x），nvm 可以一條命令切換。
對系統無侵入：不需要 sudo，不污染系統路徑，卸載也很干凈。
項目級約束：配合 .nvmrc 固定項目 Node 版本，團隊一致性更好。
鏡像可配：國內可配置鏡像源，大幅提升安裝速度與成功率。

最佳實踐：開發機使用 nvm 管理 Node，避免系統級安裝（如 brew install node 或官方 pkg）造成 PATH 沖突。

二、TL;DR 快速開始（Mac/Linux，推薦）

# 1）可選：國內加速（建議先設置）
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
export NVM_IOJS_ORG_MIRROR=https://npmmirror.com/mirrors/iojs# 2）安裝 nvm（以 v0.39.7 為例，可改最新穩定版）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 或
#wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash# 3）讓當前 Shell 生效（Zsh 常用）
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"# 4）裝一個穩定 LTS 版本并使用
nvm install --lts
nvm use --lts
node -v && npm -v

若重開終端后 nvm 不生效，請將 第3步的兩行加入 ~/.zshrc 或 ~/.bashrc，并執行 source ~/.zshrc（或重開終端）。

三、安裝 nvm（詳細版）

3.1 macOS / Linux（官方腳本，推薦）

準備鏡像環境（可選但強烈推薦）

echo 'export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node' >> ~/.zshrc
echo 'export NVM_IOJS_ORG_MIRROR=https://npmmirror.com/mirrors/iojs' >> ~/.zshrc
source ~/.zshrc

執行官方安裝腳本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 或 wget -qO-

寫入 Shell 啟動配置（安裝腳本通常會自動寫入，若未成功手動添加）

# Zsh（macOS 新系統默認）
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc# Bash
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.bashrc
source ~/.bashrc

驗證安裝
```
command -v nvm
nvm --version
```

3.2 macOS（Homebrew 方式，次選）

說明：nvm 官方推薦腳本安裝。若使用 Homebrew，需要手動設置環境變量并創建工作目錄。

brew install nvm
mkdir -p ~/.nvm# Apple Silicon（M 系，Homebrew 默認前綴 /opt/homebrew）
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc# Intel Mac（Homebrew 前綴 /usr/local）
# echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
# echo '[ -s "/usr/local/opt/nvm/nvm.sh" ] && . "/usr/local/opt/nvm/nvm.sh"' >> ~/.zshrcsource ~/.zshrc
nvm --version

避免沖突：若機器上曾用 brew install node 或官方 pkg 安裝 Node，請先卸載它們（或至少確保 PATH 順序讓 nvm 管理的 Node 優先）。

3.3 Windows（nvm-windows）

Windows 下常用的是 nvm-windows（與 nvm 項目不同代碼庫，但命令類似）。
安裝步驟：
1. 卸載先前用官方 msi 安裝的 Node（如已安裝）。
2. 下載并安裝 nvm-setup（管理員運行）。
3. 安裝時選擇 nvm 根目錄 與 Node 安裝目錄（默認即可）。
4. 通過命令提示符/PowerShell 使用：
```
nvm version
nvm node_mirror https://npmmirror.com/mirrors/node
nvm npm_mirror https://npmmirror.com/mirrors/npm
nvm install lts
nvm use lts
node -v
```
差異提示：nvm-windows 使用全局 symlink 切換 Node，切換時需要管理員權限的情況更多；.nvmrc 文件不自動生效（可寫腳本或使用工具實現）。

四、常用命令速查

# 安裝/切換
nvm install <version>           # 例如：nvm install 20.18.0 / nvm install --lts / nvm install node(最新)
nvm use <version>               # 切換到指定版本
nvm alias default <version>     # 設置默認版本（新終端自動使用）
nvm uninstall <version>         # 卸載某版本# 查詢
nvm ls                          # 查看本機已安裝版本
nvm ls-remote                   # 查看可安裝版本（受鏡像/網絡影響）
nvm current                     # 當前使用版本# 遷移全局包（例如從 16 遷移到 18）
nvm reinstall-packages 16

小技巧：nvm install --lts --latest-npm 可在安裝 LTS 的同時升級到較新的 npm（不同版本行為可能略有差異）。

五、項目內固定 Node 版本（`.nvmrc`）

在項目根目錄創建 .nvmrc：
```
v18
# 或 18.20.3 / lts/* / v20
```

使用（進入項目目錄后）：

nvm use        # 讀取 .nvmrc 自動切換
nvm install    # 如未安裝會直接安裝 .nvmrc 指定的版本

自動切換建議：
- Zsh 用戶可使用插件（如 zsh-nvm）或 direnv 在進入目錄時自動執行 nvm use。

六、國內網絡環境與加速策略

Node 鏡像：

export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
export NVM_IOJS_ORG_MIRROR=https://npmmirror.com/mirrors/iojs

npm 源（按需）：

npm config set registry https://registry.npmmirror.com
# 恢復官方源：
# npm config set registry https://registry.npmjs.org

代理（公司/校園網）：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

Apple Silicon 注意：優先安裝 arm64 對應的 Node 版本，避免 Rosetta 兼容層導致的二進制不匹配。

七、與包管理器協作（npm / pnpm / yarn / corepack）

npm：隨 Node 安裝，不同 Node 版本對應不同的全局包目錄。
pnpm / yarn：
- Node 新版本中內置 Corepack（部分版本需手動啟用）：
```
corepack enable
# 指定版本
corepack prepare pnpm@latest --activate
```
- 項目建議使用鎖文件（package-lock.json / pnpm-lock.yaml / yarn.lock）保障一致性。
不要在 nvm 場景下修改 npm 全局 prefix 到系統路徑，也不要使用 sudo npm -g。

八、常見問題（FAQ）與排查

nvm: command not found
- 是否把下列內容寫入了 shell 配置文件（~/.zshrc 或 ~/.bashrc）并 source？
```
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
```
- 是否開啟了新終端？是否有安全軟件阻攔？
node 版本切換后仍不生效
- 可能 PATH 中仍有系統 Node（如 Homebrew/官方 pkg）優先生效。
- 解決：卸載系統 Node，或確保 nvm 管理的路徑在 PATH 前。
安裝 Node 速度慢或失敗
- 確認鏡像變量 NVM_NODEJS_ORG_MIRROR 已設置并生效。
- 公司/學校網絡需配置 HTTP/HTTPS 代理。
全局包丟失（切換版本后找不到全局命令）
- 不同 Node 版本的全局包隔離。使用：
```
nvm reinstall-packages <舊版本號>
```
nvm 與 Homebrew 沖突
- 若曾 brew install node，請卸載或保證 nvm 的 node 在 PATH 前。
Windows 下切換失敗或權限問題
- 以管理員身份運行 PowerShell；關閉占用 Node 的進程；必要時重啟終端。

九、團隊協作與 CI 提示

在倉庫根目錄提供：
- .nvmrc（如 v18）
- 包管理器鎖文件（確保依賴可重復安裝）
CI（GitHub Actions/GitLab CI）不必安裝 nvm，可直接使用官方 setup-node/runner 的 node，但本機開發與 CI 的 Node 版本務必一致（遵循 .nvmrc）。

十、最佳實踐清單（可直接套用）

安裝前先設置鏡像：NVM_NODEJS_ORG_MIRROR。
統一使用 LTS：nvm install --lts && nvm alias default lts/*。
每個項目放一個 .nvmrc，并在進入項目目錄后執行 nvm use。
不使用 sudo npm -g，需要的 CLI 盡量 npx 或加到 devDependencies。
切換大版本后執行 nvm reinstall-packages 遷移常用全局包。
避免同時存在系統級 Node 與 nvm Node；若必須共存，確保 PATH 順序正確。

最后小總結

使用 nvm 管理 Node 版本是本地開發環境的“地基工程”。配置好鏡像與 .nvmrc 后，你的多項目協作、版本切換、團隊一致性都會顯著提升。如果你在安裝或切換過程中遇到特殊報錯，歡迎在評論區貼出你的系統信息與命令輸出，一起排查。

本文來自互聯網用戶投稿，該文觀點僅代表作者本人，不代表本站立場。本站僅提供信息存儲空間服務，不擁有所有權，不承擔相關法律責任。
如若轉載，請注明出處：http://www.pswp.cn/bicheng/94828.shtml
繁體地址，請注明出處：http://hk.pswp.cn/bicheng/94828.shtml
英文地址，請注明出處：http://en.pswp.cn/bicheng/94828.shtml

如若內容造成侵權/違法違規/事實不符，請聯系多彩編程網進行投訴反饋email:809451989@qq.com，一經查實，立即刪除！