macOS Monterey下Node 18.0.0运行Gatsby构建遇原生构建缺失错误

错误原因解析 #

这个错误是因为项目中某个native依赖包没有提供针对Node 18.0.0（ABI版本108）的arm64架构预编译二进制文件。Node 17.9.1的ABI版本为102，对应的预编译包存在，因此能正常运行。

临时修复：让Gatsby 4在Node 18下正常运行 #

方案1：清理依赖缓存并重装 #

• 删除本地依赖和锁文件：

  rm -rf node_modules
  rm package-lock.json
  

• 清空npm缓存：

  npm cache clean --force
  

• 重新安装依赖：

  npm install
  

• 尝试重新构建：

  gatsby build
  

方案2：强制重新编译Native模块 #

如果依赖需要本地编译，旧的编译缓存是针对旧Node版本的，执行以下操作：

• 全局安装node-gyp（用于编译native模块）：

  npm install -g node-gyp
  

• 重新编译所有native依赖：

  npm rebuild
  

• 再次运行构建命令。

方案3：切换Node 18为x64架构（M1 Mac专属） #

部分依赖暂未适配arm64，可以安装x64版本的Node 18：

• 卸载当前arm64版本的Node 18：

  nvm uninstall 18.0.0
  

• 以x64架构安装Node 18：

  arch -x86_64 nvm install 18.0.0
  

• 切换到该版本：

  nvm use 18.0.0
  

• 重装依赖后尝试构建。

长期解决方案：顺利升级到Gatsby 5 #

Gatsby 5要求Node ≥18.0.0，建议使用更稳定的LTS版本（如18.17.0），步骤如下：

1. 升级Node到18.x LTS：

   nvm install 18.17.0
   nvm use 18.17.0
   

   更新.nvmrc文件内容为18.17.0，确保后续默认使用该版本。

2. 升级Gatsby及相关依赖：

   • 升级Gatsby核心包：

     npm install gatsby@latest
     

   • 检查并升级其他Gatsby插件/数据源：

     npm outdated
     

     把所有gatsby-plugin-*、gatsby-source-*等依赖升级到兼容Gatsby 5的版本。

3. 清理Gatsby缓存并验证：

   gatsby clean
   gatsby develop
   

   确认开发服务器正常运行后，执行构建：

   gatsby build
   

内容的提问来源于stack exchange，提问作者Dan Jackson