Node.js 安装与环境配置：版本管理是重点

Node.js 安装与环境配置：版本管理是重点

引言

前端开发绕不开 Node.js，这点不用多说。但"装 Node.js"这件事，网上教程各说各话：有人让你下官网安装包，有人让你用 nvm，还有人喊你用包管理器。新手照着装完，很快就在第一个项目上卡住——“这个项目要求 Node 18，你现在是 Node 22，跑不起来”。

安装 Node 真正的重点不是"装一个能用的"，而是版本管理。一台电脑上同时存在多个 Node 版本、随时切换，才是正规的开发姿势。今天切 Node 18 跑老项目，明天切 Node 22 开新项目，用 nvm 都是一条命令的事。这篇文章以 nvm 为主线，把 Windows 和 macOS 两条路讲清楚，版本切换、国内源、全局目录这些坑一次性填平。

文中所有版本号以官方文档为准。

安装方式对比：动手之前先想清楚

几种方式放在一起看，免得装完后悔再重来。差异主要在"能不能管版本"和"装出来干不干净"。

结论很直白：正经做开发，选 nvm。官网安装包适合救急，包管理器装出来的版本经常落后一两个大版本，权限坑也多。下面重点讲 nvm。

补充一个边界情况：如果你只是写个脚本、练练语法，短期内不打算做多项目，那官网安装包完全够用，别被"必须用 nvm"的说法吓住。一旦开始同时维护两个以上项目，或者经常要配合老项目切版本，再换成 nvm 也不迟，迁移成本不高。现在多数团队直接要求 nvm，入职配环境时也省得你解释版本从哪来的。

安装方式的选择，本质上是在"省事"和"可控"之间做取舍：官网安装包省事但不可控，nvm 稍微多点学习成本但完全可控。多数人最终都会走向可控这一边，早点切过去不亏。

nvm 安装与使用：Windows 和 macOS 分开讲

先看一张决策流程图，快速定位自己该走哪条安装路径：

Windows：用 nvm-windows

先说一个容易懵的点：Windows 上的 nvm-windows 和 macOS/Linux 的 nvm 是两个独立项目，作者不同，命令也有差异，别混着看。

nvm-windows 的安装很省事，到它的 GitHub 仓库（coreybutler/nvm-windows）下载 nvm-setup.exe 双击安装（以官方文档为准）。安装路径建议保持默认。装完重开一个终端再执行命令，不然 PATH 还没刷新。

# 验证 nvm 是否装好nvm version# 预期输出：# 1.1.12 （版本号以实际安装为准）# 查看远程可安装的 Node 版本（列表很长，这里只列末尾几行）nvm list available# 预期输出（节选）：# 20.19.4 22.12.0 23.2.0 24.x.x# ...# 安装指定大版本的 Node（自动装到最新小版本）nvminstall20# 预期输出：# Downloading node.js version 20.19.4...# Installing...# Installation complete.# 切换使用nvm use20# 预期输出：# Now using node v20.19.4 (64-bit)# 查看本机已装的版本列表，* 号标记当前在用nvm list# 预期输出：# * 20.19.4 (Currently using 64-bit executable)# 22.12.0

版本切换是这个工具的核心价值。老项目要 Node 18，新项目要 Node 22，nvm use一行命令来回切。再用nvm alias default 20设默认版本，新开的终端窗口自动用这个版本，不用每次手动切。

再补几个高频操作。装指定小版本用nvm install 22.12.0；装最新 LTS 用nvm install --lts；看当前版本用nvm current。切换时报 ‘exit status 1’ 之类的错，一般是权限或杀毒软件拦截，以管理员身份重开终端再试。卸掉某个版本用nvm uninstall 18，连同它自己的全局包一起清掉，干净利落。

macOS / Linux：用 nvm

macOS 和 Linux 用的是 nvm-sh 这个项目，官方推荐 install 脚本安装：

# 安装 nvm（tag 版本号以官方文档为准，装前可去 nvm-sh/nvm 仓库核对最新版）curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh|bash# 脚本会自动把配置写进 ~/.bashrc 或 ~/.zshrc# 重载配置文件（以 zsh 为例）source~/.zshrc# 验证nvm--version# 预期输出：# 0.40.3 （版本号以实际安装为准）# 安装 Node 并切换nvminstall20nvm use20

