1. 先搞明白 v16 是谁为什么这个老版本还有人装1.1 先澄清一个搜索词撞车博图 v16 不是 Node.js v16“Node.js v16 版本安装”这个搜索词混着一个很容易让人跑偏的流量大户博图 v16也就是 TIA Portal V16。做工业自动化、PLC 编程的朋友搜出来的是西门子的组态软件Windows 上十几个 GB 的工程环境做前端和后端的人搜出来的是 JavaScript 运行时 Node.js 的 16.x 系列。两个除了“16”这个数字相同技术栈完全没关系。别在别人的工具教程里找了半天找不到许可证回来发现根本不是一回事。本文只讲 Node.js 16。1.2 v16 的生命周期它已 EOL但没到不能用的地步Node.js 的版本发布策略很固定偶数版本走 LTS长期支持奇数版本当试验田。v16 在 2021 年 4 月 20 日发布同年 10 月 26 日进入 LTS 阶段代号叫 Gallium。按照官方时间表它的主动维护期到 2022 年 10 月 18 日之后转入安全维护期最终在 2023 年 9 月 11 日彻底 EOL。说人话就是Node.js 16 现在已经停止一切更新包括安全补丁。如果你是新项目、新团队、没有历史包袱我不建议直接上 v16但如果是为了维护老项目、跑旧脚手架、复现一些文档还停留在 v16 时代的开源项目那装 v16 是再正常不过的需求。老话说“存在即合理”这句话放在 Node 版本上特别成立——大把公司的线上服务还钉死在 v14 和 v16 上不是不想升是不敢动。1.3 什么项目建议装 v16什么项目千万别碰建议装 v16 的情况我归纳下来基本就是三种。第一种是老项目维护。支付系统、管理后台、中台服务只要 npm 依赖树里有 ES Module 转换、webpack 4、或者某些只在 Node 16 下测试过的原生模块升到 v18 后行为可能完全变掉。为了一个稳定运行的线上服务去冒升级风险明显不划算。第二种是原生模块锁死了 ABI。Node.js 每个大版本都有一个模块版本号v16 对应的是 93。node-sass、旧版 bcrypt、部分 native addon 对 ABI 绑定极其敏感主版本一换就必须重新编译编译环境和依赖链稍微不对就全挂。这类项目里 v16 不是你选的是模块逼着你用的。第三种是教学、实验、复现开源项目。很多课程和博客文章的示例代码是 2021-2022 年写的当时的 Node 默认版本就是 v16照文档操作最容易跑通。这个场景下装 v16 能避免“文档里明明这么写我执行却报错”的版本错位。千万别碰 v16 的是你刚启动一个全新项目且没有任何兼容性要求。直接装 v20 或 v22 LTS 版本更稳妥跑得又新又稳。v16 的最后一个版本是 16.20.2补丁已经打全了真要用就装这个别去装 16.0.0 那种早期版本给自己找罪受。2. Windows 上装 v16官方 MSI 和 nvm-windows 两条路线2.1 官方 MSI 安装包的几步关键选项Windows 上装 v16最直接的方式是去官网的 dist 目录下载 16.20.2 的 Windows Installer.msi双击一路 Next。但我遇到过不少在这条简单路上翻车的关键是这几个选项安装路径默认是 C:\Program Files\nodejs。想改路径可以但别选带空格或者中文的目录某些老工具执行子进程时对路径空格非常敏感报错的时候你不会想到是这个原因。“Add to PATH”这个复选框默认勾选千万别手贱取消。很多新手后来在 cmd 和 PowerShell 里敲 node 报“不是内部或外部命令”就是因为安装时取消了这个选项或者 PATH 被后续安装的软件覆盖了。MSI 安装有一个隐藏的好处它注册了系统卸载信息。以后不想要 v16 了可以从“设置 → 应用”里正规卸载比手动删目录干净得多。装完之后先重启一下终端再执行node -v。如果还是找不到命令就去“系统属性 → 环境变量”里检查 Path看有没有 C:\Program Files\nodejs 这一项。没有就手动加上注意 Windows 10 以上环境变量之间以分号分隔别把格式写错。2.2 nvm-windows多版本管理的正确姿势实际工作里我更多时候用的是 nvm-windows而不是官方 MSI。原因很简单一个开发机上经常同时有多个项目A 项目锁 v16B 项目锁 v18只装一个版本根本不够用。这里必须强调nvm-windows 和 Linux/macOS 上的 nvm 虽然是同名但作者和实现都不相同。Windows 版由 coreybutler 维护在 GitHub 上搜索 nvm-windows 就能找到。安装 nvm-windows 之前有个重要动作先把已经安装的 Node.js 卸载干净。如果你已经通过 MSI 装了 v16再直接装 nvm-windows两个环境变量会互相打架最后你切换版本时会发现根本没有效果。顺手把残留的 C:\Program Files\nodejs 目录一并删掉再装 nvm能省掉不少麻烦事。安装完成后在管理员身份启动的 CMD 或 PowerShell 里执行nvm version nvm install 16.20.2 nvm use 16.20.2注意nvm install执行后不会自动切换必须手动nvm use。之后node -v输出 v16.20.2 才算成功。如果提示找不到 node先重启终端再检查 NVM_HOME、NVM_SYMLINK 环境变量是否配置正确以及 Path 里有没有包含这两项。这是 nvm-windows 最常见的坑我踩过一次之后就记死了。常用命令我也列在这里命令作用nvm list查看已安装版本列表nvm install 16.20.2安装指定版本nvm use 16.20.2切换到指定版本nvm uninstall 16.20.2卸载指定版本nvm on / nvm off开启 / 关闭 nvm 管理2.3 npm 镜像源该不该改怎么改才不误伤Node 装完绕不开 npm 下载速度。默认源是 https://registry.npmjs.org/在国内环境经常慢得离谱。临时加速可以这样npm install --registryhttps://registry.npmmirror.com想永久生效就写入全局配置npm config set registry https://registry.npmmirror.com但我个人的经验是全局改镜像可以但要慎用。有些公司内部 npm 包只存在于私有源你把 registry 全局改成公共镜像后npm install要么报 404要么装到了同名但完全不同的包。更稳妥的做法是只给特定项目配置.npmrc在项目根目录新建文件写入registryhttps://registry.npmmirror.com这样对当前项目生效其他项目仍然走默认源或私有源互不干扰。顺带提醒一句npmmirror 的地址已经换成 registry.npmmirror.com网上很多老教程写的 registry.npm.taobao.org 早已淘汰照着老文章操作大概率失败。3. macOS 与 Linux 的 v16 安装三套方案按场景选3.1 macOS 的老芯片坑与 nvm 安装流程Apple 芯片的 Mac 装老版本 Node有一个历史坑Node.js 从 16.13.0 开始才正式提供 macOS arm64 的二进制包。如果你装的是 16.13.0 以前的版本在 M1/M2 上会被 Rosetta 转译运行平时用感觉不大一旦涉及原生模块编译极容易出现架构不匹配的问题。所以 Mac 用户装 v16最低也得是 16.13.0直接上 16.20.2 更省心。macOS 上很多人会想到 Homebrewbrew install node16但需要注意brew 的 node16 是 keg-only装完还需要手动执行brew link --force node16。而且 v16 进入 EOL 后Homebrew 的 formula 会被标记为过时下次brew upgrade甚至可能直接提示移除。如果你准备长期维护 v16 环境还是直接上 nvm 最稳curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后按提示source ~/.zshrc或者重新打开终端然后nvm install 16.20.2 nvm use 16.20.23.2 Ubuntu apt 源、NodeSource 与二进制包的选择Linux 环境下装 v16常见有三条路分别对应不同场景。第一是直接用系统 apt 源。问题在于版本太旧Ubuntu 20.04 自带 nodejs 是 v10.xUbuntu 22.04 是 v12.x离 v16 差了好几个大版本。系统自带版本只适合跑 apt 源里的老应用想用来开发基本没戏。第二是 NodeSource 提供的 apt 源可以指定安装 v16.x。执行 curl 脚本导入 GPG key然后apt install nodejs就装了对应大版本的 Node。这种方式适合服务器场景因为它自动注册了 systemd 之外的服务路径升级也能走 apt 体系。第三是用 nvm。开发机上我强烈推荐这个方案它装在用户目录不污染系统也不需要 sudo 权限多版本切换非常方便。如果目标是在生产服务器上部署且不喜欢多版本管理我更倾向直接下载官方二进制包wget https://nodejs.org/dist/v16.20.2/node-v16.20.2-linux-x64.tar.xz tar -xJf node-v16.20.2-linux-x64.tar.xz mv node-v16.20.2-linux-x64 /opt/node-v16 ln -s /opt/node-v16/bin/node /usr/local/bin/node ln -s /opt/node-v16/bin/npm /usr/local/bin/npm这种办法的好处是路径可控、完全不依赖第三方源升级时改一下软链接就行。缺点是每次升级手动操作不会有版本切换能力适合“一台服务器只跑一个 Node 版本”的场景。3.3 EACCES 权限问题为什么我劝你别用 sudoLinux/macOS 上新手碰到最多的报错之一是这个npm ERR! Error: EACCES: permission denied, mkdir /usr/local/lib/node_modules表面原因是 npm 全局安装的默认路径归 root 所有普通用户没权限写。网上一堆教程让你加 sudo 解决我是强烈反对的。你想想每次全局安装都要 sudo时间长了 /usr/local 目录的属主全被改乱后续任何非 root 工具读这个目录都会出问题。最优雅的方案是用 nvm 把 Node 装到用户目录这样整个 node_modules 树都是你自己的完全不碰系统目录。如果你已经用安装包装在了系统路径又不想换方案可以修正目录属主sudo chown -R $(whoami) /usr/local/lib/node_modules sudo chown -R $(whoami) /usr/local/bin/node这确实是有效解决方案但只能算治标。我自己的体会是开发环境越早迁移到用户级目录后面踩的坑越少。特别是同时用多个 Node 版本的时候系统级目录方案基本无解。4. 装完别急着写代码一张自检清单排查环境问题4.1 六个命令确认安装状态装完 v16很多人敲一下node -v看到 v16.20.2 就认为万事大吉其实远远不够。我每次配置完新环境都会按顺序跑一组命令node -v npm -v which node which npm npm config get registry npm ls -g --depth0which node和which npm是为了确认你到底在跑哪个路径下的 Node。装了 nvm 之后偶尔会遇到 shell 加载顺序问题PATH 里残留着系统自带的 node这时候node -v显示的版本和刚装的 v16 完全对不上。npm config get registry是确认源有没有被改掉避免装了慢悠悠的默认源还不知道。npm ls -g --depth0是看全局包清单后面切版本时要用。4.2 PowerShell 执行策略与 Windows 全局命令异常Windows 上用 MSI 安装的 Nodenpm 全局包目录默认在 C:\Users\你的用户名\AppData\Roaming\npm。装完某个全局工具后在 PowerShell 里执行提示“无法加载因为在此系统上禁止运行脚本”这个锅是 PowerShell 策略不是 Node 的。以管理员身份执行一次Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser之后全局命令就不会再被拦。另外Windows 下 npm 全局包安装成功后如果仍然提示“npm 不是内部或外部命令”多半是 PATH 里只加了 nodejs 目录没有加 npm 全局目录。去环境变量编辑器把 %APPDATA%\npm 追加进 Path重开窗口就好了。这是 Windows 下特别常见但大多数人反应不过来的问题。4.3 PATH 优先级和终端配置文件对 Node 的影响PATH 是有顺序的谁排前面谁先被命中。如果系统自带的 node 路径排在 nvm 的符号链接前面那你执行node的时候真正命中的可能是另一个版本。排查方式是先跑node -v再跑which node对不上就检查echo $PATH把 nvm 相关路径挪到前面去。容易被忽略的是 shell 配置文件的差异。macOS 的 zsh 加载 ~/.zshrcbash 加载 ~/.bashrcLinux 的 bash 又可能是 ~/.bash_profile。nvm 安装脚本会在你当前的 shell 配置文件里写一行export NVM_DIR...如果你主力终端是 zsh但教程里让你 source 的是 ~/.bashrc那配置永远不生效。装完 nvm 后第一时间确认它被写进了哪个文件并手动补全其他 shell 的配置。5. 多版本共存时的日常操练切换、隔离、清理5.1 用 .nvmrc 锁定每个项目的 Node 版本在一台电脑上同时维护多个项目时我最怕的就是“跑错版本还不自知”。解决办法很朴素——项目根目录建一个.nvmrc文件里面就写一行16.20.2然后每次进入项目目录执行nvm use它会自动读取文件并切到指定版本。这样做以后换电脑也只需要把这个文件带过去配合nvm install就能秒级恢复环境。为了双保险建议在 package.json 里也声明 engines 字段engines: { node: 16 17 }这样即使有人忘了切版本npm install时也会因为 engines 不匹配给出警告。虽然它不阻止安装但至少给了提示省得你在奇怪的运行时报错里翻半天。5.2 全局模块不跨版本一个反直觉的隔离设计用 nvm 切换版本后之前全局安装的包在新版本里会消失。比如你在 v16 里全局装了nodemon切到 v18 再执行nodemon终端会提示命令不存在。这个设计刚接触时很反直觉我第一次遇到还以为是 nvm 坏了后来才明白nvm 的每个版本都有独立的全局目录npm 会根据当前版本绑定全局安装位置。正确做法是整理一份全局工具清单每次切换大版本后重新安装一遍。想偷懒的话可以在.nvmrc旁边放一个global.sh列出所有全局包名切换后一键重装。不要试图通过--prefix强制共享某些带原生二进制的包在跨版本场景下会报平台不匹配不值得省这个时间。5.3 从 v16 升到 v18 后为什么必须删 lock 文件重装旧项目的 node_modules 里原生模块的二进制文件和 Node 的 ABI 是绑定的。直接把 v16 时期的 node_modules 拿给 v18 用轻则报Module version mismatch重则直接启动失败。正确迁移姿势是rm -rf node_modules package-lock.json npm install别舍不得删。package-lock.json 重新生成后依赖版本范围保持不变只是按当前 Node 版本重新解析一次。删掉半个小时的缓存换来一个干净的环境这笔账怎么算都划算。6. 我遇过的 v16 安装报错和排查思路6.1 node-gyp / node-sass 编译失败的真实原因老项目安装依赖时经常卡在 node-sass、sharp、bcrypt 这类需要本地编译的包上。v16 环境报 python 相关错误的概率特别高因为 node-gyp 编译步骤需要 Python 参与。Windows 上最省事的办法是装 Visual Studio Build Tools安装时勾选“C 桌面开发”工作负载然后执行npm config set msvs_version 2022如果你还在 v16 的环境里硬扛 node-sass建议直接看项目能不能换 dart-sass 或者升级依赖。node-sass 的版本和 Node 版本绑定极其死板它早已停止维护就算硬装成功后续安全风险也得你自己兜着。6.2 “is not yet released”报错的定位方法有个搜索词是“node.js v24.21.0 is not yet released or is not available”这类报错通常来自 nvm 或其他安装脚本。当你指定了一个版本列表中不存在的版本号比如写了 24.21.0但官方只发布到 24.20.x工具去查版本列表发现查无此版就会抛出这个提示。定位方法很简单先用nvm ls-remote或直接去官网 dist 目录确认版本号真实存在再重新安装。这个报错和 v16 本身没关系但它常出现在处理旧项目时因为很多人喜欢凭记忆抄版本号抄错了就出类似问题。6.3 npm 缓存、代理和 SSL 证书异常的现场处理npm 偶尔会报UNABLE_TO_GET_ISSUER_CERT_LOCALLY这通常和公司内网代理、自签名证书有关。临时排查时可以设置npm config set strict-ssl false但这只是临时手段不能日常开着。内网环境如果必须走代理就配置npm config set proxy http://127.0.0.1:7890 npm config set https-proxy http://127.0.0.1:7890用完记得删除npm config delete proxy npm config delete https-proxy至于npm cache clean --force这种操作我的经验是能不做就不做。npm 缓存损坏的概率其实很低依赖装不上首先应怀疑 node_modules 残留、版本冲突和网络问题顺序应该是删 node_modules 和 lock 文件重装再检查代理最后才考虑清缓存。一上来就清缓存解决不了问题反而把本地缓存全打掉下次安装全部走网络慢上加慢。我自己在维护一个混合版本开发环境时最终的组合是Windows 上用 nvm-windows 管 v16 和 v18macOS 上用官方 nvm 管同样的两套版本任何项目进来先看.nvmrc再动手。v16 这台“老车”虽然早就过了官方质保期但只要项目需要它依然稳定可靠关键是一开始就要把环境装对、把坑避开。
1. 先搞明白 v16 是谁为什么这个老版本还有人装1.1 先澄清一个搜索词撞车博图 v16 不是 Node.js v16“Node.js v16 版本安装”这个搜索词混着一个很容易让人跑偏的流量大户博图 v16也就是 TIA Portal V16。做工业自动化、PLC 编程的朋友搜出来的是西门子的组态软件Windows 上十几个 GB 的工程环境做前端和后端的人搜出来的是 JavaScript 运行时 Node.js 的 16.x 系列。两个除了“16”这个数字相同技术栈完全没关系。别在别人的工具教程里找了半天找不到许可证回来发现根本不是一回事。本文只讲 Node.js 16。1.2 v16 的生命周期它已 EOL但没到不能用的地步Node.js 的版本发布策略很固定偶数版本走 LTS长期支持奇数版本当试验田。v16 在 2021 年 4 月 20 日发布同年 10 月 26 日进入 LTS 阶段代号叫 Gallium。按照官方时间表它的主动维护期到 2022 年 10 月 18 日之后转入安全维护期最终在 2023 年 9 月 11 日彻底 EOL。说人话就是Node.js 16 现在已经停止一切更新包括安全补丁。如果你是新项目、新团队、没有历史包袱我不建议直接上 v16但如果是为了维护老项目、跑旧脚手架、复现一些文档还停留在 v16 时代的开源项目那装 v16 是再正常不过的需求。老话说“存在即合理”这句话放在 Node 版本上特别成立——大把公司的线上服务还钉死在 v14 和 v16 上不是不想升是不敢动。1.3 什么项目建议装 v16什么项目千万别碰建议装 v16 的情况我归纳下来基本就是三种。第一种是老项目维护。支付系统、管理后台、中台服务只要 npm 依赖树里有 ES Module 转换、webpack 4、或者某些只在 Node 16 下测试过的原生模块升到 v18 后行为可能完全变掉。为了一个稳定运行的线上服务去冒升级风险明显不划算。第二种是原生模块锁死了 ABI。Node.js 每个大版本都有一个模块版本号v16 对应的是 93。node-sass、旧版 bcrypt、部分 native addon 对 ABI 绑定极其敏感主版本一换就必须重新编译编译环境和依赖链稍微不对就全挂。这类项目里 v16 不是你选的是模块逼着你用的。第三种是教学、实验、复现开源项目。很多课程和博客文章的示例代码是 2021-2022 年写的当时的 Node 默认版本就是 v16照文档操作最容易跑通。这个场景下装 v16 能避免“文档里明明这么写我执行却报错”的版本错位。千万别碰 v16 的是你刚启动一个全新项目且没有任何兼容性要求。直接装 v20 或 v22 LTS 版本更稳妥跑得又新又稳。v16 的最后一个版本是 16.20.2补丁已经打全了真要用就装这个别去装 16.0.0 那种早期版本给自己找罪受。2. Windows 上装 v16官方 MSI 和 nvm-windows 两条路线2.1 官方 MSI 安装包的几步关键选项Windows 上装 v16最直接的方式是去官网的 dist 目录下载 16.20.2 的 Windows Installer.msi双击一路 Next。但我遇到过不少在这条简单路上翻车的关键是这几个选项安装路径默认是 C:\Program Files\nodejs。想改路径可以但别选带空格或者中文的目录某些老工具执行子进程时对路径空格非常敏感报错的时候你不会想到是这个原因。“Add to PATH”这个复选框默认勾选千万别手贱取消。很多新手后来在 cmd 和 PowerShell 里敲 node 报“不是内部或外部命令”就是因为安装时取消了这个选项或者 PATH 被后续安装的软件覆盖了。MSI 安装有一个隐藏的好处它注册了系统卸载信息。以后不想要 v16 了可以从“设置 → 应用”里正规卸载比手动删目录干净得多。装完之后先重启一下终端再执行node -v。如果还是找不到命令就去“系统属性 → 环境变量”里检查 Path看有没有 C:\Program Files\nodejs 这一项。没有就手动加上注意 Windows 10 以上环境变量之间以分号分隔别把格式写错。2.2 nvm-windows多版本管理的正确姿势实际工作里我更多时候用的是 nvm-windows而不是官方 MSI。原因很简单一个开发机上经常同时有多个项目A 项目锁 v16B 项目锁 v18只装一个版本根本不够用。这里必须强调nvm-windows 和 Linux/macOS 上的 nvm 虽然是同名但作者和实现都不相同。Windows 版由 coreybutler 维护在 GitHub 上搜索 nvm-windows 就能找到。安装 nvm-windows 之前有个重要动作先把已经安装的 Node.js 卸载干净。如果你已经通过 MSI 装了 v16再直接装 nvm-windows两个环境变量会互相打架最后你切换版本时会发现根本没有效果。顺手把残留的 C:\Program Files\nodejs 目录一并删掉再装 nvm能省掉不少麻烦事。安装完成后在管理员身份启动的 CMD 或 PowerShell 里执行nvm version nvm install 16.20.2 nvm use 16.20.2注意nvm install执行后不会自动切换必须手动nvm use。之后node -v输出 v16.20.2 才算成功。如果提示找不到 node先重启终端再检查 NVM_HOME、NVM_SYMLINK 环境变量是否配置正确以及 Path 里有没有包含这两项。这是 nvm-windows 最常见的坑我踩过一次之后就记死了。常用命令我也列在这里命令作用nvm list查看已安装版本列表nvm install 16.20.2安装指定版本nvm use 16.20.2切换到指定版本nvm uninstall 16.20.2卸载指定版本nvm on / nvm off开启 / 关闭 nvm 管理2.3 npm 镜像源该不该改怎么改才不误伤Node 装完绕不开 npm 下载速度。默认源是 https://registry.npmjs.org/在国内环境经常慢得离谱。临时加速可以这样npm install --registryhttps://registry.npmmirror.com想永久生效就写入全局配置npm config set registry https://registry.npmmirror.com但我个人的经验是全局改镜像可以但要慎用。有些公司内部 npm 包只存在于私有源你把 registry 全局改成公共镜像后npm install要么报 404要么装到了同名但完全不同的包。更稳妥的做法是只给特定项目配置.npmrc在项目根目录新建文件写入registryhttps://registry.npmmirror.com这样对当前项目生效其他项目仍然走默认源或私有源互不干扰。顺带提醒一句npmmirror 的地址已经换成 registry.npmmirror.com网上很多老教程写的 registry.npm.taobao.org 早已淘汰照着老文章操作大概率失败。3. macOS 与 Linux 的 v16 安装三套方案按场景选3.1 macOS 的老芯片坑与 nvm 安装流程Apple 芯片的 Mac 装老版本 Node有一个历史坑Node.js 从 16.13.0 开始才正式提供 macOS arm64 的二进制包。如果你装的是 16.13.0 以前的版本在 M1/M2 上会被 Rosetta 转译运行平时用感觉不大一旦涉及原生模块编译极容易出现架构不匹配的问题。所以 Mac 用户装 v16最低也得是 16.13.0直接上 16.20.2 更省心。macOS 上很多人会想到 Homebrewbrew install node16但需要注意brew 的 node16 是 keg-only装完还需要手动执行brew link --force node16。而且 v16 进入 EOL 后Homebrew 的 formula 会被标记为过时下次brew upgrade甚至可能直接提示移除。如果你准备长期维护 v16 环境还是直接上 nvm 最稳curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后按提示source ~/.zshrc或者重新打开终端然后nvm install 16.20.2 nvm use 16.20.23.2 Ubuntu apt 源、NodeSource 与二进制包的选择Linux 环境下装 v16常见有三条路分别对应不同场景。第一是直接用系统 apt 源。问题在于版本太旧Ubuntu 20.04 自带 nodejs 是 v10.xUbuntu 22.04 是 v12.x离 v16 差了好几个大版本。系统自带版本只适合跑 apt 源里的老应用想用来开发基本没戏。第二是 NodeSource 提供的 apt 源可以指定安装 v16.x。执行 curl 脚本导入 GPG key然后apt install nodejs就装了对应大版本的 Node。这种方式适合服务器场景因为它自动注册了 systemd 之外的服务路径升级也能走 apt 体系。第三是用 nvm。开发机上我强烈推荐这个方案它装在用户目录不污染系统也不需要 sudo 权限多版本切换非常方便。如果目标是在生产服务器上部署且不喜欢多版本管理我更倾向直接下载官方二进制包wget https://nodejs.org/dist/v16.20.2/node-v16.20.2-linux-x64.tar.xz tar -xJf node-v16.20.2-linux-x64.tar.xz mv node-v16.20.2-linux-x64 /opt/node-v16 ln -s /opt/node-v16/bin/node /usr/local/bin/node ln -s /opt/node-v16/bin/npm /usr/local/bin/npm这种办法的好处是路径可控、完全不依赖第三方源升级时改一下软链接就行。缺点是每次升级手动操作不会有版本切换能力适合“一台服务器只跑一个 Node 版本”的场景。3.3 EACCES 权限问题为什么我劝你别用 sudoLinux/macOS 上新手碰到最多的报错之一是这个npm ERR! Error: EACCES: permission denied, mkdir /usr/local/lib/node_modules表面原因是 npm 全局安装的默认路径归 root 所有普通用户没权限写。网上一堆教程让你加 sudo 解决我是强烈反对的。你想想每次全局安装都要 sudo时间长了 /usr/local 目录的属主全被改乱后续任何非 root 工具读这个目录都会出问题。最优雅的方案是用 nvm 把 Node 装到用户目录这样整个 node_modules 树都是你自己的完全不碰系统目录。如果你已经用安装包装在了系统路径又不想换方案可以修正目录属主sudo chown -R $(whoami) /usr/local/lib/node_modules sudo chown -R $(whoami) /usr/local/bin/node这确实是有效解决方案但只能算治标。我自己的体会是开发环境越早迁移到用户级目录后面踩的坑越少。特别是同时用多个 Node 版本的时候系统级目录方案基本无解。4. 装完别急着写代码一张自检清单排查环境问题4.1 六个命令确认安装状态装完 v16很多人敲一下node -v看到 v16.20.2 就认为万事大吉其实远远不够。我每次配置完新环境都会按顺序跑一组命令node -v npm -v which node which npm npm config get registry npm ls -g --depth0which node和which npm是为了确认你到底在跑哪个路径下的 Node。装了 nvm 之后偶尔会遇到 shell 加载顺序问题PATH 里残留着系统自带的 node这时候node -v显示的版本和刚装的 v16 完全对不上。npm config get registry是确认源有没有被改掉避免装了慢悠悠的默认源还不知道。npm ls -g --depth0是看全局包清单后面切版本时要用。4.2 PowerShell 执行策略与 Windows 全局命令异常Windows 上用 MSI 安装的 Nodenpm 全局包目录默认在 C:\Users\你的用户名\AppData\Roaming\npm。装完某个全局工具后在 PowerShell 里执行提示“无法加载因为在此系统上禁止运行脚本”这个锅是 PowerShell 策略不是 Node 的。以管理员身份执行一次Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser之后全局命令就不会再被拦。另外Windows 下 npm 全局包安装成功后如果仍然提示“npm 不是内部或外部命令”多半是 PATH 里只加了 nodejs 目录没有加 npm 全局目录。去环境变量编辑器把 %APPDATA%\npm 追加进 Path重开窗口就好了。这是 Windows 下特别常见但大多数人反应不过来的问题。4.3 PATH 优先级和终端配置文件对 Node 的影响PATH 是有顺序的谁排前面谁先被命中。如果系统自带的 node 路径排在 nvm 的符号链接前面那你执行node的时候真正命中的可能是另一个版本。排查方式是先跑node -v再跑which node对不上就检查echo $PATH把 nvm 相关路径挪到前面去。容易被忽略的是 shell 配置文件的差异。macOS 的 zsh 加载 ~/.zshrcbash 加载 ~/.bashrcLinux 的 bash 又可能是 ~/.bash_profile。nvm 安装脚本会在你当前的 shell 配置文件里写一行export NVM_DIR...如果你主力终端是 zsh但教程里让你 source 的是 ~/.bashrc那配置永远不生效。装完 nvm 后第一时间确认它被写进了哪个文件并手动补全其他 shell 的配置。5. 多版本共存时的日常操练切换、隔离、清理5.1 用 .nvmrc 锁定每个项目的 Node 版本在一台电脑上同时维护多个项目时我最怕的就是“跑错版本还不自知”。解决办法很朴素——项目根目录建一个.nvmrc文件里面就写一行16.20.2然后每次进入项目目录执行nvm use它会自动读取文件并切到指定版本。这样做以后换电脑也只需要把这个文件带过去配合nvm install就能秒级恢复环境。为了双保险建议在 package.json 里也声明 engines 字段engines: { node: 16 17 }这样即使有人忘了切版本npm install时也会因为 engines 不匹配给出警告。虽然它不阻止安装但至少给了提示省得你在奇怪的运行时报错里翻半天。5.2 全局模块不跨版本一个反直觉的隔离设计用 nvm 切换版本后之前全局安装的包在新版本里会消失。比如你在 v16 里全局装了nodemon切到 v18 再执行nodemon终端会提示命令不存在。这个设计刚接触时很反直觉我第一次遇到还以为是 nvm 坏了后来才明白nvm 的每个版本都有独立的全局目录npm 会根据当前版本绑定全局安装位置。正确做法是整理一份全局工具清单每次切换大版本后重新安装一遍。想偷懒的话可以在.nvmrc旁边放一个global.sh列出所有全局包名切换后一键重装。不要试图通过--prefix强制共享某些带原生二进制的包在跨版本场景下会报平台不匹配不值得省这个时间。5.3 从 v16 升到 v18 后为什么必须删 lock 文件重装旧项目的 node_modules 里原生模块的二进制文件和 Node 的 ABI 是绑定的。直接把 v16 时期的 node_modules 拿给 v18 用轻则报Module version mismatch重则直接启动失败。正确迁移姿势是rm -rf node_modules package-lock.json npm install别舍不得删。package-lock.json 重新生成后依赖版本范围保持不变只是按当前 Node 版本重新解析一次。删掉半个小时的缓存换来一个干净的环境这笔账怎么算都划算。6. 我遇过的 v16 安装报错和排查思路6.1 node-gyp / node-sass 编译失败的真实原因老项目安装依赖时经常卡在 node-sass、sharp、bcrypt 这类需要本地编译的包上。v16 环境报 python 相关错误的概率特别高因为 node-gyp 编译步骤需要 Python 参与。Windows 上最省事的办法是装 Visual Studio Build Tools安装时勾选“C 桌面开发”工作负载然后执行npm config set msvs_version 2022如果你还在 v16 的环境里硬扛 node-sass建议直接看项目能不能换 dart-sass 或者升级依赖。node-sass 的版本和 Node 版本绑定极其死板它早已停止维护就算硬装成功后续安全风险也得你自己兜着。6.2 “is not yet released”报错的定位方法有个搜索词是“node.js v24.21.0 is not yet released or is not available”这类报错通常来自 nvm 或其他安装脚本。当你指定了一个版本列表中不存在的版本号比如写了 24.21.0但官方只发布到 24.20.x工具去查版本列表发现查无此版就会抛出这个提示。定位方法很简单先用nvm ls-remote或直接去官网 dist 目录确认版本号真实存在再重新安装。这个报错和 v16 本身没关系但它常出现在处理旧项目时因为很多人喜欢凭记忆抄版本号抄错了就出类似问题。6.3 npm 缓存、代理和 SSL 证书异常的现场处理npm 偶尔会报UNABLE_TO_GET_ISSUER_CERT_LOCALLY这通常和公司内网代理、自签名证书有关。临时排查时可以设置npm config set strict-ssl false但这只是临时手段不能日常开着。内网环境如果必须走代理就配置npm config set proxy http://127.0.0.1:7890 npm config set https-proxy http://127.0.0.1:7890用完记得删除npm config delete proxy npm config delete https-proxy至于npm cache clean --force这种操作我的经验是能不做就不做。npm 缓存损坏的概率其实很低依赖装不上首先应怀疑 node_modules 残留、版本冲突和网络问题顺序应该是删 node_modules 和 lock 文件重装再检查代理最后才考虑清缓存。一上来就清缓存解决不了问题反而把本地缓存全打掉下次安装全部走网络慢上加慢。我自己在维护一个混合版本开发环境时最终的组合是Windows 上用 nvm-windows 管 v16 和 v18macOS 上用官方 nvm 管同样的两套版本任何项目进来先看.nvmrc再动手。v16 这台“老车”虽然早就过了官方质保期但只要项目需要它依然稳定可靠关键是一开始就要把环境装对、把坑避开。
