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 分开讲先看一张决策流程图快速定位自己该走哪条安装路径WindowsmacOS / Linux命令找不到验证通过脚本执行失败验证通过不一致一致开始你的操作系统是Windows 还是 macOS / Linux用 nvm-windows用 nvmnvm-sh下载 nvm-setup.exe 双击安装重开终端执行 nvm version 验证检查 PATH / 环境变量nvm install 20 nvm use 20curl 脚本安装 nvmsource ~/.zshrc 后执行 nvm --version 验证改用 git clone 方式安装node -v 与 nvm use 是否一致排查旧 Node 残留 / PATH 冲突安装完成开始开发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 22nvm use一行命令来回切。再用nvm alias default 20设默认版本新开的终端窗口自动用这个版本不用每次手动切。再补几个高频操作。装指定小版本用nvm install 22.12.0装最新 LTS 用nvm install --lts看当前版本用nvm current。切换时报 ‘exit status 1’ 之类的错一般是权限或杀毒软件拦截以管理员身份重开终端再试。卸掉某个版本用nvm uninstall 18连同它自己的全局包一起清掉干净利落。macOS / Linux用 nvmmacOS 和 Linux 用的是 nvm-sh 这个项目官方推荐 install 脚本安装# 安装 nvmtag 版本号以官方文档为准装前可去 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_HOMEC:\Users\你的用户名\AppData\Roaming\nvmsetx NVM_SYMLINKC:\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或~/.bashrcexportNVM_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 1Windows 上常见一般是权限或杀毒软件拦截。以管理员身份重开终端再试# 管理员终端里执行nvm use20macOS / Linux 上如果报权限错误检查~/.nvm目录归属ls-ld~/.nvm# 属主不是当前用户时改回来sudochown-R$(whoami)~/.nvm版本验证两条命令见分晓不管哪种方式装完验证就两条命令node-v# 预期输出v20.19.4应与 nvm use 的版本一致npm-v# 预期输出10.8.2npm 随 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 国内源配置npmmirrornpm 默认的官方源 registry.npmjs.org 在国内下载速度不稳定依赖一多就容易超时。国内常用的是 npmmirror原淘宝源。# 查看当前源npmconfig get registry# 预期输出# https://registry.npmjs.org/# 永久切换到 npmmirrornpmconfigsetregistry https://registry.npmmirror.com# 确认npmconfig get registry# 预期输出# https://registry.npmmirror.com# 单次安装临时指定源不想动全局配置时用npminstalllodash--registryhttps://registry.npmmirror.com换源之后的提速是肉眼可见的。大型项目动辄几百上千个依赖官方源可能卡十几分钟镜像源几十秒完事。这条建议所有在国内开发的都配一下一次性操作长期受益。.npmrc配置的落盘位置npm 的配置会写进.npmrc文件分三层项目级的.npmrc项目根目录、用户级的~/.npmrc、npm 内置全局配置。npm config set默认写用户级。想只对某个项目用特殊源直接编辑项目根目录的 .npmrc# 项目根目录 .npmrc只对这个项目生效 registryhttps://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 5npx vite会优先用当前目录 node_modules 里的那份不会调错版本。这条命令实际使用频率极高值得现在就记住。.nvmrc 是给项目钉 Node 版本的约定文件。在项目根目录写一行20或精确到小版本20.19.4进到项目里执行nvm usenvm 会自动读这个文件切到对应版本。团队协作时这个小文件让所有人跑在同一个 Node 版本上少很多我本地能跑、你本地就报错的扯皮。再配合 package.json 的 engines 字段声明最低版本要求双保险。几个落地细节.nvmrc内容就一行放 git 里跟着 package.json 一起提交CI 环境GitHub Actions、Jenkins也认这个文件部署时照它装 Node开发和线上就对齐了。还有 npm scriptspackage.json 的 scripts 字段里用npm run dev起开发服务是团队标配新人不熟脚本名时执行npm run会列出全部可用脚本比翻文档快。常见问题速查问题原因解决办法nvm不是内部或外部命令装完没重开终端或 PATH 没生效重开终端仍不行检查系统环境变量有没有 nvm 路径nvm use提示版本不存在该版本没安装先nvm install对应版本再 usenode -v和 nvm 对不上PATH 里有多个 Nodewhich nodeWindows 用 where查路径调整顺序npm install 超时 / 极慢默认官方源切 npmmirror见上文EACCES 权限报错全局目录无写权限改用 nvm 管理别用 sudo切版本后全局包消失nvm 按版本隔离全局目录切回原版本使用或在新版本重装npm i -g两个 nvm 命令对不上nvm-windows 和 nvm 混用Windows 用nvm versionmacOS/Linux 用nvm --versionnvm install 下载慢 / 失败官方 CDN 国内访问不稳nvm-windows 在安装目录 settings.txt 配置 node_mirror / npm_mirror 指向国内镜像以官方文档为准小结Node 环境配置的核心就一句话用 nvm 管版本用 npmmirror 加速下载。官网安装包只能救急包管理器版本太旧nvm 才是能陪你走完整条开发路的那个工具。这套配好项目切版本、依赖下载这些事基本再也不用折腾。多说一句验证的姿势配完环境写个十行的小脚本实际跑一遍比对着教程点头有用得多。Node 环境折腾完下一篇讲 MySQL密码策略那个坑我至今记忆犹新提前关注。下一篇写 MySQL 安装配置从下载到连上数据库的完整流程包括那个让人抓狂的密码策略问题可以提前关注。