NextJS中Redux-Toolkit结合localStorage主题持久化故障排查

问题核心 #

切换到dark主题后刷新页面，Redux初始状态在SSR阶段无法读取localStorage，导致页面默认回到light主题，无法保留用户设置的主题。

具体修复步骤 #

1. 在客户端初始化时同步localStorage到Redux #

修改StoreProvider代码，添加客户端专属的初始化逻辑，读取localStorage中的主题并同步到Redux store：

"use client"
import { AppStore, makeStore } from "@/lib/store"
import { useRef, useEffect } from "react"
import { Provider } from "react-redux"
import { setTheme } from "@/providers/ThemeProvider/model/reducer/themeSlice"

export default function StoreProvider({
    children
}: {
    children: React.ReactNode
}) {
    const storeRef = useRef<AppStore>()
    if (!storeRef.current) {
        storeRef.current = makeStore()
    }

    useEffect(() => {
        // 客户端渲染完成后，读取本地存储的主题并同步到Redux
        const savedTheme = localStorage.getItem("theme") || "light"
        storeRef.current?.dispatch(setTheme(savedTheme))
    }, [])

    return <Provider store={storeRef.current}>{children}</Provider>
}

2. 优化themeSlice初始状态（可选，避免hydrate不匹配警告） #

将初始状态统一设为light，后续由客户端同步localStorage的值，避免服务端与客户端初始状态不一致导致的React警告：

import { createSlice } from "@reduxjs/toolkit"

const initialState = {
    theme: "light"
}

export const themeSlice = createSlice({
    name: "theme",
    initialState,
    reducers: {
        setTheme: (state, action) => {
            state.theme = action.payload
            if (typeof window !== "undefined") {
                localStorage.setItem("theme", action.payload)
            }
        }
    }
})

export const { setTheme } = themeSlice.actions

export default themeSlice.reducer

3. 确保主题Provider响应Redux状态变化 #

检查MyThemeProvider是否正确订阅Redux的主题状态，比如结合MUI的主题配置：

"use client"
import { useAppSelector } from "@/lib/hooks/useAppSelector"
import { useEffect } from "react"
import { ThemeProvider as MuiThemeProvider, createTheme } from "@mui/material/styles"

export default function MyThemeProvider({ children }: { children: React.ReactNode }) {
    const themeMode = useAppSelector(state => state.theme.theme)
    const theme = createTheme({
        palette: {
            mode: themeMode as "light" | "dark"
        }
    })

    // 同步html根元素的class，方便全局样式适配
    useEffect(() => {
        document.documentElement.classList.toggle("dark", themeMode === "dark")
    }, [themeMode])

    return <MuiThemeProvider theme={theme}>{children}</MuiThemeProvider>
}

修复原理 #

Next.js SSR过程中，服务端初始化store时无法访问浏览器的localStorage，因此初始状态固定为light。客户端hydrate阶段会复用服务端的store状态，不会自动读取localStorage。通过在StoreProvider的useEffect中手动同步localStorage的主题值到Redux，就能确保客户端渲染时使用用户之前设置的主题，刷新后也能持久保留。

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