Gatsby站点安装配置MDX转换插件及依赖报错问题求助

本次依赖冲突直接修复方案 #

本次报错核心原因是安装的@mdx-js/react@v1最高小版本仅支持 React 16/17，与项目内置的 React 18 版本不兼容；后续出现的 Parcel 模块缺失报错，是使用--legacy-peer-deps强行安装不兼容依赖导致的残缺依赖问题，按以下步骤操作即可修复：

• 先清理之前安装损坏的依赖文件：

rm -rf node_modules package-lock.json

• 安装适配 React 18 的 MDX 生态对应版本：

npm install gatsby-plugin-mdx @mdx-js/react@^2.3.0 @mdx-js/mdx@^2.3.0

• 在gatsby-config.js中补全MDX插件的基础配置后，重新执行gatsby develop即可正常启动。

如果必须使用v1版本MDX，直接将项目内React版本降到17.0.2即可兼容，执行npm install react@17.0.2 react-dom@17.0.2后再按原教程步骤安装插件即可，但该方案会损失React 18带来的Gatsby构建性能提升，不推荐使用。

npm 依赖树冲突通用排查思路 #

• 先读报错核心字段：报错中Found字段会标注当前项目中已安装的冲突包版本，Could not resolve dependency字段会标注待安装包要求的依赖版本区间，直接就能定位版本不匹配的核心矛盾，本次报错中明确标注项目已装React 18.2.0，而@mdx-js/react@1.6.22仅支持React 16/17，定位冲突仅需10秒。
• 版本二选一调整：要么升级要求低版本的依赖包到适配当前核心依赖的版本（比如本次将MDX相关包升到v2适配React 18），要么将项目核心依赖降到待安装包要求的版本区间，两种方案选一种即可解决问题。
• 禁止优先使用--legacy-peer-deps/--force参数跳过依赖校验：这类参数本质是强行安装版本不兼容的包，不会解决实际兼容问题，只会把安装阶段的报错延后到编译、运行阶段，出现类似本次Parcel模块缺失的无直接关联的奇怪报错。
• 嵌套依赖冲突用命令溯源：如果是多层依赖传递导致的冲突，执行npm ls 冲突包名即可打印完整依赖引用链路，找到哪个上层依赖引入了冲突版本，对应调整上层依赖版本即可。

npm 依赖漏洞警告处理规则 #

• 风险等级判定：npm漏洞按风险从高到低分为critical（严重）、high（高危）、moderate（中危）、low（低危）四级，分级依据是漏洞利用难度、影响范围：可远程执行代码、权限绕过类的漏洞为严重/高危，仅在特殊构造场景下才会触发、影响范围极小的为中/低危。
• 处理逻辑：
  • 先执行npm audit查看漏洞详情，确认漏洞所属依赖是生产依赖还是开发依赖
  • 生产依赖（上线后会运行在用户端的代码）中的严重、高危漏洞必须处理，优先升级对应依赖到官方发布的修复版本
  • 开发依赖（仅本地构建、调试使用的工具链）中的高危漏洞、所有等级的中低危漏洞按需处理即可：如果漏洞触发场景完全不会在你的使用流程中出现（比如漏洞需要处理恶意构造的第三方用户输入才会触发，而你只是本地写个人博客，所有内容都是自己生成），完全不需要强行升级依赖，硬升反而大概率触发新的版本兼容问题
  • 本次出现的34个漏洞警告均为Gatsby工具链嵌套的开发依赖漏洞，个人博客场景下没有任何被利用的可能，无需处理，等Gatsby官方后续迭代更新依赖版本即可。

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