Gatsby初始化后无法添加插件 出现npm ERESOLVE依赖冲突报错

这是npm 7及以上版本默认开启严格peer依赖校验触发的版本冲突：你通过gatsby create初始化的是Gatsby 4.17.0版本项目，默认预装了React 18.1.0，但项目模板自带的@mdx-js/react@1.6.22、gatsby-plugin-mdx@3.17.0最高仅支持React 16/17版本，没有做React 18的兼容声明，所以后续安装任何插件触发依赖树遍历校验时，都会直接抛出ERESOLVE依赖解析失败错误。

按优先级从高到低可选以下方案：

• 方案1：对齐依赖兼容版本（生产环境推荐，无运行时风险）
  把React版本降到现有MDX依赖支持的17.x版本，从根源解决冲突：

  1. 打开项目根目录的package.json，找到dependencies配置块下的react、react-dom字段，将版本号修改为"^17.0.2"
  2. 清理旧的依赖缓存和锁文件，Mac/Linux执行以下命令：

     rm -rf node_modules package-lock.json
     

     Windows用户可以直接手动删除项目下的node_modules文件夹和package-lock.json文件
  3. 重新执行npm install安装全量依赖，后续安装任意官方Gatsby插件都不会再触发该报错。

• 方案2：升级MDX依赖适配React 18（需要用React18特性时选这个）
  如果要保留React 18的新特性，把旧版MDX相关依赖升级到适配React18的版本即可：

  1. 先卸载不兼容的旧版MDX包：

     npm uninstall gatsby-plugin-mdx @mdx-js/react @mdx-js/mdx
     

  2. 安装适配Gatsby 4 + React 18的MDX v2版本：

     npm install @mdx-js/react@^2.1.0 gatsby-plugin-mdx@^4.0.0
     

  3. 安装完成后正常添加其他插件即可。

• 方案3：临时跳过依赖校验（仅本地快速验证用，禁止生产环境使用）
  如果只是临时测试功能不想调整依赖版本，可以在所有npm安装命令后加上--legacy-peer-deps参数，让npm跳过peer依赖版本校验强制安装：

  # 示例：安装插件时附加参数
  npm install gatsby-plugin-xxx --legacy-peer-deps
  

  注意：该方案只是绕过安装阶段的校验，实际运行时因为版本不兼容，大概率会出现MDX渲染报错、页面白屏、控制台抛错等问题，绝对不要在生产构建时用这个参数。

内容的提问来源于stack exchange，提问作者Giuseppe Marchi