NextJS 14(TS)中next-themes主题切换器适配系统设置并支持点击切换

核心配置调整 #

next-themes默认就支持「优先用户手动选择，无选择时用系统偏好」的逻辑，你只需要确保ThemeProvider的配置正确：

1. _app.jsx/tsx中的ThemeProvider配置
   不要硬指定固定主题，显式开启系统偏好检测，同时设置适配CSS框架的属性：

   import { ThemeProvider } from 'next-themes'
   
   export default function App({ Component, pageProps }) {
     return (
       <ThemeProvider
         enableSystem={true} // 开启系统主题检测
         attribute="class" // 用class属性切换主题，适配Tailwind等主流框架
         defaultTheme="system" // 首次无用户选择时，自动匹配系统偏好
       >
         <Component {...pageProps} />
       </ThemeProvider>
     )
   }
   

主题切换组件的正确写法 #

使用useTheme钩子实现切换，切换后用户选择会自动存入localStorage，后续访问会优先读取该值：

import { useTheme } from 'next-themes'

export default function ThemeToggle() {
  const { theme, setTheme } = useTheme()

  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      {theme === 'dark' ? '切换到浅色' : '切换到深色'}
    </button>
  )
}

常见问题排查 #

• 若之前硬设defaultTheme为dark/light，会覆盖系统偏好，改成system即可。
• 手动切换后，检查浏览器localStorage是否存在theme键，该键值会优先于系统偏好生效。
• 不要自定义干扰theme键的localStorage逻辑，next-themes默认依赖该键存储用户选择。

验证逻辑 #

1. 首次访问：清空浏览器localStorage，打开网站会自动匹配系统的明暗主题设置。
2. 手动切换：点击切换器后，localStorage会存入用户选择的主题，后续即使系统主题变化，网站也会保持用户手动选择的主题。

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