Mac与Linux环境下Sharp模块安装失败问题求助

通用前置清理操作 #

先彻底清理现有依赖和缓存，避免残留问题：

• 删除本地依赖目录：rm -rf node_modules
• 删除锁文件：rm package-lock.json yarn.lock
• 清理npm缓存：npm cache clean --force

Mac 平台专属修复步骤 #

1. 确保Xcode命令行工具正常：
   • 执行xcode-select --install安装工具，若已安装则重置：sudo xcode-select --reset
2. 安装Sharp依赖的底层VIPS库：
   • 通过Homebrew安装：brew install vips
3. 重新安装Sharp，匹配本地架构：
   • Intel芯片：npm install --platform=darwin --arch=x64 sharp
   • M系列芯片：npm install --platform=darwin --arch=arm64 sharp
4. 若仍失败，强制从源码编译：
   • npm install sharp --build-from-source

Linux 平台专属修复步骤 #

1. 安装系统级依赖（根据发行版选择）：
   • Debian/Ubuntu：sudo apt-get update && sudo apt-get install libvips-dev gcc g++ make
   • RHEL/CentOS：sudo yum install vips-devel gcc-c++ make
2. 重新安装Sharp：
   • npm install sharp
3. 若预编译包下载失败，强制源码编译：
   • npm install sharp --build-from-source

额外排查要点 #

• 确认终端架构：执行uname -m（Mac）或arch（Linux），确保安装命令的--arch参数与实际架构一致
• 检查Node.js版本：Sharp要求Node.js >=16.13.0，建议使用LTS版本（18/20）
• 网络问题处理：若预编译包下载超时，切换国内镜像：
  • npm config set sharp_binary_host "https://npmmirror.com/mirrors/sharp"
  • 执行完后重新安装Sharp

内容的提问来源于stack exchange，提问作者Pedro Rabbi