升级@mui/material从5.14.20到5.15.10后触发export语法错误

我将@mui/material的小版本从5.14.20升级至5.15.10后，触发了Syntax error: unexpected token 'export'错误，错误来自@mui/utils/generateUtilityClasses/index.js中的ES模块语法，而我的项目并未直接导入该模块。完整错误堆栈如下：

(node:79404) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
(Use `node --trace-warnings ...` to show where the warning was created)
/HOME/project-main/website/node_modules/@mui/utils/generateUtilityClasses/index.js:1
export { default } from './generateUtilityClasses';
^^^^^^

SyntaxError: Unexpected token 'export'
    at internalCompileFunction (node:internal/vm:77:18)
    at wrapSafe (node:internal/modules/cjs/loader:1288:20)
    at Module._compile (node:internal/modules/cjs/loader:1340:27)
    at Module._extensions..js (node:internal/modules/cjs/loader:1435:10)
    at Module.load (node:internal/modules/cjs/loader:1207:32)
    at Module._load (node:internal/modules/cjs/loader:1023:12)
    at cjsLoader (node:internal/modules/esm/translators:356:17)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:305:7)
    at ModuleJob.run (node:internal/modules/esm/module_job:218:25)
    at async ModuleLoader.import (node:internal/modules/esm/loader:329:24)
    at async BuildPipeline.retrieveManifest (file:///HOME/project-main/website/node_modules/astro/dist/core/build/buildPipeline.js:92:26)
    at async generatePages (file:///HOME/project-main/website/node_modules/astro/dist/core/build/generate.js:110:16)
    at async staticBuild (file:///HOME/project-main/website/node_modules/astro/dist/core/build/static-build.js:93:7)
    at async AstroBuilder.build (file:///HOME/project-main/website/node_modules/astro/dist/core/build/index.js:134:5)
    at async AstroBuilder.run (file:///HOME/project-main/website/node_modules/astro/dist/core/build/index.js:165:7)
    at async build (file:///HOME/project-main/website/node_modules/astro/dist/core/build/index.js:44:3)
    at async build (file:///HOME/project-main/website/node_modules/astro/dist/cli/build/index.js:21:3)
    at async runCommand (file:///HOME/project-main/website/node_modules/astro/dist/cli/index.js:116:7)
    at async cli (file:///HOME/project-main/website/node_modules/astro/dist/cli/index.js:144:5)

Node.js v20.11.0

问题原因 #

MUI 5.15.x版本调整了内部依赖的模块输出格式，部分核心包（如@mui/utils）仅保留ES模块版本，但项目构建工具（此处为Astro）在处理依赖时，仍使用CommonJS加载器尝试解析这些ES模块，导致语法兼容报错。

解决方案 #

• 调整项目模块类型
  在项目根目录的package.json中添加"type": "module"，强制Node.js采用ES模块规则处理所有.js文件：

  {
    "type": "module"
  }
  

  注意：若项目中存在CommonJS语法的文件，需将其重命名为.cjs后缀，或修改语法适配ES模块规范。

• 配置构建工具转译MUI依赖
  若无法修改项目模块类型，可在Astro配置中指定转译@mui/*系列包，确保构建工具将其转换为兼容当前模块系统的格式。修改astro.config.mjs：

  import { defineConfig } from 'astro/config';
  
  export default defineConfig({
    vite: {
      optimizeDeps: {
        include: ['@mui/utils', '@mui/material', '@mui/system']
      },
      ssr: {
        noExternal: ['@mui/utils', '@mui/material', '@mui/system']
      }
    }
  });
  

• 临时锁定版本
  若上述方案暂无法生效，可在package.json中锁定@mui/material版本为5.14.20，执行依赖安装命令回退版本：

  {
    "dependencies": {
      "@mui/material": "5.14.20"
    }
  }
  

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