MUI v5无代码改动出现reading 'drawer'报错及DefaultTheme无zIndex属性求解

问题根因 #

1. 依赖版本不匹配：若package.json中MUI相关依赖使用^前缀允许兼容小版本升级，MUI后续更新的小版本对主题默认配置做了不兼容调整，未锁定版本时拉取的新包会破坏原有逻辑。若你未将包锁文件提交到代码仓库，回滚代码也无法恢复依赖版本，就会出现代码未改但报错的情况。
2. 导入路径错误：createTheme或makeStyles导入路径不符合MUI v5规范，导致主题默认配置未正确合并、类型声明不匹配。
3. 类型声明未扩展：TS默认的DefaultTheme未继承MUI的主题类型定义，导致类型校验报错。
4. 主题未正确注入：自定义主题未通过ThemeProvider包裹应用根组件，导致makeStyles拿到的是未初始化的空主题。

解决步骤 #

步骤1：锁定依赖版本 #

• 删除本地node_modules文件夹和包锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml）
• 修改package.json将MUI相关依赖固定为5.0.2版本：

{
  "@mui/material": "5.0.2",
  "@mui/styles": "5.0.2",
  "@emotion/react": "^11.4.1",
  "@emotion/styled": "^11.3.0"
}

• 重新执行依赖安装：npm install（或对应包管理器的安装命令）

步骤2：修正导入路径和代码 #

• 确认createTheme从@mui/material/styles导入，不要从其他路径引入
• 确认makeStyles从@mui/styles导入，并给主题参数加上类型注解：

import { makeStyles } from '@mui/styles';
import { Theme } from '@mui/material/styles';

const useStyles = makeStyles((theme: Theme) => ({
  appBar: {
    zIndex: theme.zIndex.drawer + 1,
    transition: theme.transitions.create(['width', 'margin'], {
      easing: theme.transitions.easing.sharp,
      duration: theme.transitions.duration.leavingScreen,
    }),
  },
}));

步骤3：修复TS类型报错 #

在项目根目录的类型声明文件（通常为typings.d.ts或src/react-app-env.d.ts）中添加如下类型扩展：

import { Theme } from '@mui/material/styles';

declare module '@mui/styles/defaultTheme' {
  interface DefaultTheme extends Theme {}
}

步骤4：确认主题正确注入 #

检查应用根组件，确保自定义theme通过ThemeProvider包裹了所有业务组件：

import { ThemeProvider } from '@mui/material/styles';
import theme from './你的theme定义文件路径';

function App() {
  return (
    <ThemeProvider theme={theme}>
      {/* 所有业务组件放在此处 */}
    </ThemeProvider>
  );
}

可选优化方案 #

MUI v5官方已经不推荐使用makeStyles，如果没有历史代码包袱，可直接改用内置的sx属性或styled API，不需要额外引入独立包，也可以避免这类主题兼容问题。

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