Material-UI v5搭配styled-components与TypeScript时报错找不到@emotion/styled

问题根源 #

你仅在tsconfig.json中配置路径别名是无效的，tsconfig的paths配置仅作用于TypeScript的类型检查阶段，项目打包工具（Webpack/Vite等）或包管理器不会读取该配置，因此MUI依然会加载默认依赖@emotion/styled的@mui/styled-engine包，导致找不到依赖报错。

解决方案 #

第一步：确认安装必要依赖 #

# 安装MUI适配styled-components的引擎包、styled-components本体
npm install @mui/styled-engine-sc styled-components
# TypeScript项目如果使用styled-components v5版本，需额外安装类型定义
npm install -D @types/styled-components

第二步：配置模块解析规则（任选一种即可） #

方案1：包管理器强制替换（无需修改打包配置，通用性最强）

在package.json中添加规则，强制所有依赖引用的@mui/styled-engine都替换为适配styled-components的版本：

• 使用npm的场景：

{
  "overrides": {
    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
  }
}

• 使用yarn/pnpm的场景：

{
  "resolutions": {
    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
  }
}

配置完成后删除node_modules文件夹、包锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行依赖安装命令即可。

方案2：打包工具配置别名

如果不想修改包管理器配置，可以给对应的打包工具添加别名规则：

• Webpack配置（含react-app-rewired等自定义CRA配置场景）：

// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      '@mui/styled-engine': '@mui/styled-engine-sc'
    }
  }
}

• Vite配置：

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@mui/styled-engine': '@mui/styled-engine-sc'
    }
  }
})

第三步：补充完善tsconfig配置 #

确认tsconfig.json中配置了正确的baseUrl，否则paths规则不会生效：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@mui/styled-engine": [ "./node_modules/@mui/styled-engine-sc" ]
    }
  }
}

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