Vue 3+Inertia SSR布局文件引发Hydration节点不匹配问题求助

问题根源分析 #

• 全局布局的SSR上下文不一致：在app.js中直接配置全局布局时，服务端渲染阶段Inertia的页面上下文（如$page对象）可能未完全初始化，导致服务端生成的DOM结构和客户端hydrate后的结构出现差异。
• 全局布局注册方式错误：如果直接通过app.component注册全局布局，Inertia的SSR服务端渲染器可能无法正确识别该组件，造成服务端输出的HTML不含布局DOM，而客户端hydrate时自动添加布局，引发节点不匹配。
• 插槽渲染时序差异：服务端渲染全局布局的插槽内容时，与客户端的渲染逻辑存在细微时序差（比如服务端先渲染布局再插入页面内容，客户端则相反），最终导致DOM结构不一致。

具体解决办法 #

1. 改用Inertia官方推荐的全局布局配置方式 #

不要在app.js中直接注册全局组件，而是通过Inertia的resolve回调统一设置全局布局：

// app.js
createInertiaApp({
  resolve: name => {
    const page = require(`./Pages/${name}`).default
    // 所有页面默认使用全局布局，页面指定layout: null的除外
    page.layout = page.layout || require('./Layouts/Layout.vue').default
    return page
  },
  // 保留其他原有配置
})

这种方式能确保服务端和客户端渲染时，布局的加载、渲染逻辑完全一致，避免上下文差异。

2. 同步服务端SSR配置 #

打开ssr.js，确保里面也正确引入布局组件，并和app.js保持一致的resolve回调配置：

// ssr.js
import { createSSRApp } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import Layout from './Layouts/Layout.vue'

createInertiaApp({
  resolve: name => {
    const page = require(`./Pages/${name}`).default
    page.layout = page.layout || Layout
    return page
  },
  setup({ App, props, plugin }) {
    return createSSRApp({ render: () => h(App, props) })
      .use(plugin)
  },
  // 保留其他原有配置
})

同时可以查看浏览器的页面源代码，确认服务端返回的HTML中是否包含布局的DOM结构，如果没有，说明服务端未正确加载布局，需调整ssr.js配置。

3. 给布局根元素添加唯一标识 #

在Layout.vue的根元素上添加:key="$page.url"，帮助Vue准确匹配服务端和客户端的节点：

<!-- Layout.vue -->
<template>
  <div :key="$page.url">
    <slot />
  </div>
</template>

4. 局部使用布局测试验证 #

如果上述方法无效，可以先给Welcome.vue指定layout: null，然后在组件内部直接引入Layout使用：

<!-- Welcome.vue -->
<template>
  <Layout>
    <section>
      <h1>Welcome</h1>
    </section>
  </Layout>
</template>

<script setup>
import Layout from '@/Layouts/Layout.vue'
defineOptions({
  layout: null
})
</script>

如果这样能正常运行，说明问题出在全局布局的配置逻辑上，需进一步检查resolve回调的实现是否正确。

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