纯净安装Gatsby 5.2出现react-server-dom-webpack相关NPM WARN求助

环境信息 #

运行gatsby info --clipboard输出：

% gatsby info --clipboard

  System:
    OS: macOS 13.0.1
    CPU: (16) x64 Intel(R) Xeon(R) W-2140B CPU @ 3.20GHz
    Shell: 5.8.1 - /bin/zsh
  Binaries:
    Node: 18.12.1 - ~/.nvm/versions/node/v18.12.1/bin/node
    npm: 8.19.2 - ~/.nvm/versions/node/v18.12.1/bin/npm
  Browsers:
    Chrome: 108.0.5359.98
    Safari: 16.1
  npmPackages:
    gatsby: ^5.2.0 => 5.2.0
    gatsby-plugin-image: ^3.2.0 => 3.2.0
    gatsby-plugin-manifest: ^5.2.0 => 5.2.0
    gatsby-plugin-sharp: ^5.2.0 => 5.2.0
    gatsby-source-filesystem: ^5.2.0 => 5.2.0
    gatsby-transformer-sharp: ^5.2.0 => 5.2.0
  npmGlobalPackages:
    gatsby-cli: 5.2.0

%

实际安装告警日志 #

运行npm i的实际输出：

% npm i
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   react@"^18.2.0" from the root project
npm WARN   10 more (react-dom, gatsby, gatsby-plugin-image, ...)
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.2.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.2.0
npm WARN     node_modules/gatsby
npm WARN deprecated async-cache@1.1.0: No longer maintained. Use [lru-cache](http://npm.im/lru-cache) version 7.6 or higher, and provide an asynchronous `fetchMethod` option.
npm WARN deprecated stable@0.1.8: Modern JS already guarantees Array#sort() is a stable sort, so this library is deprecated. See the compatibility table on MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#browser_compatibility
npm WARN deprecated babel-eslint@10.1.0: babel-eslint is now @babel/eslint-parser. This package will no longer receive updates.

added 1505 packages, and audited 1588 packages in 1m

325 packages are looking for funding
  run `npm fund` for details

15 moderate severity vulnerabilities

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.
% 

1. 告警成因 #

告警分为两类：

• Peer依赖冲突：Gatsby 5.2依赖的react-server-dom-webpack是实验版本，其peer依赖要求为react@0.0.0-experimental-c8b778b7f-20220825，但项目根依赖使用的是稳定版react@18.2.0，npm 7+的严格依赖解析规则会识别这种版本不匹配并抛出警告。
• 包废弃提示：async-cache、stable、babel-eslint这些依赖已被维护者标记为废弃，要么有替代方案，要么功能已被JS原生支持，npm会主动提示更换。

2. 纯净安装为何出现问题 #

纯净安装的Gatsby项目依赖链中存在两个矛盾点：

1. Gatsby 5.x内部引入了未及时更新peer依赖声明的实验包（即react-server-dom-webpack），它的peer依赖还停留在旧实验版React，但Gatsby项目本身要求使用稳定版React 18，两者版本要求冲突。
2. Gatsby的依赖树包含部分老旧包，这些包已被废弃但尚未被Gatsby官方替换，因此初始化时会带出废弃告警。

3. 解决方法及--legacy-peer-deps的作用 #

首选解决方案

使用npm install --legacy-peer-deps执行安装，即可消除peer依赖冲突告警。

为何Gatsby 5.x需要该参数

npm 7及以上版本默认启用严格peer依赖解析：若检测到peer依赖版本不匹配，会直接中断安装（npm 6及以前仅抛出警告）。而--legacy-peer-deps会让npm回退到npm 6的解析逻辑，忽略peer依赖的版本冲突，优先安装实际兼容的版本。

Gatsby 5.x依赖的实验版react-server-dom-webpack虽然声明需要实验版React，但实际与稳定版React 18兼容，只是包的peer依赖声明未及时更新。通过--legacy-peer-deps绕过校验后，安装可顺利完成且不影响项目运行。

其他补充处理

• 废弃包告警无需手动处理，等待Gatsby官方更新依赖替换即可；
• 安装后的中度漏洞，可先运行npm audit fix尝试自动修复，若问题未解决再考虑npm audit fix --force（注意：--force可能引发兼容性问题，需谨慎使用）。

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