最近总有人跑来问我Node.js 到底怎么升级 大部分人以为从官网把安装包重新点一遍就完事结果不是 npm 全局命令全部失效就是 node -v 还卡在旧版本号上。说实话升级 Node.js 本身不难难的是升级之前搞不清楚自己的环境是怎么装的升级之后不知道该怎么验证。这篇就围绕 node.js 下载、node.js lts 下载、ubuntu 安装 node.js 20 这些高频场景把我自己这几年在 Windows、macOS、Linux 上做升级的实际操作和踩过的坑一次性说清楚。不管你是刚接手项目的前端新人还是要维护服务器 Node 环境的同学照着下面的思路走至少能避开 90% 的坑。1. 搞清楚升级对象Node.js 是什么为什么值得升1.1 先花一分钟理解 Node.js 在项目里的角色很多新人看到升级 Node.js这个操作第一反应是它不就是个运行环境吗为什么要单独维护。Node.js 确实是一个基于 V8 引擎的 JavaScript 运行时但它的作用远不止让 JS 能跑在服务器上。你在公司里跑 npm install、执行 vue build、启动 nuxt dev背后都是 Node.js 在干活。可以说Node.js 是前端工程化链条里最底层的发动机。它不是普通软件那样装了就不管的依赖而是一个持续演进的基础设施。不同的 Node.js 版本对 ES 语法特性的支持、对 npm 依赖包的兼容性、对高并发场景下的性能表现都会差很多。很多项目出现本地跑得好好的上服务器就崩的问题最后排查下来就是 Node.js 版本不一致。所以升级 Node.js 不是追新而是让开发环境、测试环境、生产环境都能对齐在同一个稳定运行区间。1.2 升级到底能换来什么我听到比较多的说法是等出问题了再升级。这种思路可以理解但风险其实挺高。Node.js 的升级收益通常集中在三块。第一是安全修复。LTS长期支持版本的维护周期里官方会持续推送安全更新。如果你一直停在一个 2020 年的旧版本上等于把已知漏洞长期暴露在外面。第二是性能和内存改善。从 18 到 20 再到 22、24事件循环、流处理、fetch API、内存占用这些方向都有明显优化尤其是处理并发请求的 Node 服务升级之后往往能感受到响应速度的提升。第三是生态兼容。现在主流的前端构建工具、CLI 工具、后端框架对新版本 Node.js 的要求越来越明确。比如很多依赖包要求 Node 20否则安装的时候会直接给你一个 engine 警告。所以升级不是给别人看的版本号而是实实在在的运行效率和安全保障。1.3 版本号怎么读别把奇偶版本当成必追Node.js 的版本号看着复杂其实规则很清晰。主版本号为偶数的才是面向稳定用户的 LTS 版本比如 18、20、22、24奇数版本比如 21、23、25 是 Current 版本功能新但稳定性要靠社区持续反馈不适合生产环境。版本命名一般是这种格式主版本号.次版本号.补丁版本号比如 20.18.1。主版本号的变化意味着大的功能调整可能带来破坏性变更次版本号通常增加功能补丁版本号则是修 bug 和安全问题。升级策略上我个人的建议是生产环境优先选偶数 LTS不要在 LTS 版本刚发布的头一两个月就急着切过去等小版本迭代到比较稳的阶段再动。开发环境则可以稍微紧跟 LTS感受到新语法和 API 的体验但也要有回滚方案。下面把几个常见版本的定位整理一下方便你对照主版本发布时间类型适合场景182022年LTS已进入维护尾声老项目继续维护逐步升级过渡202023年LTS维护期较长现阶段大多数项目的稳妥选择222024年LTS较新新项目、性能敏感服务242025年LTS新一批稳定版新项目配合最新工具链版本选择不是越新越好而是要看你手上的依赖包是否声明了 engines 字段。很多大型项目的 package.json 里直接写着 node: 20.0.0 25.0.0这时候跨大版本升级就得谨慎。2. 升级前必须做的一次环境体检2.1 三分钟查清当前版本和来源升级之前先打开终端把下面几行命令跑一遍node -v npm -v which node which npm不要小看这几条命令。node -v 看到的是最终生效的版本which node 告诉你的则是最有可能被 PATH 优先命中的可执行文件路径。很多时候不是没升级成功而是系统里装了两个 Node.js一个在 /usr/local/bin/node一个在家目录下的 .nvm/versions/nodePATH 顺序不对导致 node -v 永远指向旧的那个。另外建议你用 npm config get prefix 看一下全局安装目录。如果是 Linux 或 macOS 下面常见的 /usr/local说明当前 Node 是通过官方包或安装脚本装的如果是 /Users/你的用户名/.nvm/versions/node/v20.x.x/bin那就是 nvm 管理着的。搞清楚来源才能决定下一步该用哪种升级方案而不是一上来就覆盖安装。2.2 给项目里的依赖做一次兼容性快照升级 Node.js 最怕的不是 Node 本身跑不起来而是你的项目依赖包在新版本上炸掉。所以升级前在项目目录里执行npm list --depth0把顶层依赖列出来重点看有没有原生模块比如 node-sass、sharp、bcrypt、canvas 这类需要编译二进制文件的包。它们对 Node 版本非常敏感升级 Node 之后如果不重新编译很容易出现找不到模块或者段错误的报错。如果项目里有老旧的 node-sass我先给你提个醒这包基本属于历史遗留问题能换 sass 或者 dart-sass 就尽早换。如果依赖里出现了 bcrypt 和 sharp记得升级后跑一次 npm rebuild或者直接删掉 node_modules 和 package-lock.json 里对应项再重新安装。2.3 备份全局依赖和项目依赖列表这一步看起来多余但真能救命。升级前先把全局包列表导出来npm list -g --depth0 global-packages.txt然后把当前项目的依赖也锁定一份不需要复制 node_modules那个太大也没意义。用 package.json 和 package-lock.json 就足够了。真要回滚的时候把 Node 版本切回去再执行 npm ci 就能恢复原样。如果你有全局安装的 CLI 工具比如 vue-cli、angular/cli、nest-cli、pm2 这类升级后也建议重新安装一遍。全局包的编译路径往往绑定了旧版本的 ABI二进制接口Node 大版本一换这些工具就得重来。2.4 确定目标版本LTS 优先别被最新版带跑升级之前最核心的问题就是到底要升到哪个版本。如果你没有特殊需求我的习惯是直接看 Node.js 官网的 LTS 版本列表或者查一下 nodejs.org 页面上标着 LTS 的版本号。比如当前稳定线是 20 和 22新一点的 LTS 是 24那就根据项目的依赖要求二选一。这里有个小技巧在项目里执行node -e console.log(process.versions.node)如果项目代码用到了比较新的原生 API比如 fetchNode 18 开始稳定、Web Streams、结构化复制那至少选 20 以上比较合适。如果只是想修安全和性能问题原地升级同一条 LTS 线的小版本就够了比如从 20.11 升到 20.18不用跨大版本。千万不要为了尝鲜去下载奇数版本。在开发环境跑着玩没问题但如果你还要带团队、发布生产项目奇数版本会让你成为同事的噩梦源头。3. 四个主流升级方案按场景选最顺手的那种3.1 Windows 官方安装包覆盖安装最省心但要注意 PATHWindows 上的 Node.js 升级最常见的就是去 nodejs.org 下载新版 LTS 安装包双击一路 Next。这种方式会把新版本覆盖安装到原来目录默认路径通常还是 C:\Program Files\nodejs\node.exe 和 npm 都会一并更新。但有一个坑如果你之前是用 nvm-windows 或国内某些一键安装包装的 Node再到官网下载安装包覆盖会出现两个 Node 同时存在的混乱情况。检查办法是打开命令行执行where node看输出的是几个路径。正常情况下应该只有一个路径。如果出现多个建议先把旧版本卸载干净删除残留目录再安装新版。Windows 用户更省心的做法是用 wingetwinget install OpenJS.NodeJS.LTS这个命令会自动下载 LTS 版本并处理好环境变量。不过公司内网有时无法访问 winget 源那就回到官网手动下载。安装完后新开的终端窗口里的 node 命令才会引用新版本老终端需要重启一下。3.2 macOS 用 Homebrew一行命令但要分清 tapmacOS 上如果一直用 Homebrew 管理软件升级 Node.js 很简单brew update brew upgrade node对于从官网 PKG 包安装的 Nodebrew 可能不认此时做一次彻底的清理再 brew install node 更合适。还有一个细节是需要搞清楚 Node 是通过 brew 的 node formula 装的还是通过 nvm 装的。如果你既用过 nvm 又用过 brewmacOS 的 PATH 会被搞得很乱。我自己的习惯是 macOS 上尽量统一用 nvm。因为很多时候要同时维护两三个项目的 Node 环境某个项目锁在 18另一个项目要求 22brew 这种全局安装的方式切换版本非常痛苦。如果你已经用 nvm就不需要 brew upgrade node直接在 nvm 里安装新版本即可。3.3 Ubuntu 系列 Linux 的三种姿势重点说 20 怎么装用 Linux 服务器的人最关心的是 ubuntu 安装 node.js 20 到底怎么做。Ubuntu 官方 apt 源里的 Node.js 通常版本偏老直接 apt install nodejs 可能装出 10 或者 12所以大多数情况下要自己加源或者用二进制包。一种方式是 NodeSource 官方源。在 Ubuntu 上安装指定大版本可以这样curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs这个脚本会自动把 NodeSource 的仓库写入 apt 源然后 apt 安装的就是 Node.js 20 的最新小版本。如果你要装 22 或 24只需要把 setup_20.x 改成 setup_22.x 或 setup_24.x。注意 curl 的链接必须是你信任的官方源不要从第三方转载的脚本瞎改。另一种姿势是直接用 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash nvm install 20 nvm use 20nvm 的好处是免 sudo、可以多版本共存。Ubuntu 服务器上如果没有特殊理由我个人更推荐 nvm。它的第二个好处是升级不需要动系统级的 /usr/bin/node不会影响容器或系统服务里已经写死的路径。还有一种最硬核的方式是下载官方二进制 tar 包手动解压。比如wget https://nodejs.org/dist/v20.18.1/node-v20.18.1-linux-x64.tar.xz tar -xJf node-v20.18.1-linux-x64.tar.xz mv node-v20.18.1-linux-x64 /opt/nodejs ln -s /opt/nodejs/bin/node /usr/local/bin/node ln -s /opt/nodejs/bin/npm /usr/local/bin/npm这种方式适合对系统路径和权限有严格要求的场景。不过手动解压的版本不会自动更新后续升级要自己重复操作容易忘。所以我建议除非是离线内网环境否则优先考虑 NodeSource 或 nvm。3.4 nvm一套能解决版本切换的终极方案不管你在哪个平台只要是类 Unix 环境nvm 都是绕不开的好工具。它不直接改你系统里的全局 node而是把每个版本安装到用户目录下的 .nvm/versions 里然后通过软链接的方式切换 PATH。几个最常用的命令nvm install 20 # 安装指定的 Node 20 最新版 nvm install 22 # 安装 Node 22 最新版 nvm alias default 20 # 设置默认版本 nvm use 22 # 当前终端临时切换 nvm ls # 查看本机已安装版本 nvm ls-remote # 查看可远程安装的版本列表 nvm uninstall 18 # 卸载不再需要的版本nvm 最有用的一点是每个终端会话都可以有独立版本。项目 A 用 20项目 B 用 22不需要卸载重装切个目录直接 nvm use 就行。自己平时开发强烈建议把 nvm alias default 设置成稳定的 LTS减少每次打开终端还要手动切版本的麻烦。如果在 Windows 上nvm 原版不直接支持但可以使用 nvm-windows它的基本命令风格类似。不过 nvm-windows 和 Linux 版并不完全等价某些版本切换通过修改映射目录来实现遇到权限问题也比较多建议 Windows 新手还是用官方安装包或者 nvs 来管理。3.5 Docker 和 CI 里的 Node 版本别忘了同步升级提到升级 Node.js很多人的注意力全在本地环境容易忘了服务器上的 Docker 镜像和 CI 的构建环境。Dockerfile 里通常有一行 FROM node:18-alpine这才是生产环境真正跑代码的版本容器。只把本地的 node 升上去线上还在跑老镜像没有任何意义。更新 Docker 镜像版本的方法是在 Dockerfile 里把基础镜像的 tag 改成 node:20-alpine 或 node:22-slim。改完后重新构建镜像、推送到镜像仓库、让服务拉取新镜像才算完成一次完整的升级。CI 里如果是 GitHub Actions、GitLab CI、Jenkins也要注意其中 setup-node 或 node 镜像版本的一致性。这一步很多人会遗漏强烈建议把本地、CI、Docker三处版本放到同一个检查清单里。省得将来线上出现问题排查到凌晨才发现是线上 Node 还是旧的。4. 升级时的高频报错与排查实录4.1 最容易被搜到的报错Node.js v24.21.0 is not yet released or is not available这个报错我帮人排查过好几次当时的问题是执行 nvm install 24.21.0 的时候提示error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。先说结论这个报错不是因为你的操作步骤错了而是你试图安装的版本号在当前 nvm 远程列表中不存在。为什么会出现这种荒谬的情况原因主要有几个。最常见的是版本号拼写错误把 24.21.0 想当然地当成最新版但官方最新可能停在 24.20.2nvm 去官方源拉版本列表时找不到完全匹配的版本号。第二个原因是 nvm 的版本列表没有更新本地还停留在旧快照官方其实已经发布了新版本但nvm ls-remote还没拉到。第三个原因是某些镜像源没有同步到版本列表里导致 nvm 请求的服务器返回了 404。处理办法也不复杂。第一步先执行nvm ls-remote看看可选的版本到底有哪些。如果列表里没有你要的版本说明这个版本还没发布或者源没同步。想安装某个大版本的当前最新小版本直接用nvm install 24就好不要手动指定一个不确定的小版本号。如果需要精确用某个版本等官方版本发布之后再装。另外还可以检查一下 nvm 使用的镜像地址确认是不是配了某个只同步了 LTS 的源。还有一个小细节如果你用的是二进制包直接下载nodejs.org 的 dist 目录里会以版本号命名文件夹比如 v24.20.0。如果文件夹不存在也会报 404。同样的道理版本未发布或目录名打错都会触发类似提示。4.2 升级后 node -v 还是旧版本多半是 PATH 顺序问题这个问题在 macOS 和 Ubuntu 上特别多。明明 nvm install 20 成功了node -v 显示的还是 18。多数情况是 nvm 的 shims 目录没有排在 PATH 最前面或者系统里还残留着 brew、apt 安装的 Node。排查步骤which node echo $PATH ls -la /usr/local/bin/node如果 which node 显示的是 /usr/local/bin/node但你 nvm 里已经安装了新版本说明 nvm 没有接管 PATH。在 Ubuntu 上可能需要重新加载 shell 配置source ~/.nvm/nvm.sh在 .bashrc 或 .zshrc 里确认包含 nvm.sh 的加载行。macOS 还要检查是不是同时用 brew 装过 nodebrew 的路径优先级有时会盖过 nvm。解决方式是保持单一安装来源必要时卸载 brew 安装的 nodebrew uninstall --force node新的终端再执行 node -v应该就能找到 nvm 的版本了。4.3 npm 全局命令找不到路径引用了旧版本升级完 Node.js 后执行 npm run dev 可能直接提示 sh: command not found: nodemon或者输入 vue --version 报错。这种情况通常是全局工具目录没有跟着升级而更新。如果你用的是 nvm全局包是安装在每个 Node 版本自己的目录下的版本切换后需要重新安装全局包。相比之下从 Linux 发行版包管理器安装的 Node全局包统一安装在 /usr/lib/node_modules 里升级时 npm 可能被替换但全局包的链接没变有时反而没问题。解决办法是升级后执行npm install -g npmlatest npm install -g nodemon pm2 vue-cli # 按需补装如果你有完整的全局包列表备份直接cat global-packages.txt | xargs npm install -g也能一次性装完。这里引出了一个经验不要把重要的全局 CLI 工具完全依赖在某一次升级后仍然自动保留的假设上升级之后最好主动检查一遍。4.4 权限、缓存与符号链接问题冷门但真会碰到Linux 上执行 npm install -g 报 EACCES 权限错误多半是 npm 全局目录属于 root而当前用户没有写入权限。两个方向要么给全局目录添加用户归属要么使用 nvm 这种基于用户目录的安装方式绕开权限问题。还有一种情况是符号链接失效。手动解压官方 tar 包安装 Node 时如果 ln -s 建了软链接后续新版本解压目录改名后旧软链接会指向不存在的文件。这时候 ls -la /usr/local/bin/node 会看到一个红色闪烁的链接。重新 ln -sfn 一下目标路径就能解决。npm 缓存问题也偶尔出现表现是安装某个包时一直报 integrity checksum failed。这种可以先清缓存再重试npm cache clean --force不过这种问题一般和 Node 升级没有直接关系更多是网络缓存环境导致但升级后如果 npm 版本也变了新版本对缓存校验更严格容易把老缓存的问题暴露出来。下面整理一份速查表报错现象核心原因解决思路Node.js v24.21.0 is not yet released版本号不存在或 nvm 列表未同步nvm ls-remote 查看真实版本用nvm install 24node -v 仍显示旧版本PATH 顺序问题或另一套 Node 占用检查 which node移除多余安装源全局命令 not foundnvm 切换版本后全局包不共用升级后按需重新安装全局 CLI 工具EACCES 权限报错npm 全局目录归属 root使用用户目录安装或调整目录权限软链接失效手动安装后路径变更重新 ln -sfn 建立链接5. 升级完不是结束验证版本、固定版本、稳住团队5.1 用三行命令完成基础验证不管用哪种方式升级完成后都不要直接跑业务。打开新终端先执行三行验证命令node -v npm -v which node确认版本号已经是目标版本并且 which node 指向你预期的路径。然后在一个临时目录里创建一个简单脚本测试node -e console.log(hello from node, process.version)再跑一下 npm config get registry确认镜像源没有因为升级被重置成官方源。如果之前配过内部 npm 镜像或者常用镜像升级后要检查一下有时候 npm 本身的大版本升级不会保留旧配置。5.2 顺手把 npm 和全局依赖更新掉升级 Node.js 只是第一步npm 也会跟着变。你可以主动再执行npm install -g npmlatest npm update -gnpm update -g 可能会更新很多全局包耗时比较长所以建议确认自己有时间再执行。对于生产服务器全局包越少越好能不全局装就不全局装避免依赖冲突。如果你在升级过程中发现 npm 缓存有问题也可以参考官方文档处理。总之升级后别急着开会先把本地和 CI 上的版本对齐再继续推进。5.3 用 engines 和 .nvmrc 把版本一致性钉死在工程里升级完自己电脑上的 Node还要保证团队其他成员、CI、服务器不会又用回旧版本。最工程化的做法是在 package.json 里声明 engines 字段engines: { node: 20.0.0, npm: 10.0.0 }这样使用 npm 或 pnpm 时如果 Node 版本不满足要求npm 会给出警告。不过 engines 只是警告并不会阻止安装更严格的约束需要配合 .nvmrc 使用。在项目根目录创建一个 .nvmrc 文件文件内容只有一个版本号比如20.18.1然后团队成员在项目目录执行 nvm usenvm 就会根据 .nvmrc 自动切换到指定版本。对于用 CI 的项目setup-node 的 action 里也可以读 node-version 文件或者手动指定版本这样整个链路都用同一个版本。5.4 升级频率怎么定我的建议与项目规划最后说说节奏。Node.js 升级不是越频繁越好但也别三年不动。我的建议是每季度花半天到一天时间检查一次当前使用的大版本是否还在维护期内。如果官方已经宣布某个 LTS 进入 EOL就列个升级计划。比如 Node 18 的维护期接近尾声就尽早规划切到 20 或 22。具体项目里的升级频率要结合依赖包的兼容性来定。对于依赖简单、后端服务轻量的项目跟随 LTS 节奏走没问题。对于用了大量原生模块、老构建工具的项目升级前必须做一次完整的构建和自测。可以先把新版 Node 装到开发环境跑一遍回归测试再推到 CI 和测试环境最后动生产环境。这个顺序别颠倒稳才是第一位的。我在实际维护多个项目的过程中悟到一个经验升级 Node.js 这件事真正重要的不是记住几条命令而是理解自己的环境是怎么组成、依赖包对版本有多敏感、团队如何保持一致。把 nvm 用熟、把 .nvmrc 和 engines 用起来之后每次升级都会变得很平滑。希望这篇能帮你在下次面对版本升级时少走一点弯路也欢迎把你自己踩过的坑分享出来一起把环境维护得更干净。