Electron+React手动搭建项目npm安装JSX依赖报错排查

问题背景 #

未使用create-react-app脚手架，手动搭建了基于React的Electron应用，目前无法回退至脚手架搭建方案，正在引入支持JSX开发的相关依赖，项目package.json中依赖声明如下：

"dependencies": {
    "electron": ">=11.2.3",
    "electron-reload": ">=1.5.0",
    "graphql": "^14.5.8",
    "react": ">=17.0.1",
    "react-dom": ">=17.0.1",
    "react-scripts": ">=4.0.1",
    "concurrently": ">=7.2.2",
    "wait-on": ">=6.0.1"
}

执行npm install操作时抛出如下报错：

199 silly placeDep ROOT react-refresh@0.11.0 OK for: @pmmmwh/react-refresh-webpack-plugin@0.5.7 want: >=0.10.0 <1.0.0
200 silly placeDep ROOT webpack@5.73.0 OK for: @pmmmwh/react-refresh-webpack-plugin@0.5.7 want: >=4.43.0 <6.0.0
201 timing idealTree Completed in 2680ms
202 timing command:install Completed in 2683ms
203 verbose stack TypeError: Cannot read property 'matches' of undefined
203 verbose stack     at Arborist.[canPlaceDep] (C:\Program Files\nodejs\node_modules\npm\node_modules\@npmcli\arborist\lib\arborist\build-ideal-tree.js:1284:15)
203 verbose stack     at Arborist.[placeDep] (C:\Program Files\nodejs\node_modules\npm\node_modules\@npmcli\arborist\lib\arborist\build-ideal-tree.js:1061:36)
203 verbose stack     at Arborist.[placeDep] (C:\Program Files\nodejs\node_modules\npm\node_modules\@npmcli\arborist\lib\arborist\build-ideal-tree.js:1212:41)

已在配置中明确声明react-scripts、concurrently、wait-on三个依赖包的版本要求，排查未发现显性配置遗漏。

根因定位 #

报错与项目依赖配置无关，核心触发原因是本地Node版本不受支持：低版本Node与新版npm内置的Arborist依赖树解析工具存在兼容性问题，在解析版本范围匹配逻辑时会触发空值读取错误。

解决步骤 #

Windows 11环境下无法直接通过npm命令完成Node版本升级，可按以下步骤操作：

• 安装nvm-windows（Windows平台Node版本管理工具）
• 打开终端执行nvm install lts下载Node长期支持版本
• 执行nvm use lts切换全局默认Node版本为刚安装的LTS版本
• 删除项目目录下的node_modules文件夹与package-lock.json锁文件
• 重新执行npm install即可正常完成依赖安装

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