因MUI Material及npm依赖问题无法运行React项目求解决方案

问题1：npm依赖树解析失败（ERESOLVE错误） #

执行npm安装/卸载包时出现以下错误：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: <user>@1.0.0
npm ERR! Found: react@17.0.2
npm ERR! node_modules/react
npm ERR!   react@"17.0.2" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.6.3" from shards-react@1.0.3
npm ERR! node_modules/shards-react
npm ERR!   shards-react@"^1.0.3" from the root project

注：当前项目实际使用React 18.2.0，与shards-react@1.0.3的peer依赖要求冲突

解决方案 #

• 移除shards-react（若项目未使用该包）：

  npm uninstall shards-react --legacy-peer-deps
  # 或用yarn：
  yarn remove shards-react
  

• 升级shards-react至兼容React 17/18的版本：

  npm install shards-react@latest --legacy-peer-deps
  # 或指定具体兼容版本（如存在）：
  npm install shards-react@x.x.x --legacy-peer-deps
  

• 跳过peer依赖检查（临时方案，不推荐长期使用）：
  后续所有npm操作添加--legacy-peer-deps参数，例如：

  npm install --legacy-peer-deps
  npm uninstall <package-name> --legacy-peer-deps
  

问题2：MUI编译错误（experimental_sx导出缺失） #

编译时出现以下错误：

ERROR in ./node_modules/@mui/material/styles/index.js 2:0-191

export 'experimental_sx' (reexported as 'experimental_sx') was not found in '@mui/system' (possible exports: Box, Container, GlobalStyles, Stack, StyledEngineProvider, ThemeProvider, Unstable_Grid, alignContent, alignItems, alignSelf, alpha, backgroundColor, bgcolor, border, borderBottom, borderBottomColor, borderColor, borderLeft, borderLeftColor, borderRadius, borderRight, borderRightColor, borderTop, borderTopColor, borderTransform, borders, bottom, boxSizing, breakpoints, color, colorChannel, columnGap, compose, containerClasses, createBox, createBreakpoints, createContainer, createGrid, createSpacing, createStack, createStyled, createTheme, createUnarySpacing, createUnaryUnit, css, darken, decomposeColor, display, emphasize, flex, flexBasis, flexDirection, flexGrow, flexShrink, flexWrap, flexbox, fontFamily, fontSize, fontStyle, fontWeight, gap, getContainerUtilityClass, getContrastRatio, getGridUtilityClass, getLuminance, getPath, getStackUtilityClass, getStyleFromPropValue, getStyleValue, getThemeProps, getValue, grid, gridArea, gridAutoColumns, gridAutoFlow, gridAutoRows, gridClasses, gridColumn, gridRow, gridTemplateAreas, gridTemplateColumns, gridTemplateRows, handleBreakpoints, height, hexToRgb, hslToRgb, justifyContent, justifyItems, justifySelf, keyframes, left, letterSpacing, lighten, lineHeight, margin, marginKeys, maxHeight, maxWidth, mergeBreakpointsInOrder, minHeight, minWidth, order, padding, paddingKeys, palette, paletteTransform, position, positions, private_safeAlpha, private_safeColorChannel, private_safeDarken, private_safeEmphasize, private_safeLighten, recomposeColor, responsivePropType, rgbToHex, right, rowGap, shadows, shape, shouldForwardProp, sizeHeight, sizeWidth, sizing, sizingTransform, spacing, stackClasses, style, styled, systemDefaultTheme, textAlign, textTransform, top, typography, typographyVariant, unstable_createCssVarsProvider, unstable_createGetCssVar, unstable_createStyleFunctionSx, unstable_defaultSxConfig, unstable_extendSxProp, unstable_getThemeValue, unstable_resolveBreakpointValues, unstable_styleFunctionSx, useTheme, useThemeProps, useThemeWithoutDefault, width, zIndex)

注：当前使用@mui/material@5.11.0，错误原因是@mui/material与@mui/system版本不匹配

解决方案 #

• 统一MUI包版本：卸载现有不匹配的包，重新安装同版本的@mui/material和@mui/system：

  npm uninstall @mui/material @mui/system
  npm install @mui/material@5.11.0 @mui/system@5.11.0 --legacy-peer-deps
  # 或用yarn：
  yarn remove @mui/material @mui/system
  yarn add @mui/material@5.11.0 @mui/system@5.11.0
  

• 升级至MUI最新稳定版本（推荐，可避免版本兼容问题）：

  npm install @mui/material@latest @mui/system@latest --legacy-peer-deps
  # 或用yarn：
  yarn upgrade @mui/material@latest @mui/system@latest
  

• 清理依赖后重新安装：
  1. 删除node_modules和lock文件：

     rm -rf node_modules package-lock.json yarn.lock  # Windows用rmdir /s /q node_modules && del package-lock.json yarn.lock
     

  2. 重新安装依赖：

     npm install --legacy-peer-deps
     

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