NextJS集成Mantine UI报错：useMantineColorScheme需ColorSchemeProvider包裹

核心原因 #

报错Error: useMantineColorScheme hook was called outside of context, make sure your app is wrapped with ColorSchemeProvider component的本质是：主题切换组件未被ColorSchemeProvider正确包裹，或者Provider的层级/初始化逻辑错误，导致组件渲染时无法获取主题上下文。

具体问题定位（基于你的代码结构） #

从可复现场景来看，问题出在_app.tsx的Provider配置顺序：

• ColorSchemeProvider未作为MantineProvider的父组件存在，导致主题上下文无法传递给Mantine内部组件；
• 部分组件可能在Provider完成初始化前就已渲染，触发上下文缺失报错。

修复步骤 #

1. 调整_app.tsx的Provider层级 #

确保ColorSchemeProvider包裹MantineProvider，且整个应用组件树都在这两个Provider范围内：

// _app.tsx
import { useState } from 'react';
import { MantineProvider } from '@mantine/core';
import { ColorSchemeProvider, ColorScheme } from '@mantine/core';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  const [colorScheme, setColorScheme] = useState<ColorScheme>('light');
  const toggleColorScheme = () => {
    setColorScheme((current) => (current === 'light' ? 'dark' : 'light'));
  };

  return (
    <ColorSchemeProvider colorScheme={colorScheme} toggleColorScheme={toggleColorScheme}>
      <MantineProvider
        withGlobalStyles
        withNormalizeCSS
        theme={{ colorScheme }}
      >
        <Component {...pageProps} />
      </MantineProvider>
    </ColorSchemeProvider>
  );
}

2. 确认主题切换组件的使用范围 #

检查colorComponent.tsx，确保它在_app.tsx的Provider包裹下渲染，不要在_document.tsx或其他脱离上下文的位置使用：

// colorComponent.tsx
import { ActionToggle, useMantineColorScheme } from '@mantine/core';
import { SunIcon, MoonIcon } from '@modulz/radix-icons';

export default function ColorToggle() {
  const { colorScheme, toggleColorScheme } = useMantineColorScheme();
  return (
    <ActionToggle
      onClick={toggleColorScheme}
      size="md"
      sx={(theme) => ({
        backgroundColor: theme.colorScheme === 'dark' ? theme.colors.dark[6] : theme.colors.gray[0],
      })}
    >
      {colorScheme === 'dark' ? <SunIcon /> : <MoonIcon />}
    </ActionToggle>
  );
}

3. 简化_document.tsx配置 #

仅保留官方要求的基础配置，不要添加额外主题逻辑：

// _document.tsx
import { Html, Head, Main, NextScript } from 'next/document';
import { ColorSchemeScript } from '@mantine/core';

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <ColorSchemeScript defaultColorScheme="light" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

关键注意事项 #

• ColorSchemeProvider必须是MantineProvider的父组件，确保主题上下文能传递给所有Mantine组件；
• useMantineColorScheme钩子仅能在客户端组件中使用，不要在服务端渲染逻辑（如getStaticProps/getServerSideProps）中调用；
• 若使用Next.js 13+ App Router，需将Provider移至layout.tsx中，Pages Router按上述步骤即可修复。

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