更新gatsby-cli后npm install突然失效的故障排查求助

这一连串的问题确实有点棘手——误操作搞乱了全局Node环境，再叠加M1芯片对原生编译类依赖的兼容性问题，才导致各种报错扎堆出现。别着急，咱们一步步捋清楚解决：

一、先彻底清理并重建全局Node环境 #

之前的误操作大概率让全局npm残留了一堆混乱文件，先把环境拉回正轨：

1. 卸载现有Node：

   brew uninstall node
   

2. 手动删除全局依赖残留目录：
   • ~/.npm
   • ~/.node_modules
   • /usr/local/lib/node_modules
   • 如果用过nvm，也删掉~/.nvm
3. 用nvm重新安装适配M1的Node（避免权限和版本兼容坑）：
   • 先装nvm：

     brew install nvm
     

   • 按照brew提示把nvm的环境变量配置到~/.zshrc或~/.bashrc里
   • 安装LTS版本的Node（比如18.x或20.x，Gatsby 3+对Node版本有要求）：

     nvm install --lts
     nvm use --lts
     

4. 重新安装全局gatsby-cli：

   npm install -g gatsby-cli
   

二、清理项目依赖并重置安装 #

针对单个Gatsby项目，彻底清空旧的依赖文件：

1. 进入项目根目录，删除依赖相关文件：

   rm -rf node_modules package-lock.json yarn.lock
   

2. 清除npm缓存：

   npm cache clean --force
   

三、解决gatsby-plugin-sharp安装问题 #

M1上sharp依赖的vips库需要手动安装：

1. 通过brew装vips：

   brew install vips
   

2. 指定M1平台参数安装sharp：

   npm install sharp --arch=arm64 --platform=darwin
   

3. 再安装gatsby-plugin-sharp（注意版本要和你的Gatsby版本匹配，比如Gatsby 3对应gatsby-plugin-sharp@3.x）：

   npm install gatsby-plugin-sharp
   

四、替换node-sass为sass（dart-sass） #

node-sass已经停止维护，对M1兼容性极差，直接换官方推荐的替代方案：

1. 卸载node-sass：

   npm uninstall node-sass
   

2. 安装sass：

   npm install sass
   

3. 项目里的代码基本不用改——sass是node-sass的无缝替代，样式编译逻辑完全兼容

五、最后尝试启动开发服务器 #

完成以上步骤后，在项目根目录执行：

npm install
gatsby develop

如果还是有报错，可以试试用Rosetta 2运行终端当临时方案：右键终端图标→「获取信息」→勾选「使用Rosetta打开」，再重新执行安装和启动命令，能解决部分原生编译依赖的兼容性问题。

内容的提问来源于stack exchange，提问作者Fin Moorhouse