Next.js应用中Chakra UI暗黑模式不生效问题求助

云原生阿岚

2026-8-9

Next.js + Chakra UI 开发环境暗黑模式不生效的解决方案

核心原因

开发环境下浏览器会缓存Chakra UI的颜色模式偏好（存在localStorage），同时Next.js的热刷新机制可能导致主题配置未正确重载；而生产环境是全新构建，无缓存干扰，因此暗黑模式能正常生效。

具体解决步骤

清除浏览器本地存储缓存
Chakra UI会将用户的颜色模式存在localStorage的chakra-ui-color-mode键中，即使修改了initialColorMode，浏览器仍优先读取缓存值。操作：
1. 打开Chrome开发者工具（F12）
2. 切换到Application标签页
3. 找到Local Storage -> 对应本地开发域名
4. 删除chakra-ui-color-mode条目，刷新页面

统一主题配置与ColorModeScript参数
避免硬编码initialColorMode值，确保document.js中的ColorModeScript和主题配置完全一致，防止配置冲突：

// 假设主题文件路径为 styles/theme.js
import { theme } from '../styles/theme';

// document.js
<body>
  <ColorModeScript initialColorMode={theme.config.initialColorMode} />
  <Main />
  <NextScript />
</body>

强制ChakraProvider重载主题
开发环境的Fast Refresh可能未触发主题更新，给ChakraProvider添加依赖于颜色模式的key，强制组件重载：

// _app.js
import { ChakraProvider } from '@chakra-ui/react';
import { theme } from '../styles/theme';

function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider theme={theme} key={theme.config.initialColorMode}>
      <Component {...pageProps} />
    </ChakraProvider>
  );
}

export default MyApp;