---

一次 openEuler ARM64 服务器上的升级复盘：问题不在下载，也不在 npm，而在安装位置与执行路径不一致。

升级工具报告成功，node -v 却仍显示旧版本。这不是矛盾，而是两个不同问题的答案：文件装到了哪里，Shell 又从哪里找到文件。

一、从报错到根因

现场环境是 openEuler 24.03（aarch64），Node.js 为 v22.11.0，npm 为 11.5.2。安装 GitNexus RC 版本时出现警告：

required: { node: '^22.18.0 || >=24.11.0' }
current:  { node: 'v22.11.0', npm: '11.5.2' }

EBADENGINE 表示运行时版本不符合包声明的要求；它是兼容性警告，不等于 npm 自身需要升级，也不必然意味着安装失败。既然希望保持 Node.js 22 主版本，目标定为 v22.23.1 即可。

随后执行：

npm install -g n
n --preserve 22.23.1

日志给出了决定性证据：

installed : v22.23.1 to /usr/local/bin/node
active    : v22.11.0 at /root/.local/nodejs22/bin/node

新版已写入 /usr/local/bin/node，但当前 Shell 优先找到 /root/.local/nodejs22/bin/node。安装成功，不代表正在使用。

这里有三个互不等价的概念：

概念	决定什么	本次实例
版本约束	应该安装哪个版本	22.23.1
安装前缀 N_PREFIX	n 把文件写到哪里	默认 /usr/local
环境变量 PATH	Shell 优先运行哪个文件	/root/.local/nodejs22/bin/node

n 是 Node.js 版本管理工具，npm 是 JavaScript 包管理工具，二者也不等于操作系统的 RPM/DNF。即使没有可用的系统包管理器，也可以使用 n 或官方二进制包；关键是先确定原有安装的归属。

二、正确的处理顺序

目标不是“让某一次 node -v 变对”，而是在原目录完成升级，不改 PATH、不破坏 npm，并且可以回退。

1. 先定位，不急于安装

type -a node npm n
readlink -f "$(command -v node)"
readlink -f "$(command -v npm)"
npm config get prefix
npm root -g
uname -m

确认当前 node 确实来自 /root/.local/nodejs22，并检查其是否为指向其他位置的符号链接。如有 RPM 管理记录，应优先遵循原安装方式；未知归属的目录不应直接覆盖。正在承载业务的服务器，还应安排维护窗口并明确重启、验收责任。

2. 备份整个安装前缀

BACKUP="/root/nodejs22-before-22.23.1-$(date +%Y%m%d%H%M%S).tar.gz"
tar -C /root/.local -czf "$BACKUP" nodejs22
printf 'Backup: %s\n' "$BACKUP"

备份整个目录，而非只复制 node：npm、全局包、头文件和命令入口可能也位于其中。应确认归档成功、磁盘空间充足，并保存备份路径。

3. 指定目标目录，精确升级

N_PREFIX=/root/.local/nodejs22 n --preserve 22.23.1
hash -r

/root/.local/nodejs22/bin/node -v
/root/.local/nodejs22/bin/npm -v
node -v
npm -v

N_PREFIX 把安装目标固定为原目录；--preserve 使 n 不替换目标目录内现有的 npm、npx 和 Corepack。它不会从别处“搬来”当前 npm。因此，只有原 npm 11.5.2 确实装在这个前缀内，才可预期继续使用该版本。

验收不能只看版本号，还要核对路径：

command -v node
command -v npm
npm config get prefix
npm root -g
node -p 'process.execPath'

本例的预期结果是 node 和 process.execPath 均指向 /root/.local/nodejs22/bin/node，版本为 v22.23.1；npm 应来自预期安装环境。确认全局安装前缀后，再执行：

npm install -g gitnexus@rc

若 Node.js 用于 systemd 服务，还须检查服务的 ExecStart 与实际运行环境，并在受控重启后验收；交互式 Shell 的 PATH 不会自动替服务生效。对高可用生产系统，更适合采用独立版本目录与受控切换，而不是直接覆盖正在使用的安装目录。

4. 最后清理误装的副本

确认目标目录升级成功后，再检查 /usr/local：

ls -l /usr/local/bin/{node,npm,npx,corepack} 2>/dev/null || true
ls -ld /usr/local/include/node /usr/local/lib/node_modules/{npm,corepack} 2>/dev/null || true

不能未经核实就执行 N_PREFIX=/usr/local n uninstall。 查看 n 的实现可知，该命令不仅删除 node，还会删除该前缀下的 npm、npx、corepack 及相关文件。此前使用了 --preserve，这些文件未必是本次升级创建的；盲目卸载可能误伤原有软件。

只有确认这些文件属于可整体撤销的 n 安装后，才执行：

N_PREFIX=/usr/local n uninstall
N_PREFIX=/usr/local n rm 22.23.1

第一条清理该前缀的活动安装；第二条清理 n 在该前缀下缓存的指定版本。卸载与删缓存是两件事。 如果文件归属无法确认，宁可暂不清理，也不要对整个 /usr/local/bin 或 /usr/local/lib/node_modules 执行递归删除。

三、回滚不应靠记忆

若升级后出现兼容性问题，使用第二步保存的归档恢复整个前缀；以下 BACKUP 须替换为实际备份文件路径：

BACKUP=/root/nodejs22-before-22.23.1-YYYYMMDDHHMMSS.tar.gz
mv /root/.local/nodejs22 "/root/.local/nodejs22.failed.$(date +%Y%m%d%H%M%S)"
tar -C /root/.local -xzf "$BACKUP"
hash -r
/root/.local/nodejs22/bin/node -v

移动而非直接覆盖现有目录，可以避免升级后新增文件混入旧版本。恢复后还应复测 npm、业务命令和相关服务。

四、这次复盘最值得保留的原则

先前的处理建议有四处应当纠正：未经必要性评估就建议跨主版本升级；未确认安装前缀就运行 n，造成重复安装；用修改 PATH 代替原目录升级，只绕过了表象；过早建议 n uninstall，忽视了共享目录内其他文件的归属风险。

一套可靠的升级操作，顺序应当固定：识别约束 → 查清归属 → 备份 → 定位安装 → 双重验收（版本与路径）→ 验证业务 → 清理副本。升级前先定义“成功”的判据，往往比选择哪个安装工具更重要。

这次故障只差一个目录，却揭示了一条通用工程规律：软件的安装状态、解析路径与实际运行状态必须分别验证。

参考资料

• Node.js v22.23.1 官方发布归档：版本、架构与随附 npm 信息。
• n 官方文档：N_PREFIX、--preserve、版本缓存和卸载语义。
• n 卸载逻辑源码：可核查 uninstall_installed 实际删除的路径。
• GNU Bash 参考手册：PATH 查找与 hash -r 的行为。