执行npm install时报sodium@3.0.2 preinstall脚本失败如何解决？

sodium@3.0.2属于需要本地编译的原生Node扩展库，preinstall阶段执行失败的常见原因如下：

• 系统缺少原生库编译所需的构建工具链：Windows环境缺少Visual Studio C++构建组件，macOS缺少Xcode命令行工具，Linux缺少基础编译套件和Python环境
• Node.js版本不兼容：sodium@3.0.2发布时间较早，仅适配Node.js 12.x~14.x LTS版本，使用16.x及以上版本会触发预安装脚本执行异常
• npm本地缓存损坏：之前的安装残留文件干扰本次预安装脚本的执行逻辑
• 目录权限不足：执行npm install的用户没有项目目录的写入权限，预安装脚本无法生成临时编译文件

按以下顺序逐一验证处理：

• 补齐系统构建依赖
  • Windows：下载安装Visual Studio Build Tools，安装时勾选「桌面开发使用C++」工作负载，同时安装Python 3.8及以上版本
  • macOS：终端执行xcode-select --install按照指引完成命令行工具安装
  • Debian/Ubuntu系列Linux：终端执行sudo apt update && sudo apt install build-essential python3
  • CentOS/RHEL系列Linux：终端执行sudo yum groupinstall "Development Tools" && sudo yum install python3
• 兼容版本适配
  如果当前使用的Node.js版本高于14.x，可以使用nvm切换到14.x LTS版本重新执行安装；也可以直接替换项目依赖为纯JS实现的libsodium-wrappers，功能和sodium完全一致，无需本地编译，兼容性更强
• 清理缓存重试
  终端依次执行以下命令：

  npm cache clean --force
  rm -rf node_modules package-lock.json
  npm install
  

• 修复目录权限
  不要使用sudo/root权限执行npm install，如果是目录权限问题，执行sudo chown -R $USER:$GROUP 你的项目目录路径为当前用户授权后重试。

内容的提问来源于stack exchange，提问作者yonatan abergel