刚从一段聊天记录里看到有人急着喊“Node.js看我的就行了”再往下翻大家都在问 node.js 安装、node.js 官网下载、ubuntu 安装 node.js 20 到底怎么弄。老实说Node.js 这玩意儿平时看着门槛不高但真正动手装的时候一堆人就卡在版本选择和报错排查上了尤其那句“error installing 24.21.0: node.js v24.21.0 is not yet released”一下就能劝退一大半新手。这篇东西就围绕 Node.js 从零开始说清楚它到底解决什么问题版本号怎么读Windows、macOS、Ubuntu 上分别怎么装装完以后常见报错怎么破最后再聊聊我自己的实际体会。适合刚接触 Node.js 的前端新手、想在自己电脑上搭开发环境的同学还有那些已经在用但每次重装系统都要重新踩一遍坑的人。看完这篇Node.js 这块基本就能一次弄利索不用再来回折腾。1. 先把“Node.js 是干什么的”这件事搞明白很多人第一次搜 node.js搜出来的全是安装教程但装完之后其实并不知道它到底为什么存在。我建议新手别跳过这一节因为你不理解它的定位后面遇到“为什么要用 npm”“为什么前端要装 Node”这类问题的时候还是会懵。1.1 一句话说清楚 Node.jsNode.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时环境。什么叫运行时环境你可以把它理解成“让 JavaScript 在浏览器之外也能跑起来”的容器。以前 JavaScript 只能在浏览器里写写表单校验、做做页面交互但 Node.js 出现以后JavaScript 就能操作文件、连接数据库、处理网络请求、搭建服务器变成了一门可以走后端开发的语言。它最核心的设计思路是事件驱动和非阻塞 I/O。传统服务器处理请求的时候遇到文件读写或者数据库查询线程会一直等着结果返回这期间啥也干不了但 Node.js 遇到耗时操作不会傻等而是先挂起一个回调继续处理下一个请求等结果好了再回过头来处理。用生活化的类比来说传统方式像是去银行柜台办业务一个窗口只能服务一个人后面的人排队。Node.js 则像是叫号系统一个窗口同时处理很多人的需求有人要复印材料就去复印窗口先叫下一位等材料好了再叫回来。这种模型特别适合 I/O 密集型的应用比如聊天服务、实时推送、API 网关这类场景。1.2 Node.js 解决的核心问题在没有 Node.js 之前前后端是两套完全不同的语言体系。前端用 JavaScript后端用 PHP、Java、Python 这些每次前后端对接都要商量接口格式、维护两套工程规范。Node.js 出现以后至少前端团队可以只用 JavaScript 就把后端服务也写了整个技术栈统一了。它解决的另一类问题是前端工程化。现在的前端项目基本都离不开 webpack、vite、rollup 这些构建工具写 SCSS 要编译写 TypeScript 要转译写 Vue、React 要打包这些工具全部跑在 Node.js 上。哪怕你只是写一个静态页面只要用了构建工具电脑上就必须装 Node.js。所以现在前端开发的第一件事不是写代码而是装 Node.js这个环节绕不过去。1.3 哪些人必须装 Node.js我把需要装 Node.js 的人群分成三类你可以自己对号入座前端开发者要跑构建工具、要本地起 dev server、要用 npm 安装依赖包必须装。后端开发者想用 JavaScript 写服务端接口或者维护已有的 Node.js 服务必须装。自动化脚本爱好者想用 JavaScript 写一些本地脚本比如批量重命名文件、抓取网页数据、自动同步目录Node.js 是最方便的脚本环境之一。连我认识的不少做测试、做运维的朋友电脑里也都装了 Node.js只是为了跑一些工具链脚本。这玩意儿已经成了开发环境的基础设施跟装 Git、装终端一样标配。2. 版本选择的第一课为什么 LTS 才是你的首选热搜词里有一长串都是关于版本身的内容什么“node.js lts 下载”“ubuntu 安装 node.js 20”还有人贴出 “error installing 24.21.0: node.js v24.21.0 is not yet released”。这类报错一看就知道是用版本管理器装了一个尚未发布的版本号。很多人根本没搞明白 Node.js 的版本规则就随手敲了个数字进去结果不进坑才怪。2.1 Node.js 版本号到底怎么读Node.js 的版本号遵循 SemVer 语义化版本规范格式是主版本号.次版本号.补丁版本号。主版本号变大说明有重大变更很可能不兼容旧代码次版本号变大说明加了新功能但向后兼容补丁版本号变大说明只是修 bug。真正关键的是主版本号的奇偶规律。Node.js 的偶数主版本号比如 14、16、18、20、22属于长期维护版本也就是 LTSLong Term Support版本官方会持续维护很多年修 bug、补安全漏洞奇数主版本号比如 15、17、19、21属于当前版本只维护几个月主要是给想尝鲜的人用到了下一个偶数版本发布之后奇数版本很快就不再维护了。我给新手一个最直接的结论不要装奇数版本不要追最新版本。就装当前的 LTS 偶数版本。你写业务代码LTS 和 Current 之间的 API 差异你在日常开发里基本感知不到但 LTS 的稳定性、生态兼容性、安全更新时长都是 Current 没法比的。2.2 LTS 和 Current 的对比我在给团队做环境标准化的时候最常被问的一句话就是“为什么不装最新版”。这里我给一张对照表看完就明白了对比维度LTS长期维护版Current当前最新版主版本号偶数如 20、22奇数或刚发布的新偶数版初期维护周期官方承诺 3 年以上维护通常 6 个月左右就到下一轮稳定性经过大量生产环境验证新特性多但可能有回归 bug生态兼容npm 上的主流包基本都已适配部分老包可能出现兼容问题适合人群生产开发、公司项目、绝大多数个人开发者尝鲜者、Node.js 核心源码贡献者升级频率低频但有确定周期节奏快几乎每隔几个月就有大版本这张表我建议收藏。以后别人问“为什么我装的版本过几个月就没人维护了”你就能直接甩这张表给他。2.3 那些没被正式发布的版本为什么会报错开头那个报错 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”本质上是版本管理器在请求一个不存在的版本。Node.js 官方在 GitHub releases 页面上只会发布真实存在的版本号如果你用 nvm 去 install 一个还没发布、或者写错的版本号版本管理器会去远端拉取版本列表匹配不到就会抛出这类错误。还有一种情况是在用 n 或者 nvm 的时候你指定了 “latest” 或者手滑多打了一个小版本号比如当前实际只发布到 24.2.0你敲成 24.21.0数字本身合法但不真实存在于是就会报 not yet released。这和使用姿势没关系纯粹是版本号输入错误。解决办法也很简单先通过nvm ls-remote或者nvm list available查看远端所有真实存在的版本再挑一个 LTS 安装就不会出这种幺蛾子了。3. 实操开始三平台安装与踩坑记录下面进入正题。我按 Windows、macOS、Ubuntu 三个平台分别写每个平台的思路会略微不同。总体原则是能用官方安装包就用官方安装包Linux 服务器上建议用节点版本管理器 nvm方便以后切换版本。3.1 通用准备动作不管你用什么系统装完以后都要打开终端验证两个东西node 本身和它自带的包管理器 npm。验证命令很简单node -v npm -vnode -v 会输出当前 Node.js 版本号npm -v 会输出 npm 的版本号。如果你能看到两行版本号说明安装成功。如果提示 “command not found”或者“不是内部或外部命令”说明环境变量没配上后面我会专门讲。另外一个很重要的概念npm 是跟 Node.js 一起安装的。你装 Node.js 的时候npm 就自动有了不需要单独去装。npm 的作用是管理 JavaScript 的第三方依赖包以后你用npm install xxx安装各种库全都要靠它。所以验证 npm 版本不是多此一举是为了确认基础链路是通的。3.2 Windows 平台安装Windows 上最省事的安装方式是直接下载官方安装包。打开 Node.js 官网首页最显眼的位置就是两个下载按钮左边是 LTS 版本右边是 Current 版本。我前面已经说了新手只认准左边的 LTS。下载下来的文件是一个 .msi 格式的安装包双击运行一路 Next 就能装完。但有几个选项我提醒你注意一下安装路径默认在 C 盘 Program Files 下如果你 C 盘空间紧张可以改到 D 盘但要注意改路径后环境变量是自动配置的一般情况下不要手动去改。安装向导里有一项 “Add to PATH”默认是勾选的千万别取消。这项的作用是把 Node.js 的可执行文件路径写入系统环境变量 PATH取消之后你在命令行里敲 node 会提示找不到命令很多人装完好几天后说“我明明装了却用不了”十有八九就是这里出了问题。安装向导还会问是否安装 “corepack”这是用来管理包管理器比如 pnpm、yarn的工具保持默认勾选即可。装完以后重新打开一个命令行窗口注意装了以后已经打开的命令行窗口不会自动获取新的环境变量要关掉重开再执行node -v和npm -v看到版本号就说明装好了。3.3 macOS 平台安装macOS 上的安装方式有两种主流选择。第一种也是去官网下载 .pkg 格式的安装包双击安装同样是一路 Next第二种是如果你已经装了 Homebrew直接用一条命令brew install node但这里有个坑用 Homebrew 默认安装的是当前最新版不一定是 LTS 版本。如果你对版本有要求可以先搜索仓库里的版本brew search node搜索出来你会发现有 node、node22、node20 这样的具体版本 formula。想安装指定 LTS 版本就明确指定比如brew install node22但我个人在 macOS 上更推荐直接用 nvm 管理理由后面单独说。如果你只是想快速装一个能用的环境官网 pkg 包最直接不用折腾 Homebrew 的依赖关系。还需要提一句macOS 如果弹出“无法打开因为无法验证开发者”的提示去“系统设置-隐私与安全性”里点一下“仍要打开”就行这是 macOS 对未签名或新下载应用的安全限制不是什么大事。3.4 Ubuntu 安装 Node.js 20 的完整流程Linux 环境下的安装方法和 Windows、macOS 都不太一样尤其是 Ubuntu因为系统自带的 apt 源里的 Node.js 版本非常老。热搜里明确有“ubuntu 安装 node.js 20”我重点讲这个。先解释一下为什么 apt 装的不行。Ubuntu 的默认软件源里确实有 nodejs 这个包但版本很旧很多还是 12.x 甚至 10.x早就不在维护期了。用旧版本跑新项目经常会出现依赖包要求 Node 18 而你是 Node 12 的尴尬局面。所以不要在 Ubuntu 上用apt install nodejs一条命令解决问题——这个方法对新手来说是最省事的但用的是一颗定时炸弹。正确的方案是下面三种我按推荐程度排序方案一用 NodeSource 官方仓库适合固定版本的生产环境NodeSource 是 Node.js 社区里相当权威的第三方源专门提供较新版本的 Node.js 二进制包。安装 Node.js 20.x 用下面这条命令curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs这里解释一下第一条命令会把 NodeSource 的软件源加到你的 apt 源列表里同时更新缓存第二条命令才真正安装 nodejs 包。装完以后可以验证node -v npm -v我记得我第一次在 Ubuntu 上跑这套命令的时候卡在了 curl 命令不存在的报错上。如果你也遇到这个问题先装一下依赖sudo apt update sudo apt install -y curl然后再执行 NodeSource 的安装命令。方案二用 nvm 安装适合需要切换版本的开发机说实话我在自己电脑上装 Node.js 从来不用系统包管理器一律用 nvm。nvm 的全称是 Node Version Manager它可以在同一个系统里安装多个 Node.js 版本随时切换。对开发机来说它的优势是彻底不用折腾环境变量也彻底不需要 sudo 权限。安装 nvm 的命令curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash执行完以后需要重新加载一下环境变量export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh当然如果你用的是 bash 作为默认 shell重新登录终端也会自动加载。接着你就可以列出所有远端可用的 Node.js 版本然后安装指定 LTS 版本nvm ls-remote nvm install 20 nvm use 20nvm install 20的意思是安装 20.x 系列最新的 LTS 版本具体是 20.19.x 还是别的nvm 会自动帮你选。nvm use 20是把当前 shell 的默认 Node.js 切换到 20 系列。用 nvm 装完以后它就放在用户目录下的 .nvm 文件夹里跟系统级目录完全隔离以后想卸载也干净直接删目录加删 nvm 的配置行就行。方案三直接下载官方二进制压缩包适合没有 sudo 权限的服务器有些公司的服务器不会给你 sudo 权限但又需要特定版本的 Node.js这时候就用官方提供的 tar.gz 包。请根据架构选择x64 的服务器用下面命令wget https://nodejs.org/dist/v20.19.0/node-v20.19.0-linux-x64.tar.xz sudo tar -xJf node-v20.19.0-linux-x64.tar.xz -C /usr/local/ sudo ln -s /usr/local/node-v20.19.0-linux-x64/bin/node /usr/local/bin/node sudo ln -s /usr/local/node-v20.19.0-linux-x64/bin/npm /usr/local/bin/npm这里先用 tar 命令解压到 /usr/local 目录然后给 node 和 npm 分别创建软链接让全局命令可以直接访问。注意具体的版本号要以官网实际发布的为准我给的 20.19.0 只是举例。这种方式的优点是完全不依赖 apt缺点是以后升级版本要手动替换软链接和目录稍微麻烦一点。4. 装完之后那些最容易碰到的报错很多新手把 Node.js 装上以后觉得万事大吉结果在用的时候接二连三地碰到报错。我把自己这些年看到的、遇到过的典型问题整理成一个速查表配合排查思路一起看会比直接搜报错文案高效得多。4.1 报错速查表报错信息场景最常见原因解决思路node: command not found命令行敲 node 没反应没装好或环境变量 PATH 没配置检查安装路径Windows 确认 PATH 有没有 nodejs 目录error installing 24.21.0: node.js v24.21.0 is not yet releasednvm/n 安装指定版本时报错版本号不存在或写错先nvm ls-remote查真实版本再安装npm: command not foundnpm 命令找不到npm 随 Node.js 安装但 PATH 缺失重新安装 Node.js或用软链接指向 npmEACCES: permission denied全局安装 npm 包时提示权限用 root 方式全局写目录不要用 sudo npm改用 nvm 管理用户级权限npm ERR! code ENOTFOUNDnpm install 时报 DNS 错误网络无法访问 npm 源检查网络或使用国内镜像源node -v 有输出但项目跑不起来项目启动报语法错误项目要求更高 Node 版本看 package.json 的 engines 字段切换 LTS 版本nvm command not found重开终端后找不到 nvmnvm 的环境变量没加载检查 .bashrc / .zshrc 里的 nvm 初始化行这张表我建议直接存起来。下面挑几个高频的细说一下排查思路。4.2 “node 不是内部或外部命令”到底怎么修这个报错在 Windows 上最常见。出现这个提示说明系统光是“知道有 Node.js 这回事”但命令行找不到它。先检查 Node.js 到底装哪了一般默认在 C:\Program Files\nodejs\。如果这个目录存在但命令行还是找不到那就是 PATH 环境变量里没加这个路径。打开“系统属性-环境变量”在用户变量的 Path 中新建一条把 nodejs 目录路径填进去保存后重新打开命令行。这里有个小细节PATH 修改之后已经打开的命令行窗口不会自动生效必须开一个新窗口。很多人改完以后原地敲命令发现没用其实不是没改成功只是窗口没更新。另一种情况是“node 命令在但 npm 不在”这通常发生在手动解压二进制包的时候只给 node 建了软链接却忘了 npm。Windows 上一般不涉及软链接问题更多是安装包损坏或者被杀毒软件拦截了安装过程重新下载官方安装包再装一次基本能解决。4.3 权限相关的坑在 Linux 或 macOS 上使用全局安装命令的时候很容易遇到 EACCES 权限报错。比如npm install -g create-react-app如果报权限不足很多人的第一反应是加 sudosudo npm install -g create-react-app这个做法能解决眼前问题但后患无穷。全局目录归 root 所有以后每次全局安装都要 sudo而且 sudo 状态下 npm 脚本运行的权限模型和当前用户不一致容易踩权限边界问题。正确解法是用 nvm 装 Node.js因为 nvm 会把所有内容都放在用户目录下不存在跨用户写入的问题。如果不想换版本管理器也可以手动修改 npm 全局目录的归属mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把 ~/.npm-global/bin 加进 PATH。这种方式也能绕开 sudo。不过我个人的经验是既然要长期搞开发不如一步到位用 nvm省得后续每次都要想权限这件事。4.4 镜像源和网络问题如果你在国内环境安装依赖经常遇到 npm install 卡住不动或者报网络超时。这不是 npm 的 bug也不是你代码的问题纯粹是默认源访问速度不行。改成国内镜像源是最直接的优化方案npm config set registry https://registry.npmmirror.com改完之后可以验证一下是否生效npm config get registry输出里能看到镜像源地址就说明设置成功了。这个方法只改 npm 的下载源不影响 Node.js 版本。以后想改回官方源执行同样的命令把地址换回 https://registry.npmjs.org 即可。我们团队做过一个粗测同一台服务器上从默认官方源拉依赖经常要两三分钟起步换了镜像源基本十几秒能完成体感差异巨大。如果你的项目包含大量依赖甚至可以把 pnpm 的仓库存储也指到同一个镜像源效果更好。4.5 版本混用和缓存混乱的问题还有一个容易忽视的问题是电脑里同时存在多个 Node.js 版本来源不同互相干扰。比如有些人先通过官网装了一个系统级 Node.js后来又装了 nvm然后在 nvm 里又装了一个版本。结果命令行里 node -v 显示的版本跟你项目需要的版本不一致。排查思路是which node在 Windows 上则是where.exe node这条命令会显示当前命令行实际调用的 node 可执行文件路径。如果路径指向系统目录而你明明在 nvm 里切换过版本大概率是 PATH 顺序问题nvm 的路径排在系统目录后面了。解决办法是调整 PATH 顺序或者干脆卸载掉系统级的 Node.js只用 nvm 管理。项目级的版本锁定问题也值得提醒。在每个项目里创建一个.nvmrc文件内容是需要的版本号比如echo 20 .nvmrc然后进项目目录执行nvm usenvm 会自动读取 .nvmrc 并切换到对应版本。这样团队协作的时候每个人本地的 Node 版本就是一致的避免“我本地明明能跑到你那就报错”这类经典的“环境不一致”问题。我也建议在 package.json 里写明引擎要求{ engines: { node: 20.0.0 } }虽然这个字段不会强制拦截所有执行流程但至少是一个声明别人拿到项目就能一眼看到版本基线。5. 安装验证与日常维护的小习惯环境装好了不等于以后就不出问题。我在日常开发中习惯性地会做一些验证和维护动作很小但能避免不少坑。5.1 每装完一个新版本做一次最小化验证这是一个我坚持了很久的习惯。装完 Node.js 不是为了看到版本号就完事而是要做一次最小化的运行验证确认 runtime 本身真的能干活。具体这么做node -e console.log(hello from node)如果输出 hello from node说明 Node.js 运行正常。再验证一下 npm 能否正常安装一个临时包npm install -g cowsay cowsay hello这只是个简单到有点无聊的验证但它能一次性暴露 PATH、权限、网络三个维度的问题比单纯看版本号靠谱得多。如果这条链路都通了那你的 Node.js 基本就是能用的状态。5.2 定期升级 LTS 小版本的节奏LTS 版本也并不是装完就一劳永逸。LTS 主版本在维护期内会有很多次小版本更新这些更新主要是修 bug 和安全漏洞建议跟进。用 nvm 的话在小版本序列里升级很容易nvm install 20 --reinstall-packages-from20 nvm use 20这里--reinstall-packages-from20的意思是在装新版本时从旧的 20.x 版本迁移已安装的全局 npm 包。升级完之后再跑一次 node -v确认版本号的补丁号变了就说明升级成功。升级节奏我个人的建议是不要一看到新版本就冲观察一周到两周看看社区有没有报重大回归问题再决定要不要升。特别是公司项目不要在生产环境升级 Node.js先在测试环境跑一轮回归。Node.js 官方每个 LTS 版本都有清晰的维护时间表你可以把自己常用的 LTS 版本进维护期后的时间记在日历里提前一个季度计划迁移。5.3 多项目并行时的版本管理建议如果你同时维护好几个项目有的用 Node 18有的用 Node 20有的甚至还在用 16那你必须用 nvm并且每个项目都要有 .nvmrc。千万不要幻想一个 Node.js 版本打天下因为老项目的依赖可能在新版本下跑不起来新项目的依赖又要求高版本强行统一只会恶心自己。给团队的建议是至少统一 Node 大版本团队内部所有成员都用同一个 LTS 主版本比如都切到 20。这样 CI 和本地环境保持一致构建产物也更可控。如果团队里有人已经用了 nvm那就在项目文档里写清楚切版本的命令如果有人直接用的官方安装包那就建议他换成 nvm方便以后切换。6. 最后再分享一点我自己的体会折腾 Node.js 这几年踩得最深的一个坑就是“追新”。以前我也喜欢看到新版本发布就马上升级总感觉新版本等于更好结果有次把一个项目从 16 升级到 19依赖树里两个核心库直接报错查了一整天才发现是某个原生模块没适配新版本。从那以后我学乖了开发环境追新可以但生产项目一律用偶数 LTS升级前先看依赖包的兼容矩阵再跑完整回归稳字当头。另一个体会是“不要怕重装”。很多人电脑上 Node.js 环境一团乱麻不敢动怕一卸载连项目都跑不起来。其实 nvm 的出现就是为了解决这个痛点你可以放心地把系统级的 Node.js 清掉然后全部交给 nvm 管理。我第一次清理系统级 Node.js 的时候也有点慌清完才发现 nvm 收编所有版本之后不但项目没挂连全局命令都比以前整齐了。最后想说的是环境这东西本质上是一个“一次配好长期受益”的投资。多花十分钟把 LTS 版本、npm 源、nvm、.nvmrc 这些东西理顺你后面写代码省下的时间远超这十分钟。希望这篇内容能帮你把 Node.js 从安装到日常维护这条路一次走通以后别再在版本和报错上反复打转了。