Next.js14.2.4+MUI5.15.20报错：useMode返回值不可迭代

一、错误原因与修复步骤 #

出现 Error: (0 , _theme__WEBPACK_IMPORTED_MODULE_1__.useMode) is not a function or its return value is not iterable 错误，通常是以下几种情况导致的：

• useMode 未遵循 React Hook 规则，不是合法的钩子函数
• useMode 返回值不是可迭代类型（比如应该返回数组却返回了对象）
• 在 Next.js 14 默认的服务端组件（RootLayout）中直接调用了客户端 Hook

1. 修正 useMode Hook 实现 #

确保 theme.js 中的 useMode 是合法的 Hook，且返回数组类型：

// 路径可以是 app/theme.js 或 src/app/theme.js
import { useState } from 'react';
import { createTheme } from '@mui/material/styles';
import { blue, amber } from '@mui/material/colors';

// 定义亮色/暗色主题
const lightTheme = createTheme({
  palette: {
    mode: 'light',
    primary: blue,
    secondary: amber,
  },
});

const darkTheme = createTheme({
  palette: {
    mode: 'dark',
    primary: amber,
    secondary: blue,
  },
});

// 正确的 useMode Hook 实现
export function useMode() {
  const [mode, setMode] = useState('light');

  const toggleColorMode = () => {
    setMode(prev => prev === 'light' ? 'dark' : 'light');
  };

  const currentTheme = mode === 'light' ? lightTheme : darkTheme;

  // 返回数组，支持解构赋值
  return [currentTheme, toggleColorMode];
}

2. 处理 Next.js 服务端/客户端组件差异 #

Next.js 14 的 RootLayout 默认是服务端组件，不能直接调用客户端 Hook（如 useMode）。需要创建一个客户端组件来承载 MUI 的主题逻辑：

// app/Providers.jsx 或 src/app/Providers.jsx
'use client'; // 必须添加此指令标记为客户端组件

import { ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';
import { useMode } from './theme';

export function Providers({ children }) {
  const [theme] = useMode(); // 若需要切换主题，可同时解构 toggleColorMode 并传递给子组件

  return (
    <ThemeProvider theme={theme}>
      <CssBaseline /> {/* 重置全局样式，确保 MUI 主题生效 */}
      {children}
    </ThemeProvider>
  );
}

3. 在 RootLayout 中使用客户端组件 #

修改根布局，引入上述 Providers 组件包裹页面内容：

// app/layout.js 或 src/app/layout.js
import { Providers } from './Providers';

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

二、关于 src 目录的说明 #

Next.js 14 支持两种文件结构：

• 直接在项目根目录下创建 app 目录
• 在 src 目录下创建 app 目录

两种方式都是官方认可的正确做法，使用 src 目录的优势在于可以将源码与配置文件（如 package.json、next.config.js）分离，更适合大型项目的代码组织。MUI 对两种结构都完全兼容，没有强制要求必须使用 src 目录。

内容的提问来源于stack exchange，提问作者learning to code