全新MacBook Pro运行gatsby-theme-apollo-docs依赖冲突问题求助

问题原因 #

你遇到的是旧项目peer依赖版本冲突问题：你安装的gatsby-theme-apollo-docs@5.3.1版本核心依赖为React 16系列，而你项目默认使用React 17，同时apollo-algolia-autocomplete等关联依赖又要求React 17版本，多个依赖对基础库的版本要求不匹配，就会触发大量依赖解析失败的警告。

你使用的npm audit fix、npm audit fix --force命令仅用于修复依赖已知的安全漏洞，无法解决版本冲突问题，--force参数还会强制升级依赖大版本，进一步加剧版本不兼容情况。

解决方案 #

1. 最简方案：添加--legacy-peer-deps参数安装
   npm 7及以上版本默认开启严格peer依赖校验，添加该参数可跳过校验直接完成安装，操作步骤如下：

# 先清理当前项目的无效依赖缓存
rm -rf node_modules package-lock.json
# 执行安装，跳过依赖校验
npm install gatsby-theme-apollo-docs --legacy-peer-deps

不要使用sudo执行项目级别的npm依赖安装，否则容易引发后续文件读写权限问题，若遇到权限报错请先修正npm全局存储路径的权限，不要直接加sudo执行命令

2. 替代方案：使用yarn安装
   yarn对旧项目的peer依赖兼容规则更宽松，不会强制阻断安装，操作步骤如下：

# 全局安装yarn
npm install -g yarn
# 清理现有无效依赖
rm -rf node_modules package-lock.json
# 执行安装
yarn add gatsby-theme-apollo-docs

按照上述任意方案操作即可完成依赖安装，正常启动项目。

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