Node.js 版本升级与依赖迁移：从 18 到 20/22 的安全路径

升级的评估：为什么升、什么时候升

升级的驱动因素：安全补丁（旧 LTS 停止安全维护）、依赖要求（新版本的依赖包要求更高 Node）、性能（每代 LTS 的运行时有可观提升）。时机选择：LTS 的首个小版本发布后 2~3 个月（让社区把早期问题踩完），且避开业务高峰。

升级步骤（pm2 环境）

# 1. 用 nvm 安装新 LTS（不动系统 Node）
nvm install 22 && nvm use 22
# 2. 重装依赖（原生模块重编译）
rm -rf node_modules && pnpm install
# 3. 验证
node -v && npm rebuild
# 4. pm2 指向新 node（更新 pm2 的环境）
pm2 update
# 5. 重启全部服务并验证
pm2 restart all && pm2 logs --lines 20

注意 pm2 的坑：pm2 自身记录的 Node 路径是启动时的——升级后 pm2 update 或删除并重建进程列表，否则 pm2 还在用旧 Node 跑服务。

依赖兼容性排查

pnpm install 后跑 pnpm run typecheck && pnpm run build——两层验证（类型+构建）。原生模块报错的处理：按包查支持矩阵（绝大多数主流包已支持新 LTS），个别未支持的锁旧版本等待上游更新。升级前在测试环境/本地完整走一遍，不要直接在服务器上试。

回滚方案

nvm 的多版本共存让回滚极简：nvm use 20 && pm2 update && pm2 restart all——回到旧版本。升级前 pm2 save 保存的进程清单配合使用。回滚演练不用单独做：升级当天保留旧版本环境就是回滚方案本身。

与逐日 AI 升级的关系

Node 升级与逐日 AI 版本升级是两件事，分开做、不要同时做（同时升级两个变量，出问题无法归因）。顺序：先 Node（跑一次完整验证），再应用版本（又跑一次完整验证）。