Netlify部署Gatsby项目报npm ERR! ERESOLVE依赖冲突错误

构建失败发生在依赖安装阶段，根本没走到Gatsby构建流程，所以你之前执行gatsby clean、重装本地node_modules这类清构建缓存的操作完全不生效。
核心冲突非常明确：

1. Netlify构建环境用的是npm v8.11.0，这个版本默认开启严格对等依赖（peer dependency）校验，只要依赖树里有对等依赖不匹配的情况，就会直接抛出ERESOLVE错误终止安装。
2. 你的项目当前使用React 17.0.2版本，但引入的react-owl-carousel3@2.2.5包只声明支持React 0.14、15、16三个大版本，和当前React版本的对等依赖要求不匹配。
3. 本地运行正常的原因：要么你本地npm版本低于v7（旧版npm遇到对等依赖冲突只会打警告，不会终止安装），要么你本地安装依赖时手动加了--legacy-peer-deps参数，但这个配置没有同步到Netlify的构建流程里，Netlify默认执行裸npm install命令，直接触发冲突报错。

按优先级从高到低选择即可：

• 最快生效方案：统一npm依赖解析配置
  在项目根目录新建.npmrc文件，写入以下配置后提交到Git仓库：

  legacy-peer-deps=true
  

  这个配置会让所有环境（本地、Netlify）执行npm安装时，默认使用旧版对等依赖解析逻辑，跳过严格校验，直接绕过当前的冲突报错。
  如果不想改项目内的配置文件，也可以直接在Netlify站点后台的「构建与部署-环境变量」配置项中，新增一个key为NPM_FLAGS、value为--legacy-peer-deps的环境变量，Netlify执行npm安装时会自动拼接这个参数。
• 长期稳妥方案：替换无人维护的冲突依赖
  react-owl-carousel3已经长期停止更新，连React 17的兼容声明都没有，后续升级React 18、或者Gatsby大版本时还会触发同类问题。建议替换为仍在维护的轮播组件，比如Swiper React、react-responsive-carousel等，这类组件原生适配React 17/18，不会存在对等依赖冲突问题。
• 兜底校验操作
  提交代码前，先在本地删除node_modules目录和package-lock.json文件，重新执行npm install确认依赖安装无报错，再把新生成的lock文件提交到仓库，避免本地和线上依赖版本不一致触发其他构建问题。

内容的提问来源于stack exchange，提问作者Scott Montford