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-windows | 多版本共存，随时切换 | 要先装 nvm 本身，有学习成本 | 主力开发、多项目并行 |
| 系统包管理器（brew/apt） | 命令安装，跟系统生态统一 | 版本通常滞后，全局权限问题多 | 临时用一下、装个环境跑脚本 |
结论很直白：正经做开发，选 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.3git 方式装完，需要手动把下面几行加进~/.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 use20macOS / 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会列出全部可用脚本，比翻文档快。
常见问题速查
| 问题 | 原因 | 解决办法 |
|---|---|---|
nvm不是内部或外部命令 | 装完没重开终端，或 PATH 没生效 | 重开终端；仍不行检查系统环境变量有没有 nvm 路径 |
nvm use提示版本不存在 | 该版本没安装 | 先nvm install对应版本，再 use |
node -v和 nvm 对不上 | PATH 里有多个 Node | which node（Windows 用 where）查路径，调整顺序 |
| npm install 超时 / 极慢 | 默认官方源 | 切 npmmirror，见上文 |
| EACCES 权限报错 | 全局目录无写权限 | 改用 nvm 管理，别用 sudo |
| 切版本后全局包"消失" | nvm 按版本隔离全局目录 | 切回原版本使用，或在新版本重装npm i -g |
| 两个 nvm 命令对不上 | nvm-windows 和 nvm 混用 | Windows 用nvm version，macOS/Linux 用nvm --version |
| nvm install 下载慢 / 失败 | 官方 CDN 国内访问不稳 | nvm-windows 在安装目录 settings.txt 配置 node_mirror / npm_mirror 指向国内镜像（以官方文档为准） |
小结
Node 环境配置的核心就一句话：用 nvm 管版本，用 npmmirror 加速下载。官网安装包只能救急，包管理器版本太旧，nvm 才是能陪你走完整条开发路的那个工具。这套配好，项目切版本、依赖下载这些事基本再也不用折腾。
多说一句验证的姿势：配完环境，写个十行的小脚本实际跑一遍，比对着教程点头有用得多。Node 环境折腾完，下一篇讲 MySQL，密码策略那个坑我至今记忆犹新，提前关注。
下一篇写 MySQL 安装配置，从下载到连上数据库的完整流程，包括那个让人抓狂的密码策略问题，可以提前关注。