Nuxt 3生产环境（SSR/静态生成）组件重复渲染问题求助

问题根源 #

SSR或静态生成模式下，服务器渲染时Pinia Store使用初始状态（user: null, isAuthenticated: false），而客户端会通过pinia-plugin-persistedstate恢复localStorage中的持久化状态（比如已登录状态）。这会导致服务器生成的DOM与客户端水合时的DOM不一致，Nuxt为了修复这个不匹配，会强制重新渲染组件，表现为“两次渲染”。

开发环境下因为以客户端即时渲染为主，视觉上无异常，但直接使用localStorage时会触发服务器端无法访问localStorage的报错。

修复方案 #

方案1：手动控制持久化状态的客户端初始化时机

放弃直接在Store中配置persist: process.client，改用Nuxt客户端插件+手动同步localStorage的方式，确保状态恢复在水合完成后执行：

1. 创建客户端专属插件（~/plugins/auth-persist.client.ts）

import { useAuthStore } from '~/stores/auth';

export default defineNuxtPlugin(() => {
  const authStore = useAuthStore();

  // 仅在客户端执行，且在DOM挂载完成后恢复状态
  onMounted(() => {
    const savedAuthState = localStorage.getItem('auth');
    if (savedAuthState) {
      authStore.$patch(JSON.parse(savedAuthState));
    }
  });
});

2. 修改Store的actions，手动同步localStorage

import { defineStore } from "pinia";
import type { User } from "~/types/User";

export const useAuthStore = defineStore("auth", {
  state: () => ({
    user: null as User | null,
    isAuthenticated: false,
  }),

  actions: {
    login(user: User) {
      this.$patch({
        user: user,
        isAuthenticated: true,
      });
      // 客户端才执行localStorage写入
      if (process.client) {
        localStorage.setItem('auth', JSON.stringify(this.$state));
      }
    },

    logout() {
      this.$patch({
        user: null,
        isAuthenticated: false,
      });
      if (process.client) {
        localStorage.removeItem('auth');
      }
    },

    decreaseActions() {
      if (this.user) {
        this.user.games_left -= 1;
        // 如果需要持久化games_left的变化，也要同步到localStorage
        if (process.client) {
          localStorage.setItem('auth', JSON.stringify(this.$state));
        }
      } else {
        console.log("decreasing action while not logged out, that's a bug");
      }
    },
  },
});

方案2：正确配置pinia-plugin-persistedstate插件

确保插件仅在客户端注册，避免服务器端执行持久化逻辑：

1. 在nuxt.config.ts中配置客户端插件

export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
  pinia: {
    autoImports: ['defineStore', 'storeToRefs'],
  },
  // 仅在客户端加载持久化插件
  plugins: [
    { src: '~/plugins/pinia-persist.client.ts', mode: 'client' }
  ]
});

2. 创建持久化插件文件（~/plugins/pinia-persist.client.ts）

import { createPersistedState } from 'pinia-plugin-persistedstate';
import { usePinia } from '@pinia/nuxt';

export default defineNuxtPlugin(() => {
  const pinia = usePinia();
  // 注册持久化插件，仅在客户端生效
  pinia.use(createPersistedState({
    key: (storeId) => `persisted_${storeId}`,
  }));
});

3. 修改Store的persist配置

export const useAuthStore = defineStore("auth", {
  state: () => ({
    user: null as User | null,
    isAuthenticated: false,
  }),

  persist: true, // 现在插件仅在客户端运行，无需process.client判断
  // ...actions
});

原理说明 #

两种方案核心都是让服务器端和客户端水合阶段使用完全一致的初始状态，待水合完成后再恢复客户端的持久化状态。这样Nuxt不会因为DOM不匹配触发强制重新渲染，而是通过状态更新正常触发组件渲染，解决“两次渲染”的问题。

内容的提问来源于stack exchange，提问作者David 天宇 Wong