React+TypeScript+Webpack打包时@mui/material依赖解析错误

在非CRA的React项目中配置Webpack后，执行打包命令时遇到@mui/material相关解析错误。错误提示@mui/material/styles因被解析为完全指定模块而失败，推测源于严格ES模块环境。已尝试删除node_modules和package-lock.json重新安装，问题未解决。

经排查，错误来自项目依赖的组件库company_name/COMPONENT_LIB中某组件的import { useTheme } from "@mui/material/styles";语句。该组件库未包含node_modules，但package.json已声明@mui/material为依赖，且使用@mui/material其他部分无报错。疑问：是否遗漏了配置？是否需要在组件库构建时包含node_modules？

完整错误日志 #

ERROR in ./node_modules/company_name/COMPONENT_LIB/dist/some-component/index.js 2:0-48
Module not found: Error: Can't resolve '@mui/material/styles' in '/Users/username/MY_PROJECT/node_modules/company_name/COMPONENT_LIB/dist/some-component'
Did you mean 'index.js'?
BREAKING CHANGE: The request '@mui/material/styles' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains "type": "module").
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
resolve '@mui/material/styles' in '/Users/username/MY_PROJECT/node_modules/company_name/COMPONENT_LIB/dist/some-component'
  Parsed request is a module
  using description file: /Users/username/MY_PROJECT/node_modules/company_name/COMPONENT_LIB/package.json (relative path: ./dist/some-component)
    Field 'browser' doesn't contain a valid alias configuration
    resolve as module
      /Users/username/MY_PROJECT/node_modules/company_name/COMPONENT_LIB/dist/some-component/node_modules doesn't exist or is not a directory
      /Users/username/MY_PROJECT/node_modules/company_name/COMPONENT_LIB/dist/node_modules doesn't exist or is not a directory
      /Users/username/MY_PROJECT/node_modules/company_name/COMPONENT_LIB/node_modules doesn't exist or is not a directory
      /Users/username/MY_PROJECT/node_modules/company_name/node_modules doesn't exist or is not a directory
      /Users/username/MY_PROJECT/node_modules/node_modules doesn't exist or is not a directory
      looking for modules in /Users/username/MY_PROJECT/node_modules
        existing directory /Users/username/MY_PROJECT/node_modules/@mui/material
          using description file: /Users/username/MY_PROJECT/node_modules/@mui/material/package.json (relative path: .)
            using description file: /Users/username/MY_PROJECT/node_modules/@mui/material/package.json (relative path: ./styles)
              Field 'browser' doesn't contain a valid alias configuration
              /Users/username/MY_PROJECT/node_modules/@mui/material/styles is not a file
      /Users/username/node_modules doesn't exist or is not a directory
      /Users/username/node_modules doesn't exist or is not a directory
      /Users/node_modules doesn't exist or is not a directory
      /node_modules doesn't exist or is not a directory
 @ ./node_modules/company_name/COMPONENT_LIB/dist/index.js 32:0-43 303:0-650:2
 @ ./src/surface/index.tsx
 @ ./src/index.ts 2:0-26 2:0-26

项目配置文件 #

MY_PROJECT/tsconfig.json #

...
"compilerOptions": {
    "jsx": "react-jsx",
    "target": "esnext",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    ...
  }
...

MY_PROJECT/webpack.config.js #

{
    entry: './src/index.ts',
    output: {
        filename: 'bundle.js',
        path: path.resolve(__dirname, 'dist'),
    },
    module: {
        rules: [
            {
                test: /\.tsx?$/,
                use: 'ts-loader',
                exclude: /node_modules/,
            },
        ],
    },
    resolve: {
        extensions: ['.tsx', '.ts', '.js'],
    }
}

MY_PROJECT/package.json #

{
    "type": "module",
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
    "files": [
        "dist"
    ],
    "scripts": {
        "build": "webpack",
        "prepare": "npm run build",
        ...
    },
    "dependencies": {
        ...
        "@babel/cli": "^7.22.10",
        "@babel/core": "^7.22.11",
        "@babel/preset-env": "^7.22.10",
        "@babel/preset-react": "^7.22.5",
        "@babel/preset-typescript": "^7.21.4",
        ...
        "@types/react": "^18.0.37",
        "@types/react-dom": "^18.0.11",
        ...
        "babel-loader": "^8.3.0",
        "eslint": "^8.47.0",
        ...
        "react-docgen-typescript-loader": "^3.7.2",
        "storybook": "^7.0.7",
        "ts-loader": "^9.4.4",
        "typescript": "^5.2.2",
        ...
        "react": "^18.2.0",
        "react-dom": "^18.2.0",
        "tss-react": "^4.8.2"
        ...
        "webpack": "^5.88.2",
        "webpack-cli": "^5.1.4",
        "webpack-dev-server": "^4.15.1"
    }
}

核心原因 #

组件库company_name/COMPONENT_LIB的构建产物是严格ES模块（其package.json可能包含"type": "module"，或产物为.mjs格式），这种环境下ES模块要求导入路径必须带完整文件扩展名。而@mui/material/styles是目录形式，Webpack默认不会自动补全目录下的index.js扩展名，导致解析失败。

不需要在组件库构建时包含node_modules，这会导致包体积过大且不符合依赖规范。

具体解决步骤 #

1. 修改Webpack配置，添加扩展名补全规则 #

在webpack.config.js的resolve配置中补充扩展名、适配ES模块主字段，或直接通过别名映射到具体文件：

resolve: {
    extensions: ['.tsx', '.ts', '.js', '.jsx'],
    mainFields: ['module', 'main'],
    alias: {
        '@mui/material/styles': '@mui/material/styles/index.js'
    }
}

2. 调整组件库的构建配置（若有权限修改） #

如果能修改组件库代码，将导入语句改为带完整扩展名的形式：

import { useTheme } from "@mui/material/styles/index.js";

或在组件库的构建工具（Webpack/Rollup）配置中，开启自动补全扩展名的功能，确保产物中的导入路径包含完整后缀。

3. 调整TypeScript模块解析模式 #

在tsconfig.json的compilerOptions中，将moduleResolution改为bundler（适用于TypeScript 4.7+），让TS遵循打包工具的解析规则：

"moduleResolution": "bundler"

4. 关闭Webpack严格ES模块解析（临时方案） #

在Webpack配置中添加fullySpecified: false，禁用严格的扩展名检查：

resolve: {
    fullySpecified: false,
    extensions: ['.tsx', '.ts', '.js']
}

注意：此方案可能引发其他ES模块解析问题，仅作为临时修复使用。

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