Gatsby项目安装gatsby-plugin-purgecss插件失败求助

问题 #

合并Gatsby项目CSS时，安装gatsby-plugin-purgecss插件失败，抛出依赖冲突错误，日志如下：

evo02@evo02:/var/www/html/Evolvan (staging fresh without edits)/evolvan.com-gatsby$ npm install gatsby-plugin-purgecss
npm WARN ERESOLVE overriding peer dependency
npm WARN While resolving: react-server-dom-webpack@0.0.0-experimental-c8b778b7f-20220825
npm WARN Found: react@18.2.0
npm WARN node_modules/react
npm WARN   peerOptional react@"^16.8.0 || ^17.0.0 || ^18.0.0" from @apollo/client@3.7.14
npm WARN   node_modules/@apollo/client
npm WARN     peer @apollo/client@"^3" from @graphql-tools/links@8.3.36
npm WARN     node_modules/@graphql-tools/links
npm WARN     2 more (apollo-upload-client, gatsby-source-graphql)
npm WARN   20 more (@gatsbyjs/reach-router, formik, gatsby, gatsby-link, ...)
npm WARN
npm WARN Could not resolve dependency:
npm WARN peer react@"0.0.0-experimental-c8b778b7f-20220825" from react-server-dom-webpack@0.0.0-experimental-c8b778b7f-20220825
npm WARN node_modules/react-server-dom-webpack
npm WARN   react-server-dom-webpack@"0.0.0-experimental-c8b778b7f-20220825" from gatsby@5.10.0
npm WARN   node_modules/gatsby
npm WARN
npm WARN Conflicting peer dependency: react@0.0.0-experimental-c8b778b7f-20220825
npm WARN node_modules/react
npm WARN   peer react@"0.0.0-experimental-c8b778b7f-20220825" from react-server-dom-webpack@0.0.0-experimental-c8b778b7f-20220825
npm WARN   node_modules/react-server-dom-webpack
npm WARN     react-server-dom-webpack@"0.0.0-experimental-c8b778b7f-20220825" from gatsby@5.10.0
npm WARN     node_modules/gatsby
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: webpack-filter-warnings-plugin@1.2.1
npm ERR! Found: webpack@5.83.1
npm ERR! node_modules/webpack
npm ERR!   peer webpack@">=4.43.0 <6.0.0" from @pmmmwh/react-refresh-webpack-plugin@0.5.10
npm ERR!   node_modules/@pmmmwh/react-refresh-webpack-plugin
npm ERR!     @pmmmwh/react-refresh-webpack-plugin@"^0.5.10" from gatsby@5.10.0
npm ERR!     node_modules/gatsby
npm ERR!       peer gatsby@"^5.0.0-next" from babel-plugin-remove-graphql-queries@5.10.0
npm ERR!       node_modules/babel-plugin-remove-graphql-queries
npm ERR!         babel-plugin-remove-graphql-queries@"^5.10.0" from gatsby@5.10.0
npm ERR!         2 more (gatsby-plugin-image, gatsby-plugin-typescript)
npm ERR!       15 more (gatsby-plugin-eslint, gatsby-plugin-google-gtag, ...)
npm ERR!   peer webpack@">=2" from babel-loader@8.3.0
npm ERR!   node_modules/babel-loader
npm ERR!     babel-loader@"^8.3.0" from gatsby@5.10.0
npm ERR!     node_modules/gatsby
npm ERR!       peer gatsby@"^5.0.0-next" from babel-plugin-remove-graphql-queries@5.10.0
npm ERR!       node_modules/babel-plugin-remove-graphql-queries
npm ERR!         babel-plugin-remove-graphql-queries@"^5.10.0" from gatsby@5.10.0
npm ERR!         2 more (gatsby-plugin-image, gatsby-plugin-typescript)
npm ERR!       15 more (gatsby-plugin-eslint, gatsby-plugin-google-gtag, ...)
npm ERR!   18 more (css-loader, css-minimizer-webpack-plugin, ...)
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer webpack@"^2.0.0 || ^3.0.0 || ^4.0.0" from webpack-filter-warnings-plugin@1.2.1
npm ERR! node_modules/webpack-filter-warnings-plugin
npm ERR!   webpack-filter-warnings-plugin@"^1.2.1" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: webpack@4.46.0
npm ERR! node_modules/webpack
npm ERR!   peer webpack@"^2.0.0 || ^3.0.0 || ^4.0.0" from webpack-filter-warnings-plugin@1.2.1
npm ERR!   node_modules/webpack-filter-warnings-plugin
npm ERR!     webpack-filter-warnings-plugin@"^1.2.1" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR!
npm ERR!
npm ERR! For a full report see:
npm ERR! /home/evo02/.npm/_logs/2023-07-11T04_50_23_178Z-eresolve-report.txt

完整日志路径：/home/evo02/.npm/_logs/2023-07-11T04_50_23_178Z-debug-0.log

已尝试npm cache clean --force清理缓存，收到npm WARN using --force Recommended protections disabled.警告，不确定缓存状态，需解决安装失败问题。

解决步骤 #

1. 用--legacy-peer-deps参数安装插件 #

直接使用npm提供的兼容模式参数绕过peer依赖冲突：

npm install gatsby-plugin-purgecss --legacy-peer-deps

该参数会采用npm v4-v6的peer依赖解析逻辑，忽略新版本中严格的依赖匹配要求，适合Gatsby这类依赖结构复杂的项目。

2. 修复webpack-filter-warnings-plugin兼容问题 #

错误核心是webpack-filter-warnings-plugin@1.2.1仅支持webpack 2/3/4，但当前项目使用webpack 5。可通过以下方式处理：

• 手动升级插件：如果该插件是你主动安装的，执行升级命令：

npm install webpack-filter-warnings-plugin@^2.0.0 --save-dev

v2版本已支持webpack 5。

• 强制子依赖升级：如果该插件是其他依赖的子依赖，在package.json中添加overrides字段强制升级：

"overrides": {
  "webpack-filter-warnings-plugin": "^2.0.0"
}

添加后执行npm install即可生效。

3. 验证缓存状态 #

执行以下命令无需--force即可验证缓存是否正常：

npm cache verify

输出结果显示缓存有效则说明清理完成。

4. 重置依赖环境（兜底方案） #

若以上方法无效，可完全重置依赖：

1. 删除依赖文件夹和锁文件：

rm -rf node_modules
rm package-lock.json

2. 重新安装所有依赖：

npm install --legacy-peer-deps

3. 再次安装目标插件：

npm install gatsby-plugin-purgecss --legacy-peer-deps

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