如果你在一台 Ubuntu 18.04 的机器上敲下node -v看到的是v8.10.0或者更老的版本而手头的前端项目一跑就报语法错误那这篇就是写给你的。Ubuntu 18 官方源里的nodejs包版本常年停在老版本直接apt install nodejs装出来的结果根本带不动现在的 Vite、webpack 5 和一堆要求 Node 16 的 npm 依赖。这篇文章我会把升级 Node.js 到高版本的四条路线讲清楚重点给出我日常最常用的 nvm 方式以及适合生产环境服务器使用的 NodeSource 仓库方式每一步都带上命令、原理和实际踩坑记录。无论是本地开发机还是云服务器按下面的步骤操作都能装上一个能正常跑现代前端项目的高版本 Node.js。1. Ubuntu 18 官方源里的 Node.js 为什么永远那么旧1.1 先摸清楚系统里默认的 node 到底是什么版本Ubuntu 18.04 的代号是 Bionic2018 年发布当时的 Node.js 主流版本还停留在 8.x 和 10.x。Ubuntu 官方软件源会做一件容易让人误解的事它会一直给nodejs这个包推送安全补丁但不会把大版本从 8 升到 12、14 或者更高。所以哪怕你刚装完系统就sudo apt update sudo apt upgradenodejs依然停留在仓库里那个初始大版本附近最多是小版本号和补丁号变一变。想确认自己系统里的候选版本可以直接跑一条命令apt-cache policy nodejs nodejs-dev npm输出里Candidate那一行一般就是apt实际会安装的版本。在 Ubuntu 18.04 上它大概率显示的是8.10.0或者10.19.0具体取决于你是否配置过其他 PPA。很多新手在这里有个误区以为apt update之后 Node.js 就会跟着变新实际上 Ubuntu 官方对 LTS 系统的策略是“只修安全不升大版本”所以这条路基本是死的。1.2 老版本 Node 在现代前端工程里的典型症状装完老版本 Node最初几天可能没什么感觉但一旦开始跑稍微新一点的项目问题就成串出现。最常见的几种表现是npm install直接报engine node16不满足依赖装不上。启动项目时抛SyntaxError: Unexpected token ?这类错误因为新代码里用到了空值合并运算符、可选链等 ES2020 语法老版本的 V8 引擎根本不认识。像 Vite、现代版 webpack、esbuild 这类构建工具会直接拒绝启动提示当前 Node 版本太低。老项目里依赖node-sass的在安装阶段就容易在 node-gyp 编译环节崩掉报错信息里全是gyp ERR一类的红色文字。我自己就遇到过一台 Ubuntu 18 服务器上还跑着 Node 8接手一个用 Vite 写的内部工具时npm run dev刚敲下去就报错查了半天才发现是 Node 版本问题。所以这个“旧”不是小事是直接影响能不能干活的问题。1.3 高版本到底该装到多高当前 Node.js 的发布节奏是每年一个大版本偶数为 LTS长期支持版本奇数为尝鲜版本。对绝大多数开发者来说不要追奇数版本直接用最新的 LTS 就好。比如现在比较稳妥的选择是 Node 18 或 Node 20Node 20 的 LTS 周期更长生态兼容性也更好。至于 Node 16已经开始进入维护尾声新项目不太建议再用了。装到高版本之后npm也会自动跟着升级到一个新版本不需要单独处理。后面我给的命令基本都是安装 Node 20 的版本如果你想装 18把命令里的20换成18就行思路完全一样。2. 安装高版本 Node.js 的四条路线直接说结论2.1 方案对照表在动手之前先把四条主要路线拉出来对比一下方便你根据场景选方案安装方式版本新旧多版本切换适用场景官方 apt 源apt install nodejs老旧8.x/10.x不支持系统自带、不搞前端开发NodeSource 仓库添加 apt 源后安装较新可指定 18/20/21/22弱切换大版本要换源生产服务器、习惯用 apt 管理nvm脚本安装按用户管理所有历史版本都能装强随时切换本地开发、需要多版本共存官方二进制包下载 tar.xz 解压配置 PATH指定版本不支持离线环境、不想用脚本2.2 为什么我优先推荐 nvmnvm 的全称是 Node Version Manager它本身是一段 shell 脚本装好之后放在~/.nvm目录。它最大的价值是“按用户隔离”和“版本随时切换”安装新版本完全不需要sudo也不会污染系统目录。它的原理其实很简单nvm 下载官方预编译好的二进制包到自己的目录然后通过修改当前 shell 的PATH环境变量把指定版本的bin目录排到最前面。也就是说你输入node的时候系统找到的是~/.nvm/versions/node/v20.x.x/bin/node而不是/usr/bin/node。这套设计带来的好处是卸载时直接删掉~/.nvm就干干净净不会有系统残留。而且你有多个项目分别要求 Node 14、Node 16、Node 18 的时候nvm use 16一下就能切换不需要重装系统也不需要折腾软链。2.3 NodeSource 仓库适合什么样的场景NodeSource 是做 Node.js 企业级服务的一家公司官方维护了一套 Debian/Ubuntu 的 apt 仓库。它把一个安装脚本放到官网上执行之后会把对应版本的 Node.js 编译好的二进制包加入 apt 源。这样你可以用apt install nodejs装上一个比较新的版本后续升级也走apt upgrade跟系统里其他软件的管理方式一致。这种方案在服务器上很讨喜尤其适合那些已经习惯了用 apt 管理软件的运维同学。但它的缺点也明显想从 Node 18 切到 Node 20不是简单执行apt upgrade就能解决的需要重新执行setup_20.x脚本替换源地址然后才能升级。所以它更适合“一台机器固定一个版本”的生产环境。此外npm 全局包会装到/usr/lib/node_modules这种系统目录权限问题会比 nvm 方案多不少。2.4 源码编译为什么不推荐网上有些教程会让你下载 Node.js 源码然后执行./configure make -j4 make install我劝你不要在一台普通机器上这么干。Node.js 源码编译耗时非常长动辄一两个小时过程中还经常遇到机器内存不足导致编译崩溃的问题。对于绝大多数使用场景来说直接使用官方预编译二进制包是性价比最高的选择源码编译只适合极少数需要修改 Node 内部实现或者定制特殊编译选项的场合。3. nvm 路线从零开始装 Node 20 的完整记录3.1 安装前先把旧环境清干净如果你这台机器以前用apt装过nodejs或者手动解压过二进制包建议先清掉。不清理的话后面会出现which node指向/usr/bin/node但 nvm 自己也有一份 node两边版本不一致特别容易把人搞懵。先执行sudo apt remove --purge nodejs npm sudo apt autoremove如果你之前手动解压过官方二进制包到/usr/local还需要手动删掉这些目录sudo rm -rf /usr/local/bin/node /usr/local/bin/npm sudo rm -rf /usr/local/lib/node_modules如果只是残留了~/.npm缓存也可以顺手清了避免之后全局安装包时出问题。3.2 实际安装 nvm 的完整命令nvm 官方提供一行安装命令直接在终端执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash这条命令会做三件事把 nvm 仓库 clone 到~/.nvm在~/.bashrc里追加几行环境变量配置然后新开终端后自动生效。执行完会看到类似下面的输出 Downloading nvm as a script to /root/.nvm Appending nvm source string to /root/.bashrc Close and reopen your terminal to start using nvm验证是否装好可以先手动加载一下export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh nvm --version如果看到0.39.7之类的版本号说明 nvm 已经能用了。这里有个小提醒有的服务器网络访问 GitHub 不稳定curl可能超时。这种情况多试几次或者换用后面的 NodeSource 方案。不要因此去折腾一些来路不明的第三方脚本安全第一。3.3 列出并安装指定版本的 Node.jsnvm 装好之后先看看远端有哪些版本可用nvm ls-remote输出会非常长从老版本一路列到最新版。建议不要直接挑最新的午夜版挑 LTS 版本。比如要装 Node 20直接执行nvm install 20nvm 会自动去官方服务器下载 linux-x64 的预编译包解压到~/.nvm/versions/node/v20.x.x/下。整个过程很快大概几十秒。装完之后执行nvm use 20 node -v npm -v就会看到类似v20.12.4和10.9.2的输出。注意nvm use只会影响当前终端窗口新开的终端默认还是找不到 nvm 的 Node。所以对某个固定的工作目录我建议设置一个默认版本nvm alias default 20设置之后新开终端会自动加载默认版本的 node。用nvm ls可以查看本机装了多少个版本以及当前正在使用哪个。3.4 服务器上非交互 shell 的坑nvm 默认只在交互式 shell 里生效因为~/.bashrc在非交互 shell 里不会自动加载。如果你在服务器上跑 cron 任务或者用 systemd 服务来启动 Node 项目会发现在服务里找不到node命令因为服务环境的PATH是干净的。解决方式是在 systemd 的 unit 文件里直接指定 Node 的绝对路径which node拿到类似/root/.nvm/versions/node/v20.12.4/bin/node的路径后在服务配置里用这个绝对路径启动脚本。或者更省事的办法在 systemd unit 里加一行EnvironmentPATH/root/.nvm/versions/node/v20.12.4/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin这个坑我在生产环境踩过项目手动跑没问题一旦交给 systemd 就报node: command not found花了不少时间才排查到是 PATH 的问题。4. NodeSource 仓库方式apt 党的高版本方案4.1 NodeSource 的原理与准备工作NodeSource 的安装脚本做两件事把官方签名密钥加入系统信任列表然后往/etc/apt/sources.list.d/下写入一个指向 NodeSource 仓库的源文件。之后apt就能从那个仓库里拉取对应版本的 Node.js 包。所以执行脚本之后用的是你熟悉的 apt 安装流程。执行脚本前同样建议先移除系统自带的旧版sudo apt remove --purge nodejs npm然后为当前 Ubuntu 18 版本安装依赖主要是后面可能用到本地编译工具sudo apt update sudo apt install -y ca-certificates curl gnupg4.2 用 NodeSource 脚本安装 Node 20NodeSource 官方脚本长这样curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs注意两个细节第一-E参数是为了把当前用户的环境变量保留给 sudo 下的 bash防止脚本执行过程中丢失代理等环境配置第二安装的是nodejs这个包它本身已经包含了npm。装完验证node -v npm -v这样装出来的 Node.js 是 NodeSource 自己制作好的二进制包版本质量是有保障的。如果你想装 Node 18只需要把 URL 里的setup_20.x改成setup_18.x。4.3 替换 npm 默认源加速依赖安装Ubuntu 18 服务器如果放在国内npm 默认源下载依赖会比较慢建议先换成国内镜像源。这一步纯粹是网络优化不影响 Node.js 本身npm config set registry https://registry.npmmirror.com换完之后执行npm config get registry确认一下。不推荐直接用cnpm替代npm因为 cnpm 的包结构和官方 npm 不完全一致某些包的 postinstall 脚本会跳过可能导致装完的项目跑不起来。用官方 npm 配镜像源是最稳的做法。4.4 用 apt 升级 Node.js 版本NodeSource 仓库方案升级小版本很简单sudo apt update sudo apt install nodejs如果想把大版本从 18 升级到 20不能直接apt upgrade要先重新执行对应版本的 setup 脚本再apt upgrade。这个过程其实是一次“换源”先执行setup_20.x覆盖原来的源文件再运行sudo apt dist-upgrade这样才会把 Node.js 大版本提上去。切记不要手动去/usr/bin/node做软链接操作容易把系统和 apt 的管理信息搞乱。4.5 卸载 NodeSource 版 Node如果后来想切换成 nvm 方案把 NodeSource 的痕迹清干净sudo apt remove --purge nodejs npm sudo rm -f /etc/apt/sources.list.d/nodesource.list /etc/apt/keyrings/nodesource.gpg sudo apt update5. 安装完之后必踩的坑提前排掉5.1which node指向旧版本PATH 顺序问题无论用哪种方式安装都可能出现终端里node -v是新版本但某些脚本里面调用到的却是旧版本的情况。原因基本都出在PATH的优先级上。可以用这两条命令检查which -a node type -a nodewhich -a node会把系统里所有叫 node 的可执行文件路径都列出来从上到下就是PATH的查找顺序。如果/usr/bin/node排在~/.nvm/.../node前面说明 nvm 的脚本没有被正确加载。这时重新执行source ~/.bashrc hash -rhash -r是用来清空 shell 的命令哈希缓存避免 shell 记住旧路径。这是一个很隐蔽的坑改完 PATH 不刷新哈希可能跑的还是旧命令。5.2 sudo 会悄悄切走你的 Nodenvm 用户最容易踩nvm 让普通用户安装 Node 不需要 sudo但同时也带来一个副作用sudo npm install -g时sudo 会用 root 的环境变量跑命令结果调用的是/usr/bin/node而不是你 nvm 里的 Node。我在项目部署时犯过这个错npm install -g pm2成功但 pm2 却连接到了系统老 Node 的模块目录版本错乱到让人怀疑人生。现在的习惯是用 nvm 管理 Node 时不要给任何npm命令加 sudo。nvm 安装的 Node全局包默认放在~/.nvm/versions/node/v20.x.x/lib/node_modules/普通用户权限完全够用。如果某个包必须要 root 权限通常说明这个包的设计有问题要么不用要么改用 NodeSource 方案。5.3 node-sass 编译失败该换 sass 了Node 16 以上的版本对 node-sass 的兼容性非常差因为 node-sass 底层的 LibSass 以及 node-gyp 编译链跟不上新 Node 的脚步。表现就是npm install时一大段gyp ERR报错。解决思路不是疯狂重编而是把依赖从node-sass替换成sass也就是 Dart Sass 的 npm 包。它在性能上基本持平安装也不需要本地编译。如果你维护的是一个特别老的、硬编码依赖 node-sass 的项目临时方案是把它降到 Node 14 下跑但这治标不治本。长期来看替换依赖是唯一干净的出路。5.4 webpack 4 在 Node 17 上报 OpenSSL 错误另一个高频坑是项目用的是 webpack 4Node 版本升级到 17 以上后一跑构建就报Error: error:0308010C:digital envelope routines::unsupported原因是 Node 17 之后 OpenSSL 升级到 3.0webpack 4 还在使用旧版 OpenSSL API。临时解决办法是设置环境变量export NODE_OPTIONS--openssl-legacy-provider但这只是绕路最终建议还是把 webpack 升到 5。因为 webpack 5 对现代 Node 的支持更稳构建速度也更快。5.5 版本切换后的全局包丢失最后一个坑是 nvm 特有的全局 npm 包是按 Node 版本隔离的。你切到 Node 18就看不到 Node 20 环境下npm install -g装的包。这是设计使然不是 bug。我换版本之前一般会先导出全局包清单npm list -g --depth0然后在新版本里按需重装。如果某个全局包是项目运行必须的更推荐做成项目的 devDependencies而不是全局安装这样跟 Node 版本解耦换环境也不慌。这套流程走下来Ubuntu 18 上跑现代前端项目的问题基本都能解决。我自己现在的习惯是开发机用 nvm不同项目切不同 Node 版本生产服务器用 NodeSource一台机器固定一个版本配合 systemd 管理服务稳得很。装完系统级依赖之后记得快速跑一遍node -v、npm -v、npm config get registry三个命令把环境底数确认清楚后面能省掉很多莫名其妙的排错时间。
