npm 8.11环境下无法构建Shopware 6管理后台问题排查

问题现象 #

运行bin/build-administration.sh脚本构建Shopware 6管理后台时，抛出如下依赖解析错误：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: eslint-config-airbnb-base@13.2.0
npm ERR! Found: eslint@7.10.0
npm ERR! node_modules/eslint
npm ERR!   dev eslint@"7.10.0" from the root project
npm ERR!   peer eslint@"^6.0.0 || ^7.0.0 || ^8.0.0" from @typescript-eslint/eslint-plugin@5.1.0
npm ERR!   node_modules/@typescript-eslint/eslint-plugin
npm ERR!     @typescript-eslint/eslint-plugin@"5.1.0" from the root project
npm ERR!   14 more (@typescript-eslint/experimental-utils, eslint-utils, ...)
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer eslint@"^4.19.1 || ^5.3.0" from eslint-config-airbnb-base@13.2.0
npm ERR! node_modules/eslint-config-airbnb-base
npm ERR!   dev eslint-config-airbnb-base@"13.2.0" from the root project
npm ERR!   eslint-config-airbnb-base@"^13.2.0" from @shopware-ag/eslint-config-base@1.0.0
npm ERR!   node_modules/@shopware-ag/eslint-config-base
npm ERR!     @shopware-ag/eslint-config-base@"1.0.0" from the root project
npm ERR! 
npm ERR! Conflicting peer dependency: eslint@5.16.0
npm ERR! node_modules/eslint
npm ERR!   peer eslint@"^4.19.1 || ^5.3.0" from eslint-config-airbnb-base@13.2.0
npm ERR!   node_modules/eslint-config-airbnb-base
npm ERR!     dev eslint-config-airbnb-base@"13.2.0" from the root project
npm ERR!     eslint-config-airbnb-base@"^13.2.0" from @shopware-ag/eslint-config-base@1.0.0
npm ERR!     node_modules/@shopware-ag/eslint-config-base
npm ERR!       @shopware-ag/eslint-config-base@"1.0.0" from the root project

环境信息 #

当前运行环境版本：

$ npm -v
8.11.0
$ node -v
v16.15.1

使用的Shopware版本为6.4.11.1，同一份项目代码在npm 8.5版本环境下可正常完成构建。核心疑问为：该问题属于Shopware端的缺陷还是npm版本兼容问题，是否需要更新Shopware侧的相关依赖配置。

问题结论与解决方案 #

• 该问题属于npm版本规则变更+Shopware旧版本依赖声明不严谨共同导致的兼容问题，不属于Shopware核心功能缺陷，但Shopware侧确实存在依赖配置未适配新版npm规则的问题。
• 根因说明：
  • npm在8.6及之后的小版本中，默认将peer依赖的版本冲突从警告级调整为错误级，会直接中断安装/构建流程；npm 8.5及更早版本遇到同类冲突仅打印警告，不会阻断流程，这是不同npm版本下构建结果不一致的直接原因。
  • 具体依赖冲突点为：Shopware 6.4.11.1内置的@shopware-ag/eslint-config-base@1.0.0依赖了过旧的eslint-config-airbnb-base@13.2.0，该版本仅支持eslint 4.x/5.x版本，但项目根目录声明的eslint版本为7.10.0，版本范围完全不匹配，旧版npm不拦截时可以正常安装使用，新版npm严格校验后直接抛出错误。
• 解决方式：
  1. 临时快速修复：执行构建时追加--legacy-peer-deps参数，让npm回退到旧版的peer依赖校验逻辑，和npm 8.5的行为保持一致，无需修改项目代码即可完成构建，参考命令：

     npm install --legacy-peer-deps
     bin/build-administration.sh
     

  2. 长期适配方案：如果需要在新版npm环境下无额外参数正常构建，Shopware侧需要更新相关依赖配置，要么升级@shopware-ag/eslint-config-base依赖的airbnb规则包版本到支持eslint 7的版本，要么对齐项目内eslint版本和依赖包的要求范围，后续发布的高版本Shopware已经修复了该依赖冲突问题。

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