Gatsby项目安装MDX依赖遇依赖树解析失败，求助解决办法

问题根源 #

npm v7及以上版本对peer依赖的校验规则更严格，Gatsby MDX v1的依赖和你项目里现有包的peer依赖版本不兼容，导致默认安装命令触发依赖树错误。用--legacy-peer-deps能临时跳过校验完成安装，但后续执行npm i时，npm会重新校验peer依赖，所以问题反复出现。

彻底解决方法 #

方法一：全局设置peer依赖兼容策略 #

直接修改项目根目录的package.json，添加配置让所有npm命令默认使用legacy-peer-deps模式：

{
  "name": "你的Gatsby项目名称",
  // 保留原有字段...
  "npmConfig": {
    "legacy-peer-deps": true
  }
}

修改后再执行npm i就不会再触发依赖树报错。

方法二：升级到MDX v2（推荐） #

MDX v1版本较旧，依赖兼容性问题多，Gatsby官方已经全面支持MDX v2，直接安装v2版本的依赖：

npm install gatsby-plugin-mdx @mdx-js/mdx@v2 @mdx-js/react@v2

注意：升级后需要同步调整gatsby-config.js里的插件配置，适配v2的新参数（比如插件选项结构有变化，对照官方文档调整即可）。

方法三：清理缓存重装 #

如果上面的方法没用，试试彻底清理依赖缓存后重新安装：

• 删除node_modules文件夹：rm -rf node_modules（Windows系统用rmdir /s node_modules）
• 删除package-lock.json文件：rm package-lock.json（Windows系统用del package-lock.json）
• 用兼容模式重装：npm install --legacy-peer-deps

验证 #

安装完成后，执行gatsby develop启动项目，检查MDX文件能否正常加载，确认没有依赖相关的报错。

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