Next.js项目升级Material UI v4到v5启动时报react模块找不到

报错原因 #

该报错核心为模块解析规则异常：虽然你已在项目package.json中声明react依赖，但MUI依赖的@emotion包在检索react依赖时，未命中当前项目node_modules内的react安装包。常见诱因如下：

• 项目为monorepo多包结构，NextJS项目位于子目录，依赖默认向上检索上层node_modules，而上层目录未安装对应版本react
• 包管理器的依赖提升规则将react、@emotion相关包提升到了项目目录之外的位置，未被NextJS的默认解析规则捕获
• 自定义的webpack或babel配置修改了默认模块解析优先级，导致react路径匹配失败

排查解决步骤 #

• 强制指定react、react-dom解析路径
  在项目的next.config.js中添加如下webpack配置，强制所有依赖优先使用当前项目的react包：

module.exports = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      react: require.resolve('react'),
      'react-dom': require.resolve('react-dom'),
    };
    return config;
  },
};

• 调整包管理器的依赖提升规则
  如果使用pnpm，在项目根目录新增.npmrc文件，添加如下配置：

public-hoist-pattern[]=*react*
public-hoist-pattern[]=*react-dom*
public-hoist-pattern[]=*@emotion/*
public-hoist-pattern[]=*@mui/*

如果使用yarn workspace，在根目录package.json中添加nohoist规则：

"workspaces": {
  "packages": ["你的NextJS项目对应目录"],
  "nohoist": ["**/react", "**/react-dom", "**/@emotion/*", "**/@mui/*"]
}

• 补充缺失依赖
  报错链路中出现了@mui/icons-material的引用，但你的package.json中未声明该依赖，执行安装命令补全：

npm install @mui/icons-material

• 清理缓存后重装依赖
  执行以下命令清理所有缓存后重新安装依赖，排除旧缓存干扰：

rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml .next
npm install

• 检查babel配置
  你已安装的第三方包babel-preset-next和NextJS内置的babel预设存在冲突可能，建议移除该包，使用NextJS默认的babel配置，避免自定义babel规则干扰模块解析。

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