一个提醒：macOS 上如果之前装过官方安装包的 Node，可能和 nvm 冲突。node -v出来的版本和nvm use不一致，多半就是旧安装残留。建议先按官方文档把旧 Node 卸载干净，再装 nvm，省得排查半天。

常见安装故障排查

装 nvm 的过程中，下面几个问题出现频率最高，逐个给出排查步骤和命令。

问题一：装完提示nvm不是内部或外部命令（Windows）

多半是 PATH 没生效或没写进环境变量。按顺序排查：

# 1. 先重开一个终端再试，PATH 刷新需要新会话nvm version# 2. 仍不行，检查 nvm 安装目录是否在 PATH 里echo%NVM_HOME%echo%NVM_SYMLINK%# 3. 手动把 nvm 目录加进 PATH（以默认安装路径为例）setx NVM_HOME"C:\Users\你的用户名\AppData\Roaming\nvm"setx NVM_SYMLINK"C:\Program Files\nodejs"

加完重开终端，再执行nvm version验证。注意setx只对之后新开的终端生效。

问题二：macOS / Linux 安装脚本执行失败

curl ... | bash报错，常见原因是网络不通或脚本下载不完整。先确认下载本身成功：

# 1. 单独下载脚本，看能否完整拿到curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh-oinstall.sh# 2. 检查文件是否完整（能看到完整的 shell 脚本内容，而不是报错页）head-5install.sh# 3. 网络不稳时，改用 git 方式安装gitclone https://github.com/nvm-sh/nvm.git ~/.nvmcd~/.nvmgitcheckout v0.40.3

git 方式装完，需要手动把下面几行加进~/.zshrc（或~/.bashrc）：

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

然后source ~/.zshrc重载，再nvm --version验证。

问题三：macOS 与旧 Node 冲突

node -v显示的版本和nvm use不一致，多半是之前用官方安装包装过 Node，残留没清干净。按顺序处理：

# 1. 先看当前 node 到底从哪来whichnode# 预期输出：/Users/你的用户名/.nvm/versions/node/v20.19.4/bin/node# 如果指向 /usr/local/bin/node，说明旧安装还在# 2. 确认 nvm 管理的 node 路径ls-l$(whichnode)# 3. 卸载旧 Node（官方安装包方式装的，用官方卸载脚本或手动删）# 手动删除常见残留目录：sudorm-rf/usr/local/bin/nodesudorm-rf/usr/local/bin/npmsudorm-rf/usr/local/lib/node_modules

删完重开终端，再nvm use 20 && node -v验证。注意sudo rm要谨慎，确认路径无误再执行。

问题四：nvm use切换时报exit status 1

Windows 上常见，一般是权限或杀毒软件拦截。以管理员身份重开终端再试：

# 管理员终端里执行nvm use20

macOS / Linux 上如果报权限错误，检查~/.nvm目录归属：

ls-ld~/.nvm# 属主不是当前用户时，改回来sudochown-R$(whoami)~/.nvm

版本验证：两条命令见分晓

不管哪种方式装完，验证就两条命令：

node-v# 预期输出：v20.19.4（应与 nvm use 的版本一致）npm-v# 预期输出：10.8.2（npm 随 Node 一起装，版本号以实际为准）# 想确认当前 node 是从哪个目录来的whichnode# macOS / Linux# 预期输出：/Users/你的用户名/.nvm/versions/node/v20.19.4/bin/node# Windows 用 where node，预期输出为 nvm 安装目录下的路径

node -v和nvm use对不上，十有八九是 PATH 里存在多个 Node。先which node（或where node）看路径，把 nvm 的路径挪到前面，或清理掉旧的 Node 安装。

补充说明：npm -v显示的版本是当前 Node 自带的。nvm 切换版本后 npm 跟着变，这是正常现象，不用单独装。真需要指定 npm 版本，就在某个 Node 版本里执行npm install -g npm@版本号。

npm 国内源配置：npmmirror

npm 默认的官方源 registry.npmjs.org 在国内下载速度不稳定，依赖一多就容易超时。国内常用的是 npmmirror（原淘宝源）。

