CRA迁移Vite后无法解析@mui/icons-material图标依赖怎么办

将项目从CRA迁移至Vite后，执行npm run dev启动开发服务时抛出依赖解析失败报错，报错信息如下：

The following dependencies are imported but could not be resolved:

  @mui/icons-material/Article (imported by /Blog/Admin/Exports.jsx)
  @mui/icons-material/Comment (imported by /Social/Admin/Comment/View.jsx)
  @mui/icons-material/TextSnippet (imported by /Contents/Admin/Page/List.jsx)
  @mui/icons-material/FindInPage (imported by /Contents/Admin/Page/List.jsx)
  @mui/icons-material/AccountTree (imported by /Taxonomy/Admin/Hierarchy/Manage.jsx)
  @mui/icons-material/LocalOffer (imported by /Taxonomy/Admin/Tag/Manage.jsx)
  @mui/icons-material/NoteAlt (imported by /Forms/Admin/Form/List.jsx)
  @mui/icons-material/EventNote (imported by /Logs/Admin/Exports.jsx)
  @mui/icons-material/Navigation (imported by /Navigation/Admin/Exports.jsx)
  @mui/icons-material/Abc (imported by /Contents/Admin/Exports.jsx)
  @mui/icons-material/Fingerprint (imported by /Entities/Admin/Exports.jsx)
  @mui/icons-material/Support (imported by /Ticketing/Admin/Exports.jsx)
  @mui/icons-material/Shuffle (imported by /Entities/Admin/EntityType/List.jsx)
  @mui/icons-material/Delete (imported by /Logs/Admin/List.jsx)
  @mui/icons-material/Search (imported by /Contents/Admin/Image/List.jsx)
  @mui/icons-material/Done (imported by /Ticketing/Admin/Ticket/List.jsx)
  @mui/icons-material/SyncAlt (imported by /Accounts/Admin/User/List.jsx)
  @mui/icons-material/Error (imported by /Logs/Admin/List.jsx)
  @mui/icons-material/ListAlt (imported by /Contents/Admin/Section/List.jsx)
  @mui/icons-material/Message (imported by /Ticketing/Admin/Ticket/List.jsx)
  @mui/icons-material/Link (imported by /Navigation/Admin/LinkGroup/List.jsx)
  @mui/icons-material/Bolt (imported by /Contents/Admin/Section/List.jsx)

Are they installed?

执行npm install重装全量依赖后重启服务，报错仍然存在。手动进入node_modules/@mui/icons-material目录查看，对应图标文件（例如Article.js）真实存在且内容正常，文件内容示例：

"use strict";

var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");

Object.defineProperty(exports, "__esModule", {
  value: true
});
exports.default = void 0;

var _createSvgIcon = _interopRequireDefault(require("./utils/createSvgIcon"));

var _jsxRuntime = require("react/jsx-runtime");

var _default = (0, _createSvgIcon.default)( /*#__PURE__*/(0, _jsxRuntime.jsx)("path", {
  d: "M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm-5 14H7v-2h7v2zm3-4H7v-2h10v2zm0-4H7V7h10v2z"
}), 'Article');

exports.default = _default;

该报错由Vite与CRA底层依赖解析规则差异导致：你安装的@mui/icons-material版本提供的是CommonJS格式的单文件导出，Vite默认的依赖扫描逻辑没有正确识别这类深路径导入的CommonJS模块，因此抛出解析失败错误，和依赖是否安装、文件是否存在没有直接关联。

按优先级依次尝试以下方案：

• 方案1：在vite.config.js中配置optimizeDeps.include，强制Vite预构建@mui/icons-material相关依赖，配置示例：

export default defineConfig({
  // 保留原有其他配置
  optimizeDeps: {
    include: [
      '@mui/icons-material'
    ]
  }
})

修改配置后删除node_modules/.vite缓存目录，重新执行npm run dev启动服务即可。

• 方案2：如果方案1无效，调整导入写法。部分旧版本MUI图标不支持import Article from '@mui/icons-material/Article'的深路径导入，统一改为从包入口导入的写法：

// 替换原有深路径导入
// import Article from '@mui/icons-material/Article'
// 改为
import { Article } from '@mui/icons-material'

• 方案3：如果以上两个方案都不生效，检查项目是否配置了vite-plugin-commonjs这类CommonJS转译插件，插件配置规则错误也会导致CommonJS模块解析失败。可以暂时移除插件验证是否为配置冲突，确认后调整插件过滤规则，将@mui/icons-material加入插件的转译包含列表即可。

注意：每次修改Vite配置后必须清除.vite缓存目录再重启服务，否则旧的预构建缓存会导致配置不生效。

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