# 查看当前源npmconfig get registry# 预期输出：# https://registry.npmjs.org/# 永久切换到 npmmirrornpmconfigsetregistry https://registry.npmmirror.com# 确认npmconfig get registry# 预期输出：# https://registry.npmmirror.com# 单次安装临时指定源（不想动全局配置时用）npminstalllodash--registry=https://registry.npmmirror.com

换源之后的提速是肉眼可见的。大型项目动辄几百上千个依赖，官方源可能卡十几分钟，镜像源几十秒完事。这条建议所有在国内开发的都配一下，一次性操作，长期受益。

.npmrc：配置的落盘位置

npm 的配置会写进.npmrc文件，分三层：项目级的.npmrc（项目根目录）、用户级的~/.npmrc、npm 内置全局配置。npm config set默认写用户级。想只对某个项目用特殊源，直接编辑项目根目录的 .npmrc：

# 项目根目录 .npmrc，只对这个项目生效 registry=https://registry.npmmirror.com

公司项目经常用这种方式锁定内部私有源，比全局改更可控。要注意.npmrc里可能含私有源认证 token，属于敏感文件，别提交进 git。排查 npm 配置异常时，先npm config list看当前生效的配置来自哪一层，再对症处理。

全局目录与权限：npm install -g 装到了哪

npm install -g装的全局包，到底去哪了？取决于你的安装方式。

# 查看全局安装目录npmprefix-g# 用 nvm 时的预期输出：/Users/你的用户名/.nvm/versions/node/v20.19.4

用 nvm 的好处在这里体现得很明显：每个 Node 版本有独立的全局目录，权限是用户级的，不会出现 Linux 下常见的 “EACCES: permission denied” 全局写入报错。副作用也要知道：切到别的版本，之前装过的全局包要重新装。这不是 bug，是隔离设计。

反过来，如果直接用 apt 之类的系统包管理器装 Node，全局目录通常在 /usr/lib/node_modules，普通用户没写权限，npm install -g就报权限错误。正经解决办法不是加 sudo，而是改用 nvm（以官方文档为准）。

用 nvm 管理时目录结构很清晰：所有版本都在~/.nvm/versions/node/下，一个版本一个目录。重装系统或换电脑前把~/.nvm目录整体备份，新机器恢复后 nvm 里的版本原样回来，这个技巧在换机时能省一上午。日常排查"node 命令到底是哪个"的问题，直接看这个目录就一目了然。

npx 与 .nvmrc：两个容易被忽略的细节

npm 跟着 Node 一起装，npx 是同一批送你的，很多人从没注意过它。npx 的作用一句话讲清：不全局装包，直接跑。npx create-react-app my-app会临时下载工具并执行，用完即走，不往全局目录里留垃圾。它顺带解决了版本打架的问题：项目 A 本地装了 vite 6，项目 B 是 vite 5，npx vite会优先用当前目录 node_modules 里的那份，不会调错版本。这条命令实际使用频率极高，值得现在就记住。

.nvmrc 是给项目钉 Node 版本的约定文件。在项目根目录写一行20（或精确到小版本20.19.4），进到项目里执行nvm use，nvm 会自动读这个文件切到对应版本。团队协作时这个小文件让所有人跑在同一个 Node 版本上，少很多"我本地能跑、你本地就报错"的扯皮。再配合 package.json 的 engines 字段声明最低版本要求，双保险。

几个落地细节：.nvmrc内容就一行，放 git 里跟着 package.json 一起提交；CI 环境（GitHub Actions、Jenkins）也认这个文件，部署时照它装 Node，开发和线上就对齐了。还有 npm scripts：package.json 的 scripts 字段里用npm run dev起开发服务是团队标配，新人不熟脚本名时执行npm run会列出全部可用脚本，比翻文档快。

常见问题速查

小结

Node 环境配置的核心就一句话：用 nvm 管版本，用 npmmirror 加速下载。官网安装包只能救急，包管理器版本太旧，nvm 才是能陪你走完整条开发路的那个工具。这套配好，项目切版本、依赖下载这些事基本再也不用折腾。

多说一句验证的姿势：配完环境，写个十行的小脚本实际跑一遍，比对着教程点头有用得多。Node 环境折腾完，下一篇讲 MySQL，密码策略那个坑我至今记忆犹新，提前关注。

下一篇写 MySQL 安装配置，从下载到连上数据库的完整流程，包括那个让人抓狂的密码策略问题，可以提前关注。